CONSTRUCTION ONLY

applicable => sub { ... }

This is callback is used by the "applicable()" method.

    option foo => (
        ...,
        applicable => sub {
            my ($opt, $options) = @_;
            ...
            return $bool;
        },
    );
    

READ-ONLY

$class->new(prefix => 'my_prefix')

$scalar = $opt->prefix()

A prefix is required. All options have their values inserted into the settings structure, an instance of Test2::Harness::Settings. The structure is "$settings->PREFIX->OPTION".

If you do not specify a "name" attribute then the default name will be "PREFIX-TITLE". The name is the main command line argument, so "--PREFIX-TITLE" is the default name.

$class->new(type => $type)

$type = $opt->type()

All options must have a type, if non is specified the default is 'b' aka boolean.

Here are all the possible types, along with their aliases. You may use the type character, or any of the aliases to specify that type.

$class->new(title => 'my_title')

$title = $opt->title()

You MUST specify either a title, or BOTH a name and field. If you only specify a title it will be used to generate the name and field.

If your title is 'foo-bar_baz' then your field will be 'foo_bar_baz' and your name will be '$PREFIX-foo-bar-baz'.

Basically title is used to generate a sane field and/or name if niether are specified. For field all dashes are changed to underscores. The field is used as a key in the settings: "$settings->prefix->field". For the name all underscores are changed to dashes, if the option is provided by a plugin then 'prefix-' is prepended as well. The name is used for the command line argument '--name'.

If you do not want/like the name and field generated from a title then you can specify a name or title directly.

$class->new(name => 'my-name')

$name = $opt->name()

You MUST specify either a title, or BOTH a name and field. If you only specify a title it will be used to generate the name and field.

This name is used as your primary command line argument. If your name is "foo" then your command line argument is "--foo".

$class->new(field => 'my_field')

$field = $opt->field()

You MUST specify either a title, or BOTH a name and field. If you only specify a title it will be used to generate the name and field.

The field is used in the settings hash. If your field is "foo" then your settings path is "$setting->prefix->foo".

OPTIONAL

$class->new(action => sub ...)

$coderef = $opt->action()

    option foo => (
        ...,
        action => sub {
            my ($prefix, $field_name, $raw_value, $normalized_value, $slot_ref, $settings, $handler, $options) = @_;

            # If no action is specified the following is all that is normally
            # done. Having an action means this is not done, so if you want the
            # value stored you must call this or similar.
            $handler->($slot, $normalized_value);
        },
    );
    

$class->new(adds_options => $bool)

$bool = $opt->adds_options()

If this is true then it means using this option could result in more options being available (example: Loading a plugin).

$class->new(alt => ['alt1', 'alt2', ...])

$arrayref = $opt->alt()

Provide alternative names for the option. These are aliases that can be used to achieve the same thing on the command line. This is mainly useful for backcompat if an option is renamed.

$class->new(builds => 'My::Class')

$my_class = $opt->builds()

If this option is used in the construction of another object (such as the group it belongs to is composed of options that translate 1-to-1 to fields in another object to build) then this can be used to specify that. The ultimate effect is that an exception will be thrown if that class does not have the correct attribute. This is a safety net to catch errors early if field names change, or are missing between this representation and the object being composed.

$class->new(category => 'My Category')

$category = $opt->category()

This is used to sort/display help and POD documentation for your option. If you do not provide a category it is set to 'NO CATEGORY - FIX ME'. The default value makes sure everyone knows that you do not know what you are doing :-).

$class->new(clear_env_vars => $bool)

$bool = $opt->clear_env_vars()

This option is only useful when paired with the "env_vars" attribute.

Example:

    option foo => (
        ...
        env_vars => ['foo', 'bar', 'baz'],
        clear_env_vars => 1,
    ):
    

In this case you are saying option foo can be set to the value of $ENV{foo}, $ENV{bar}, or $ENV{baz} vars if any are defined. The "clear_env_vars" tell it to then delete the environment variables after they are used to set the option. This is useful if you want to use the env var to set an option, but do not want any tests to be able to see the env var after it is used to set the option.

$class->new(default => $scalar)

$class->new(default => sub { return $default })

$scalar_or_coderef = $opt->default()

This sets a default value for the field in the settings hash, the default is set before any command line processing is done, so if the option is never used in the command line the default value will be there.

Be sure to use the correct default value for your type. A scalar for 's', an arrayref for 'm', etc.

Note, for any non-scalar type you want to use a subref to define the value:

    option foo => (
        ...
        type => 'm',
        default => sub { [qw/a b c/] },
    );
    

$class->new(description => "Fe Fi Fo Fum")

$multiline_string = $opt->description()

Description of your option. This is used in help output and POD. If you do not provide a value the default is 'NO DESCRIPTION - FIX ME'.

$class->new(env_vars => \@LIST)

$arrayref = $opt->env_vars()

If set, this should be an arrayref of environment variable names. If any of the environment variables are defined then the settings will be updated as though the option was provided onthe command line with that value.

Example:

    option foo => (
        prefix => 'blah',
        type => 's',
        env_vars => ['FOO', 'BAR'],
    );
    

Then command line:

    FOO="xxx" yath test
    

Should be the same as

    yath test --foo "xxx"
    

You can also ask to have the environment variables cleared after they are checked:

    option foo => (
        prefix => 'blah',
        type => 's',
        env_vars => ['FOO', 'BAR'],
        clear_env_vars => 1, # This tells yath to clear the env vars after they
        are used.
    );
    

If you would like the option set to the opposite of the envarinment variable you can prefix it with a '!' character:

    option foo =>(
        ...
        env_vars => ['!FOO'],
    );
    

In this case these are equivelent:

    FOO=0 yath test
    yath test --foo=1
    

Note that this only works when the variable is defined. If $ENV{FOO} is not defined then the variable is not used.

$class->new(from_command => 'App::Yath::Command::COMMAND')

$cmd_class = $opt->from_command()

If your option was defined for a specific command this will be set. You do not normally set this yourself, the tools in App::Yath::Options usually handle that for you.

$class->new(from_plugin => 'App::Yath::Plugin::PLUGIN')

$plugin_class = $opt->from_plugin()

If your option was defined for a specific plugin this will be set. You do not normally set this yourself, the tools in App::Yath::Options usually handle that for you.

$class->new(long_examples => [' foo', '=bar', ...])

$arrayref = $opt->long_examples()

Used for documentation purposes. If your option takes arguments then you can give examples here. The examples should not include the option itself, so "--foo bar" would be wrong, you should just do " bar".

$class->new(negate => sub { ... })

$coderef = $opt->negate()

If you want a custom handler for negation "--no-OPT" you can provide one here.

    option foo => (
        ...
        negate => sub {
            my ($prefix, $field, $slot, $settings, $options) = @_;

            ...
        },
    );
    

The variables are the same as those in the "action" callback.

$class->new(normalize => sub { ... })

$coderef = $opt->normalize()

The normalize attribute holds a callback sub that takes the raw value as input and returns the normalized form.

    option foo => (
        ...,
        normalize => sub {
            my $raw = shift;

            ...

            return $norm;
        },
    );
    

$class->new(pre_command => $bool)

$bool = $opt->pre_command()

Options are either command-specific, or pre-command. Pre-command options are ones yath processes even if it has not determined what comamnd is being used. Good examples are "--dev-lib" and "--plugin".

    yath --pre-command-opt COMMAND --command-opt
    

Most of the time this should be false, very few options qualify as pre-command.

$class->new(pre_process => sub { ... })

$coderef = $opt->pre_process()

This is essentially a BEGIN block for options. This callback is called as soon as the option is parsed from the command line, well before the value is normalized and added to settings. A good use for this is if your option needs to inject additional App::Yath::Option instances into the App::Yath::Options instance.

    option foo => (
        ...

        pre_process => sub {
            my %params = @_;

            my $opt     = $params{opt};
            my $options = $params{options};
            my $action  = $params{action};
            my $type    = $params{type};
            my $val     = $params{val};

            ...;
        },
    );
    

Explanation of paremeters:

$class->new(short => $single_character_string)

$single_character_string = $opt->short()

If you want your option to be usable as a short option (single character, single dash "-X") then you can provide the character to use here. If the option does not require an argument then it can be used along with other no-argument short options: "-xyz" would be equivilent to "-x -y -z".

There are only so many single-characters available, so options are restricted to picking only 1.

Please note: Yath reserves the right to add any single-character short options in the main distribution, if they conflict with third party plugins/commands then the third party must adapt and change its options. As such it is not recommended to use any short options in third party addons.

$class->new(short_examples => [' foo', ...])

$arrayref = $opt->short_examples()

Used for documentation purposes. If your option takes arguments then you can give examples here. The examples should not include the option itself, so "-f bar" would be wrong, you should just do " bar".

This attribute is not used if you do not provide a "short" attribute.

$class->new(trace => [$package, $file, $line])

$arrayref = $opt->trace()

This is almost always auto-populated for you via "caller()". It should be an arrayref with a package, filename and line number. This is used if there is a conflict between parameter names and/or short options. If such a situation arises the file/line number of all conflicting options will be reported so it can be fixed.

DOCUMENTATION GENERATION

$string = $opt->cli_docs()

Get the option documentation in a format that works for the "yath help COMMAND" command.

$string = $opt->pod_docs()

Get the option documentation in POD format.

    =item ....

    .. option details ...