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 and typehint. 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.

Resolving a value

readerValue(%sources) returns the reader value of the option for one parse. %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.

Finally every single value of the result is passed to the type's prepare (which creates missing paths for createPathIfMissing). This happens only for the value that is finally used, default included.

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, auto, optionalValue, trigger):

readerValue(%sources)

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.

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.