.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "App::Yath::Options 3pm"
.TH App::Yath::Options 3pm 2024-03-08 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
App::Yath::Options \- Tools for defining and tracking yath CLI options.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This class represents a collection of options, and holds the logic for
processing them. This package also exports sugar to help you define options.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    package My::Options;
\&
\&    use App::Yath::Options;
\&
\&    # This package now has a package instance of options, which can be obtained
\&    # via the options() method.
\&    my $options = _\|_PACKAGE_\|_\->options;
\&
\&    # We can include options from other packages
\&    include_options(
\&        \*(AqPackage::With::Options::A\*(Aq,
\&        \*(AqPackage::With::Options::B\*(Aq,
\&        ...,
\&    );
\&
\&    # Define an option group with some options
\&    option_group { %common_fields } => sub {
\&
\&        # Define an option
\&        option foo => (
\&            type => \*(Aqs\*(Aq,
\&            default => "FOOOOOOO",
\&            category => \*(Aqfoo\*(Aq,
\&            description => "This is foo"
\&            long_examples => [\*(Aq value\*(Aq],
\&            ...
\&        );
\&
\&        option bar => ( ... );
\&        ...
\&    };
\&
\&    # Action to call right after options are parsed.
\&    post sub {
\&        my %params = @_;
\&
\&        ...
\&    };
.Ve
.SH EXPORTS
.IX Header "EXPORTS"
.ie n .IP "$opts = \fBoptions()\fR" 4
.el .IP "\f(CW$opts\fR = \fBoptions()\fR" 4
.IX Item "$opts = options()"
.PD 0
.ie n .IP "$opts = $class\->\fBoptions()\fR" 4
.el .IP "\f(CW$opts\fR = \f(CW$class\fR\->\fBoptions()\fR" 4
.IX Item "$opts = $class->options()"
.PD
This returns the options instance associated with your package.
.IP include_options(@CLASSES) 4
.IX Item "include_options(@CLASSES)"
This lets you include options defined in other packages.
.IP "option_group \e%COMMON_FIELDS => sub { ... }" 4
.IX Item "option_group %COMMON_FIELDS => sub { ... }"
An option group is simply a block where all calls to \f(CWoption()\fR will have
common fields added automatically, this makes it easier to define multiple
options that share common fields. Common fields can be overridden inside the
option definition.
.Sp
These are both equivalent:
.Sp
.Vb 5
\&    # Using option group
\&    option_group { category => \*(Aqfoo\*(Aq, prefix => \*(Aqfoo\*(Aq } => sub {
\&        option a => (type => \*(Aqb\*(Aq);
\&        option b => (type => \*(Aqs\*(Aq);
\&    };
\&
\&    # Not using option group
\&    option a => (type => \*(Aqb\*(Aq, category => \*(Aqfoo\*(Aq, prefix => \*(Aqfoo\*(Aq);
\&    option b => (type => \*(Aqs\*(Aq, category => \*(Aqfoo\*(Aq, prefix => \*(Aqfoo\*(Aq);
.Ve
.ie n .IP "option TITLE => %FIELDS" 4
.el .IP "option TITLE => \f(CW%FIELDS\fR" 4
.IX Item "option TITLE => %FIELDS"
Define an option. The first argument is the \f(CW\*(C`title\*(C'\fR attribute for the new
option, all other arguments should be attribute/value pairs used to construct
the option. See App::Yath::Option for the documentation of attributes.
.IP "post sub { ... }" 4
.IX Item "post sub { ... }"
.PD 0
.ie n .IP "post $weight => sub { ... }" 4
.el .IP "post \f(CW$weight\fR => sub { ... }" 4
.IX Item "post $weight => sub { ... }"
.PD
\&\f(CW\*(C`post\*(C'\fR callbacks are run after all command line arguments have been processed.
This is a place to verify the result of several options combined, sanity check,
or even add short-circuit behavior. This is how the \f(CW\*(C`\-\-help\*(C'\fR and
\&\f(CW\*(C`\-\-show\-opts\*(C'\fR options are implemented.
.Sp
If no \f(CW$weight\fR is specified then \f(CW0\fR is used. \f(CW\*(C`post\*(C'\fR callbacks or sorted
based on weight with higher values being run later.
.SH "OPTIONS INSTANCES"
.IX Header "OPTIONS INSTANCES"
In general you should not be using the options instance directly. Options
instances are mostly an implementation detail that should be treated as a black
box. There are however a few valid reasons to interact with them directly. In
those cases there are a few public attributes/methods you can work with. This
section documents the public interface.
.SS ATTRIBUTES
.IX Subsection "ATTRIBUTES"
This section only lists attributes that may be useful to people working with
options instances. There are a lot of internal (to yath) attributes that are
implementation details that are not listed here. Attributes not listed here are
not intended for external use and may change at any time.
.ie n .IP "$arrayref = $options\->all" 4
.el .IP "\f(CW$arrayref\fR = \f(CW$options\fR\->all" 4
.IX Item "$arrayref = $options->all"
Arrayref containing all the App::Yath::Option instances in the options
instance.
.ie n .IP "$settings = $options\->settings" 4
.el .IP "\f(CW$settings\fR = \f(CW$options\fR\->settings" 4
.IX Item "$settings = $options->settings"
Get the Test2::Harness::Settings instance.
.ie n .IP "$arrayref = $options\->args" 4
.el .IP "\f(CW$arrayref\fR = \f(CW$options\fR\->args" 4
.IX Item "$arrayref = $options->args"
Get the reference to the list of command line arguments. This list is modified
as arguments are processed, there are no guarentees about what is in here at
any given stage of argument processing.
.ie n .IP "$class_name = $options\->command_class" 4
.el .IP "\f(CW$class_name\fR = \f(CW$options\fR\->command_class" 4
.IX Item "$class_name = $options->command_class"
If yath has determined what command is being executed this will be populated
with that command class. This will be undefined if the class has not been
determined yet.
.ie n .IP "$arrayref = $options\->used_plugins" 4
.el .IP "\f(CW$arrayref\fR = \f(CW$options\fR\->used_plugins" 4
.IX Item "$arrayref = $options->used_plugins"
This is a list of all plugins who's options have been used. Plugins may appear
more than once.
.ie n .IP "$hashref = $options\->included" 4
.el .IP "\f(CW$hashref\fR = \f(CW$options\fR\->included" 4
.IX Item "$hashref = $options->included"
A hashref where every key is a package who's options have been included into
this options instance. The values are an implementation detail, do not rely on
them.
.SS METHODS
.IX Subsection "METHODS"
This section only lists methods that may be useful to people working with
options instances. There are a lot of internal (to yath) methods that are
implementation details that are not listed here. Methods not listed here are
not intended for external use and may change at any time.
.ie n .IP "$opt = $options\->option(%OPTION_ATTRIBUTES)" 4
.el .IP "\f(CW$opt\fR = \f(CW$options\fR\->option(%OPTION_ATTRIBUTES)" 4
.IX Item "$opt = $options->option(%OPTION_ATTRIBUTES)"
This will create a new option with the provided attributes and add it to the
options instance. A \f(CW\*(C`trace\*(C'\fR attribute will be automatically set for you.
.ie n .IP $options\->include($options_instance) 4
.el .IP \f(CW$options\fR\->include($options_instance) 4
.IX Item "$options->include($options_instance)"
This method lets you directly include options from a second instance into the
first.
.ie n .IP $options\->include_from(@CLASSES) 4
.el .IP \f(CW$options\fR\->include_from(@CLASSES) 4
.IX Item "$options->include_from(@CLASSES)"
This lets you include options from multiple classes that have options defined.
.ie n .IP $options\->include_option($opt) 4
.el .IP \f(CW$options\fR\->include_option($opt) 4
.IX Item "$options->include_option($opt)"
This lets you include a single already defined option instance.
.ie n .IP "$options\->pre_docs($format, @args)" 4
.el .IP "\f(CW$options\fR\->pre_docs($format, \f(CW@args\fR)" 4
.IX Item "$options->pre_docs($format, @args)"
Get documentation for pre-command options. \f(CW$format\fR may be 'cli' or 'pod'.
.ie n .IP "$options\->cmd_docs($format, @args)" 4
.el .IP "\f(CW$options\fR\->cmd_docs($format, \f(CW@args\fR)" 4
.IX Item "$options->cmd_docs($format, @args)"
Get documentation for command options. \f(CW$format\fR may be 'cli' or 'pod'.
.SH SOURCE
.IX Header "SOURCE"
The source code repository for Test2\-Harness can be found at
\&\fIhttp://github.com/Test\-More/Test2\-Harness/\fR.
.SH MAINTAINERS
.IX Header "MAINTAINERS"
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.SH AUTHORS
.IX Header "AUTHORS"
.PD 0
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.PD
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2020 Chad Granum <exodist7@gmail.com>.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
See \fIhttp://dev.perl.org/licenses/\fR