NAME

Getopt::Pad::Spec::Option - One option of a spec, and how its value is resolved (internal)

DESCRIPTION

This module is internal to Getopt::Pad. It is not part of the public API and can change without notice. Programs use "GetOptions" in Getopt::Pad; this page is for people working on Getopt::Pad itself.

An option spec holds the checked settings of one option: the primary name, the aliases, the reader name, the type (a Getopt::Pad::Type instance) and the keys required, default, valid, lazyValid, group, help, multiple, hash, csv, objectlist, hidden, inherit, typehint and processValue. The meaning of each key is documented in "OPTION SPECS" in Getopt::Pad.

The constructor checks every key and their combinations, and checks and converts the default in the option's shape: a list for multiple, a mapping for hash, a list of mappings for objectlist, else a single value. An invalid default is a spec error. Spec errors start with the optional where constructor param, which the declaring Getopt::Pad::Spec::Level sets to its command path (command 'image resize': ).

Resolving a value

settledValue(%sources) returns the checked value of the option for one parse, and a reporter: a coderef that throws a problem found in the value later (by the type's verify or prepare) as a Getopt::Pad::Error worded for the value's source, option '--NAME': default value: ... for the default. The reporter is undef when neither a source nor a default set the option. readerValue(%sources) returns the value alone. %sources maps each value source (commandLine, config) to the raw values it gave, keyed by primary name. The option takes the first source that set it, in that order, or else the default. Without either, a required option throws a Getopt::Pad::Error, and any other option reads as an empty list (multiple, objectlist), an empty mapping (hash) or undef.

The raw value is brought into the option's shape: the words of a csv option and a single config value are split at commas, and the INDEX.FIELD=VALUE pairs of an objectlist option are collected into its list of mappings. Then every single value passes checkValue: the type's check and coerce, the valid list and the lazyValid predicate. Problems are thrown as Getopt::Pad::Error, worded for their source (option '--NAME': ... or config value for 'NAME': ...) and naming the key or entry for hash and objectlist options.

The type's verify and prepare are not called here: the parser calls them on the settled values of every selected level, see "Second pass: the values" in Getopt::Pad::Parser.

processedValue($result, $value) runs the processValue coderef on that reader value: every single value in it is replaced by what the coderef returns when called with $result and the value, the list or mapping around them is kept (see processedWith in Getopt::Pad::Util). An unset single value (undef) is left alone. Without processValue the value is returned as it is.

METHODS

Besides the readers of its settings (name, aliases, reader, type, typeName, required, hasDefault, default, valid, group, help, multiple, hash, csv, objectlist, hidden, inherit, typehint, processValue, auto, optionalValue, trigger):

settledValue(%sources), readerValue(%sources)

See "Resolving a value".

processedValue($result, $value)

See "Resolving a value".

checkValue($value)

Checks one single value; returns the problem (or undef) and the converted value.

validValues

The values the valid key allows right now: the static list, or what the coderef returns (a spec error unless it returns an arrayref). Empty without valid. Shell completion uses it too.

typeLabel

The tag the help output shows: typehint, or the type's label.

presentedDefault

The default as the help output and --create-default-config show it: as the spec wrote it, unchecked and unconverted. A converted value may not read back in (a duration converted to seconds) or be an object.

spelling

The primary name as it is typed: with one dash for a name of one letter (-v), else with two (--verbose). Command line errors name the option this way.

takesPairs

Whether the option collects KEY=VALUE words (hash and objectlist).

glSpec, negatable

The Getopt::Long specification of the option, and whether it can be negated, both from its type.

Automatic options are option specs with auto set; they may carry a trigger (see Getopt::Pad::Spec), and --config has optionalValue.

SEE ALSO

Getopt::Pad::Spec::Level, Getopt::Pad::Type

AUTHOR

davenonymous <perl@davenonymous.com>

COPYRIGHT AND LICENSE

Copyright 2026 davenonymous

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.