|
OptionParserInternals
Internal mechanics of OptionParser.pm
SynopsisThe common module OptionParser.pm is responsible for converting a script's POD OPTIONS items to Getopt::Long option specs and parsing command line arguments from @ARGV accordingly. The goal is to derive the command-line help output from the options that are accepted, and to derive the options from the POD, so there is no duplication and everything always stays in sync. It is like an advanced version of pod_to_usage(). Format of Options in the PODEach option in the OPTIONS secion of the POD must have the following form to be parsed correctly: =item --OPTION_NAME ATTRIBUTES HELP_DESCRIPTION FULL_DESCRIPTION OPTION_NAME is the full (long) name of the option, like --foo. Optionally, the name can be prefixed with [no] (--[no]foo) to make the option negatable. ATTRIBUTES is a single, optional line that allows you to specify the following attributes:
short form: -w; type: time; default: 5m HELP_DESCRIPTION is a single line that briefly describes the option. It is what --help prints about the option. Technically, it is optional if there is at least one sentence in FULL_DESCRIPTION. In such a case, that first full period-terminated sentence in FULL_DESCRIPTION is printed by --help. FULL_DESCRIPTION is optional (unless, as noted above, no HELP_DESCRIPTION is given). Here you can write your novel about the gory details of the option. Option TypesThere are a few different data types that you can specify for an option.
The difference between an Array, array, Hash and hash is only in the type of the value you get from OptionParser::get(). All of them accept a comma-separated list. The ones that are lowercase will return undef if the option wasn't given. The uppercase ones will return an empty but defined value if an option wasn't given. Magical InstructionsThe POD can contain three kinds of magical instructions: magically named paragraphs of text, embedded instructions within an option, and instructions that precede options. Magic ParagraphsA magic paragraph is the paragraph following some magic word. You can retrieve it with the read_para_after() method. For an example, see mk-query-digest and look for MAGIC_createreview (the magic word). You just have to embed the magic word in the preceding paragraph, and then specify it in the call to read_para_after(). Embedded InstructionsThe command-line option's description can have special words in it to instruct the OptionParser to treat it a certain way. Note that when embedded in the POD, "the description" means the first sentence in the item's documentation. Here are the behaviors:
Magical embedded instructions such as "disables --foo" can have embedded POD links in them, too. So you can also say 'disables L<"--foo">' so the POD will linkify it. Instructions That Precede OptionsYou can put some paragraphs right after the OPTIONS heading, and before the list of options. These are examined for magical instructions about the options.
--config: The Magical, Meta-option--config has an intrinsic, hard-coded rule: if given, it must be the first option on the command line. OptionParser enforces this rule automatically when the --config option appears in a script. Therefore, this rule does not need to be stated in the POD, but it should be mentioned like: =item --config type: Array Read this comma-separated list of config files. If specified, this must be the first option on the command line. --config must be type Array (this is not intrinsic or automatically enforeced). See also ConfigurationFiles. |
