NAME

Getopt::Yath::Tutorial - A step-by-step guide to using Getopt::Yath

DESCRIPTION

This tutorial walks you through using Getopt::Yath to handle command-line options in your Perl scripts and modules. It starts with simple examples and builds up to advanced features.

YOUR FIRST SCRIPT

Here is the simplest useful script with Getopt::Yath:

#!/usr/bin/perl
use strict;
use warnings;
use Getopt::Yath;

option_group {group => 'my', category => 'My Options'} => sub {

    option name => (
        type        => 'Scalar',
        description => 'Your name',
    );

};

my $state = parse_options(\@ARGV);
my $settings = $state->settings;

print "Hello, " . ($settings->my->name // 'World') . "!\n";

Run it:

$ perl hello.pl --name Bob
Hello, Bob!

$ perl hello.pl
Hello, World!

What just happened?

use Getopt::Yath exports several functions into your package:

option: Define a single command-line option with a name and specification.
option_group: Set shared attributes (group, category, prefix, etc.) for a block of options.
parse_options: Process an arrayref of command-line arguments and return a state hashref with settings, remaining args, skipped items, and more.
include_options: Import option definitions from another module that also uses Getopt::Yath.
option_post_process: Register a callback to run after all options have been parsed, for cross-option validation or fixups.
options: Return the Getopt::Yath::Instance object that holds all defined options. Used for generating help and documentation output.
category_sort_map: Control the display order of option categories in help output.

Every option needs a group (the key under which it appears in settings) and a type (how it parses arguments). The category is a human-readable label used for help output.

OPTION GROUPS

option_group lets you set shared attributes for a block of options so you don't have to repeat yourself:

option_group {group => 'server', category => 'Server Options'} => sub {

    option host => (
        type        => 'Scalar',
        default     => 'localhost',
        description => 'Hostname to bind to',
    );

    option port => (
        type        => 'Scalar',
        short       => 'p',
        default     => 8080,
        description => 'Port to listen on',
    );

    option verbose => (
        type        => 'Bool',
        short       => 'v',
        description => 'Enable verbose output',
    );

};

my $state = parse_options(\@ARGV);
my $settings = $state->settings;

printf "Starting server on %s:%s\n",
    $settings->server->host,
    $settings->server->port;

Every option declared inside this block inherits group => 'server' and category => 'Server Options'. The parsed values are accessed via $settings->server->host, $settings->server->port, etc.

OPTION TYPES

Getopt::Yath provides a rich set of option types. Here they are from simplest to most specialized.

Bool

A simple on/off flag. No argument needed.

option verbose => (
    type        => 'Bool',
    short       => 'v',
    default     => 0,
    description => 'Enable verbose output',
);

Usage:

--verbose       # turns it on (1)
-v              # same thing
--no-verbose    # turns it off (0)

Scalar

Takes exactly one value.

option output => (
    type        => 'Scalar',
    short       => 'o',
    description => 'Output file path',
);

Usage:

--output results.txt
--output=results.txt
-o results.txt
-o=results.txt
-oresults.txt       # short form allows value directly after flag
--no-output         # clears the value (sets to undef)

Count

An incrementing counter. Each use bumps the value by one.

option verbosity => (
    type        => 'Count',
    short       => 'v',
    initialize  => 0,
    description => 'Increase verbosity level',
);

Usage:

-v          # 1
-vvv        # 3 (short flags can be stacked)
--verbosity # 1
-v -v -v    # 3
-v=5        # explicitly set to 5
--no-verbosity  # reset to 0

List

Collects multiple values into an arrayref. Can be specified multiple times.

option include => (
    type        => 'List',
    short       => 'I',
    description => 'Add a directory to the include path',
);

Usage:

-I lib -I blib/lib
--include lib --include blib/lib
--no-include    # empties the list

Lists also accept JSON arrays:

--include '["lib","blib/lib"]'

Splitting values

Use split_on to allow comma-separated (or other delimiter) values:

option tags => (
    type        => 'List',
    split_on    => ',',
    description => 'Comma-separated list of tags',
);

# --tags foo,bar,baz   =>   ['foo', 'bar', 'baz']

Map

Collects key=value pairs into a hashref. Can be specified multiple times.

option env_var => (
    type        => 'Map',
    short       => 'E',
    alt         => ['env-var'],
    description => 'Set an environment variable',
);

Usage:

-E HOME=/tmp -E USER=test
--env-var HOME=/tmp
--env-var '{"HOME":"/tmp","USER":"test"}'   # JSON also works
--no-env-var    # empties the hash

Like List, Map supports split_on for multiple pairs in one argument, and key_on to change the key/value delimiter (default is =).

Auto

A scalar option with an autofill value. --opt uses the autofill value, --opt=val uses the provided value. Does not support --opt val (the space-separated form), because without a required argument the next token is ambiguous.

option coverage => (
    type        => 'Auto',
    autofill    => '-silent,1',
    description => 'Enable coverage; optionally provide Devel::Cover args',
    long_examples  => ['', '=-silent,1'],
);

Usage:

--coverage          # uses autofill: "-silent,1"
--coverage=-db,cov  # uses the provided value
--no-coverage       # clears

AutoList

Combines Auto and List. --opt adds the autofill values to the list. --opt=val adds a specific value.

option plugins => (
    type        => 'AutoList',
    autofill    => sub { qw/Foo Bar/ },
    description => 'Plugins to load (defaults to Foo and Bar)',
);

Usage:

--plugins           # adds 'Foo' and 'Bar'
--plugins=Baz       # adds 'Baz'
--no-plugins        # empties the list

AutoMap

Combines Auto and Map. --opt adds the autofill key/value pairs. --opt=key=val adds a specific pair.

option defaults => (
    type        => 'AutoMap',
    autofill    => sub { timeout => 30, retries => 3 },
    description => 'Default settings',
);

Usage:

--defaults              # adds {timeout => 30, retries => 3}
--defaults=color=red    # adds {color => 'red'}
--no-defaults           # empties the hash

PathList

Like List, but values containing wildcards are expanded using glob().

option test_files => (
    type        => 'PathList',
    split_on    => ',',
    description => 'Test files to run (globs allowed)',
);

Usage:

--test-files 't/*.t'
--test-files t/foo.t,t/bar.t
--test-files 'lib/**/*.pm'

AutoPathList

Combines AutoList and PathList. --opt adds autofill paths, --opt=glob expands the glob.

option dev_libs => (
    type        => 'AutoPathList',
    short       => 'D',
    name        => 'dev-lib',
    autofill    => sub { 'lib', 'blib/lib', 'blib/arch' },
    description => 'Add dev library paths (default: lib, blib/lib, blib/arch)',
);

Usage:

-D              # adds lib, blib/lib, blib/arch
-D=lib          # adds just lib
-D='lib/*'      # adds all matches

BoolMap

Matches a pattern of options dynamically, building a hash of boolean values. Requires a pattern attribute with a capture group.

option features => (
    type        => 'BoolMap',
    pattern     => qr/feature-(.+)/,
    description => 'Toggle features on or off',
);

Usage:

--feature-color         # {color => 1}
--feature-unicode       # {unicode => 1}
--no-feature-color      # {color => 0}

The pattern is embedded into qr/^--(no-)?$pattern$/ automatically. Each captured key gets a true or false value depending on the --no- prefix.

COMMON OPTION ATTRIBUTES

These attributes work across all option types.

short

A single-character alias for the option:

option jobs => (
    type  => 'Scalar',
    short => 'j',
    ...
);

# -j4   --jobs 4   --jobs=4   -j 4

alt and alt_no

Alternate long names for the option:

option use_stream => (
    type   => 'Bool',
    alt    => ['stream'],       # --stream also works
    alt_no => ['TAP'],          # --TAP is equivalent to --no-use-stream
    description => 'Use streaming format instead of TAP',
);

prefix

Adds a prefix to the option name. Especially useful in option groups:

option_group {group => 'db', category => 'Database', prefix => 'db'} => sub {

    option host => (
        type => 'Scalar',
        description => 'Database host',
    );

    option port => (
        type    => 'Scalar',
        default => 5432,
        description => 'Database port',
    );

};

# --db-host myhost --db-port 3306

The values are still accessed as $settings->db->host and $settings->db->port -- the prefix only affects the command-line form.

field and name

By default, the option title determines both the field name (underscores) and the CLI name (dashes). You can override either:

option test_args => (
    type  => 'List',
    field => 'args',        # $settings->tests->args (not test_args)
    alt   => ['test-arg'],
    ...
);

default

A value used when the option is not provided on the command line and not set via an environment variable:

option timeout => (
    type    => 'Scalar',
    default => 60,
    description => 'Timeout in seconds',
);

# Can also be a coderef:
option search => (
    type    => 'PathList',
    default => sub { './t', './t2' },
    ...
);

initialize

Set an initial value before parsing begins. This differs from default in that default is applied after parsing if the option was never set, while initialize sets a starting value that can then be modified by command-line arguments.

option verbosity => (
    type       => 'Count',
    initialize => 0,
    ...
);

ENVIRONMENT VARIABLES

from_env_vars

Read an option's initial value from environment variables. The first one that is defined wins:

option verbose => (
    type          => 'Bool',
    from_env_vars => ['MYAPP_VERBOSE', 'VERBOSE'],
    description   => 'Enable verbose output',
);

Prefix a variable with ! to negate its value:

option quiet => (
    type          => 'Bool',
    from_env_vars => ['!VERBOSE'],     # quiet = true when VERBOSE is false
    description   => 'Suppress output',
);

set_env_vars

Set environment variables after parsing is complete (Bool, Scalar, Count, and Auto types only):

option cover => (
    type          => 'Auto',
    autofill      => '-silent,1',
    from_env_vars => ['T2_DEVEL_COVER'],
    set_env_vars  => ['T2_DEVEL_COVER'],
    description   => 'Enable Devel::Cover',
);

The ! prefix also works here for inverted env vars.

clear_env_vars

Clear specified environment variables after parsing:

option token => (
    type           => 'Scalar',
    from_env_vars  => ['AUTH_TOKEN'],
    clear_env_vars => ['AUTH_TOKEN'],    # don't leak to child processes
    description    => 'Auth token (cleared from env after reading)',
);

NORMALIZE AND TRIGGER

normalize

Transform a value as it is parsed:

option module => (
    type      => 'Scalar',
    normalize => sub {
        my ($val) = @_;
        $val =~ s/-/::/g;      # Allow Foo-Bar instead of Foo::Bar
        return $val;
    },
    description => 'Module name',
);

# --module Foo-Bar  =>  "Foo::Bar"

For List and Map types, normalize is called on each value individually.

trigger

A callback invoked whenever the option is set or cleared from the command line. Triggers do not fire for defaults, autofill, or initialization.

option input_file => (
    type    => 'Scalar',
    trigger => sub {
        my $opt    = shift;
        my %params = @_;

        return unless $params{action} eq 'set';
        my ($file) = @{$params{val}};
        die "File not found: $file\n" unless -f $file;
    },
    description => 'Input file',
);

The %params hash contains:

action   => 'set' or 'clear'
val      => \@values (arrayref, even for scalars)
ref      => \$field_ref
state    => $parse_state
options  => $instance
settings => $settings
group    => $group

ALLOWED VALUES

Restrict what values an option will accept:

option format => (
    type           => 'Scalar',
    allowed_values => [qw/json csv xml/],
    description    => 'Output format',
);

# --format json   # ok
# --format yaml   # dies: Invalid value

allowed_values can be an arrayref, a regex, or a coderef:

allowed_values => qr/^\d+$/,            # must be numeric
allowed_values => sub { $_[1] > 0 },    # must be positive

Use allowed_values_text to customize the help message:

allowed_values_text => 'json, csv, or xml',

PARSING OPTIONS

The parse_options function is how you process command-line arguments. It returns a state hashref with all the parsed data.

Basic parsing

my $state = parse_options(\@ARGV);

my $settings = $state->settings;     # Getopt::Yath::Settings object
my $remains  = $state->remains;      # args after a stop token
my $skipped  = $state->skipped;      # skipped non-options
my $stop     = $state->stop;         # what token stopped parsing
my $env      = $state->env;          # env vars that were/would be set
my $cleared  = $state->cleared;      # options cleared via --no-opt
my $modules  = $state->modules;      # modules whose options were used

Stops

Use stops to stop parsing at certain tokens. This is most commonly used for --:

my $state = parse_options(\@ARGV,
    stops => ['--'],
);

# perl script.pl --verbose -- --not-an-option foo bar
#   $state->stop    = '--'
#   $state->remains = ['--not-an-option', 'foo', 'bar']

You can define multiple stop tokens. :: is commonly used as a separator for passing arguments through to tests:

my $state = parse_options(\@ARGV,
    stops => ['--', '::'],
);

# perl script.pl --verbose :: --some-test-arg
#   $state->stop    = '::'
#   $state->remains = ['--some-test-arg']

Handling non-options

By default, encountering a non-option (something not starting with -) throws an error. You can change this:

# Skip non-options (collect them)
my $state = parse_options(\@ARGV,
    skip_non_opts => 1,
);
my @files = @{$state->skipped};

# Stop at first non-option
my $state = parse_options(\@ARGV,
    stop_at_non_opts => 1,
);
# $state->stop = the non-option that caused the stop
# $state->remains = everything after it

Handling invalid options

Similarly, you can control what happens with unrecognized options:

# Skip invalid options
my $state = parse_options(\@ARGV,
    skip_invalid_opts => 1,
);

# Stop at invalid options
my $state = parse_options(\@ARGV,
    stop_at_invalid_opts => 1,
);

Suppressing env var side effects

Prevent parse_options from modifying %ENV:

my $state = parse_options(\@ARGV,
    no_set_env => 1,
);

# $state->env still shows what would have been set

Argument groups

Argument groups let you collect arguments between delimiter tokens into an arrayref. This is useful for passing structured groups of values:

my $state = parse_options(\@ARGV,
    groups => { ':{' => '}:' },
);

# perl script.pl --opt :{ arg1 arg2 arg3 }:
# The :{ ... }: group is collected as ['arg1', 'arg2', 'arg3']

Groups can be used as option values or as standalone arguments (which end up in skipped when skip_non_opts is enabled).

GENERATING HELP OUTPUT

CLI help

sub show_help {
    print options()->docs('cli');
}

This produces formatted terminal output with ANSI colors (when available), organized by category.

POD documentation

sub show_pod {
    print options()->docs('pod', head => 2);
}

This produces POD markup suitable for embedding in your module's documentation. The head parameter controls the heading level (e.g., =head2).

Controlling category order

By default, categories are sorted alphabetically. Use category_sort_map to control the order:

category_sort_map(
    'General Options' => 1,
    'Server Options'  => 2,
    'Debug Options'   => 3,
);

Lower values appear first.

REUSABLE OPTION LIBRARIES

You can define options in a module and include them elsewhere. This lets you build composable option sets.

Defining an option library

package My::Options::Database;
use strict;
use warnings;
use Getopt::Yath;

option_group {group => 'db', category => 'Database Options'} => sub {

    option host => (
        type    => 'Scalar',
        default => 'localhost',
        description => 'Database hostname',
    );

    option port => (
        type    => 'Scalar',
        default => 5432,
        description => 'Database port',
    );

    option name => (
        type        => 'Scalar',
        description => 'Database name',
    );

};

1;

Including options from another module

package My::App;
use strict;
use warnings;
use Getopt::Yath;

include_options('My::Options::Database');

option_group {group => 'app', category => 'App Options'} => sub {

    option debug => (
        type        => 'Bool',
        description => 'Debug mode',
    );

};

my $state = parse_options(\@ARGV);
# $state->settings->db->host, ->db->port, etc.
# $state->settings->app->debug

Selective inclusion

You can include only specific options from a library:

include_options(
    'My::Options::Database' => [qw/host port/],
);

Only the host and port options will be included; name will be excluded.

POST-PROCESSING

option_post_process registers a callback that runs after all options have been parsed but before environment variables are set. This is useful for validation that depends on multiple options:

option_post_process sub {
    my ($instance, $state) = @_;

    my $settings = $state->settings;
    my $server   = $settings->server;

    if ($server->ssl && !$server->cert_file) {
        die "--ssl requires --cert-file\n";
    }
};

Weighted post-processors

The first argument is a weight that controls execution order (lower runs first, default is 0):

option_post_process 10 => sub {
    my ($instance, $state) = @_;
    # Runs after weight-0 post-processors
};

Conditional post-processors

An optional applicable coderef controls whether the post-processor runs:

option_post_process 0 => sub { ... if server group exists ... } => sub {
    my ($instance, $state) = @_;
    ...
};

If used inside an option_group block, the group's applicable is inherited automatically.

DYNAMIC OPTIONS WITH mod_adds_options

Some options specify a module name whose options should be dynamically loaded when the option is used:

option runner_class => (
    type             => 'Scalar',
    name             => 'runner',
    field            => 'class',
    default          => 'My::Runner',
    mod_adds_options => 1,
    normalize        => sub { fqmod($_[0], 'My::Runner') },
    description      => 'Runner class to use',
);

When --runner=My::Custom::Runner is specified, the module is loaded, and if it has an options() method, those options are included into the current instance. This allows plugins and extensions to contribute their own command-line options.

APPLICABILITY

Options can be conditionally shown/hidden based on runtime state:

option reloader => (
    type       => 'Auto',
    autofill   => 'My::Reloader',
    applicable => sub {
        my ($opt, $options, $settings) = @_;
        return $settings->runner->preloads && @{$settings->runner->preloads};
    },
    description => 'Module reloader (only available with preloads)',
);

When applicable returns false, the option is excluded from parsing and documentation.

THE SETTINGS OBJECT

The $state->settings value is a Getopt::Yath::Settings object. Groups are accessed as methods:

$settings->server->host;
$settings->db->port;

Useful methods:

# Check if a group exists
if ($settings->check_group('server')) { ... }

# Safe access with a default
my $val = $settings->maybe('server', 'host', 'localhost');

COMPLETE EXAMPLE

Here is a complete script demonstrating many features together:

#!/usr/bin/perl
use strict;
use warnings;
use Getopt::Yath;

option_group {group => 'app', category => 'Application Options'} => sub {

    option verbose => (
        type          => 'Count',
        short         => 'v',
        initialize    => 0,
        from_env_vars => ['MYAPP_VERBOSE'],
        set_env_vars  => ['MYAPP_VERBOSE'],
        description   => 'Increase verbosity (-v, -vv, -vvv)',
    );

    option config => (
        type        => 'Scalar',
        short       => 'c',
        description => 'Path to config file',
        trigger     => sub {
            my $opt    = shift;
            my %params = @_;
            return unless $params{action} eq 'set';
            my ($file) = @{$params{val}};
            die "Config file not found: $file\n" unless -f $file;
        },
    );

    option output_format => (
        type           => 'Scalar',
        short          => 'f',
        default        => 'json',
        allowed_values => [qw/json csv xml/],
        description    => 'Output format',
    );

    option tags => (
        type        => 'List',
        short       => 't',
        split_on    => ',',
        description => 'Tags to apply (comma-separated)',
    );

    option env_vars => (
        type        => 'Map',
        short       => 'E',
        description => 'Extra environment variables (KEY=VAL)',
    );

    option dry_run => (
        type        => 'Bool',
        short       => 'n',
        default     => 0,
        description => 'Dry run, do not make changes',
    );

};

option_group {group => 'files', category => 'File Options'} => sub {

    option include => (
        type        => 'PathList',
        short       => 'I',
        description => 'Files to include (globs allowed)',
    );

};

category_sort_map(
    'Application Options' => 1,
    'File Options'        => 2,
);

option_post_process sub {
    my ($instance, $state) = @_;
    my $settings = $state->settings;

    if ($settings->app->dry_run && $settings->app->verbose < 1) {
        warn "Note: --dry-run without --verbose; enabling verbose=1\n";
        $settings->app->option(verbose => 1);
    }
};

# Show help if requested
if (grep { $_ eq '--help' || $_ eq '-h' } @ARGV) {
    print options()->docs('cli');
    exit 0;
}

my $state = parse_options(\@ARGV,
    stops         => ['--', '::'],
    skip_non_opts => 1,
);

my $settings = $state->settings;

printf "Verbosity: %d\n", $settings->app->verbose;
printf "Format: %s\n",    $settings->app->output_format;
printf "Dry run: %s\n",   $settings->app->dry_run ? 'yes' : 'no';

if (my $tags = $settings->app->tags) {
    printf "Tags: %s\n", join(', ', @$tags) if @$tags;
}

if (my @files = @{$state->skipped}) {
    printf "Files: %s\n", join(', ', @files);
}

if ($state->stop) {
    printf "Stopped at: %s\n", $state->stop;
    printf "Remaining: %s\n", join(' ', @{$state->remains});
}

ADVANCED: MULTI-STAGE PARSING WITH SUBCOMMANDS

Many tools follow a script [GLOBAL OPTIONS] subcommand [COMMAND OPTIONS] pattern, where the script has its own set of options, a subcommand name, and then the subcommand has its own options. Getopt::Yath supports this through multi-stage parsing: parse the global options first (stopping at the subcommand), then load the subcommand and parse its options from the remaining arguments.

Step 1: Define global options

Create a package for your script-level options.

package My::CLI;
use strict;
use warnings;
use Getopt::Yath;

option_group {group => 'global', category => 'Global Options'} => sub {

    option verbose => (
        type        => 'Count',
        short       => 'v',
        initialize  => 0,
        description => 'Increase verbosity',
    );

    option config => (
        type        => 'Scalar',
        short       => 'c',
        description => 'Path to config file',
    );

};

Step 2: Define subcommand option packages

Each subcommand is a separate package with its own options:

package My::CLI::Command::deploy;
use strict;
use warnings;
use Getopt::Yath;

option_group {group => 'deploy', category => 'Deploy Options'} => sub {

    option target => (
        type        => 'Scalar',
        short       => 't',
        description => 'Deployment target (staging, production)',
    );

    option dry_run => (
        type        => 'Bool',
        short       => 'n',
        default     => 0,
        description => 'Perform a dry run',
    );

};

sub run {
    my ($class, $settings) = @_;
    printf "Deploying to %s (dry_run=%s, verbose=%d)\n",
        $settings->deploy->target // 'default',
        $settings->deploy->dry_run ? 'yes' : 'no',
        $settings->global->verbose;
}

package My::CLI::Command::test;
use strict;
use warnings;
use Getopt::Yath;

option_group {group => 'test', category => 'Test Options'} => sub {

    option jobs => (
        type        => 'Scalar',
        short       => 'j',
        default     => 1,
        description => 'Number of parallel test jobs',
    );

    option tags => (
        type        => 'List',
        split_on    => ',',
        description => 'Filter tests by tag',
    );

};

sub run {
    my ($class, $settings) = @_;
    printf "Running tests with %d jobs (verbose=%d)\n",
        $settings->test->jobs,
        $settings->global->verbose;
}

Step 3: Two-stage dispatch

Parse global options first, stopping at the subcommand name. Then load the subcommand module, include its options, and parse the remaining arguments using the combined option set. Pass the settings object through so both stages share state.

package main;

my %commands = (
    deploy => 'My::CLI::Command::deploy',
    test   => 'My::CLI::Command::test',
);

# Stage 1: Parse global options, stop at the subcommand name
my $stage1 = My::CLI::parse_options(
    \@ARGV,
    stop_at_non_opts => 1,
);

my $command_name = $stage1->stop
    or die "Usage: my-cli [global options] <command> [command options]\n";

my $command_class = $commands{$command_name}
    or die "Unknown command: $command_name\n";

# Stage 2: Include command options, parse remaining args
#          Carry forward settings so global values are preserved
My::CLI::include_options($command_class);

my $stage2 = My::CLI::parse_options(
    $stage1->remains,
    settings => $stage1->settings,
);

# Dispatch — settings object has both global and command groups
$command_class->run($stage2->settings);

Example invocations

$ my-cli -vv deploy --target production --dry-run
Deploying to production (dry_run=yes, verbose=2)

$ my-cli --config app.yml test -j8 --tags smoke,unit
Running tests with 8 jobs (verbose=0)

The key techniques are:

stop_at_non_opts in Stage 1 stops parsing at the subcommand name, placing it in $state->stop and the rest in $state->remains.
include_options merges the subcommand's options into the script's option instance before Stage 2.
settings is passed from Stage 1 to Stage 2 so the global values are preserved and both stages write into the same settings object.

SOURCE

The source code repository for Getopt-Yath can be found at http://github.com/Test-More/Getopt-Yath/.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

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

See http://dev.perl.org/licenses/

To install Getopt::Yath, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Getopt::Yath

CPAN shell

perl -MCPAN -e shell
install Getopt::Yath

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

YOUR FIRST SCRIPT

What just happened?

OPTION GROUPS

OPTION TYPES

Bool

Scalar

Count

List

Splitting values

Map

Auto

AutoList

AutoMap

PathList

AutoPathList

BoolMap

COMMON OPTION ATTRIBUTES

short

alt and alt_no

prefix

field and name

default

initialize

ENVIRONMENT VARIABLES

from_env_vars

set_env_vars

clear_env_vars

NORMALIZE AND TRIGGER

normalize

trigger

ALLOWED VALUES

PARSING OPTIONS

Basic parsing

Stops

Handling non-options

Handling invalid options

Suppressing env var side effects

Argument groups

GENERATING HELP OUTPUT

CLI help

POD documentation

Controlling category order

REUSABLE OPTION LIBRARIES

Defining an option library

Including options from another module

Selective inclusion

POST-PROCESSING

Weighted post-processors

Conditional post-processors

DYNAMIC OPTIONS WITH mod_adds_options

APPLICABILITY

THE SETTINGS OBJECT

COMPLETE EXAMPLE

ADVANCED: MULTI-STAGE PARSING WITH SUBCOMMANDS

Step 1: Define global options

Step 2: Define subcommand option packages

Step 3: Two-stage dispatch

Example invocations

SEE ALSO

SOURCE

MAINTAINERS

AUTHORS

COPYRIGHT

Module Install Instructions

Keyboard Shortcuts