/ 
Getopt-Pad-0.04
/ Getopt::Pad::Parser

NAME

Getopt::Pad::Parser - Parses a command line against a spec (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.

Getopt::Pad::Parser->new(spec => $spec, argv => \@words)->parse returns the result object of the top level, or throws. It works in two passes.

First pass: the command line

The command line is read level by level, starting at the top level:

  1. Getopt::Long reads the level's options, configured with bundling, no_ignore_case, no_auto_abbrev, and require_order on a level with commands (so the first non-option word ends the level) or permute on a level without commands. Its warnings become the error message.

  2. The triggers of the automatic options set on this level run. A trigger throws a Getopt::Pad::ExitRequest, which ends the parse before anything else is checked.

  3. The values of inherited options are set aside. When the next level is read, Getopt::Long stores into a copy of them, so an inherited option given on several levels accumulates as if it had been given on one.

  4. On a level with commands, the next word selects the command, and the loop continues with that command's level.

Second pass: the values

The config values are loaded once (an explicit --config, given on any level, replaces the autoload chain). Then the selected levels are resolved from the innermost to the top level. Each declared option gets its value from the command line words of its level and the config values of its level's section (see Getopt::Pad::Spec::Option); an inherited option gets the words collected on all levels. The innermost level consumes the positional words for its args (type check, conversion, prepare). Each level's result object, created by Getopt::Pad::Result::Generator, holds the result object of the level below.

Errors

User errors are thrown as Getopt::Pad::Error objects. The parser attaches the level they happened on, so that GetOptions can print that level's help. The parser never prints and never exits; that is left to GetOptions.

SEE ALSO

Getopt::Pad::Spec, Getopt::Pad::Config

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.