view release on metacpan or  search on metacpan

lib/App/Easer/V2.pod  view on Meta::CPAN

=head1 OPTIONS

The main capability provided by C<App::Easer> is the flexibility to
handle options, collecting them from several sources and merging them
together according to priorities.

Supported options are set in an array of hashes (or strings) pointed by
the C<options> key. Each hash in the array sets the details regarding a
single option.  When provided as string, the option is I<inherited> from
a parent, allowing the sub-command to expose the same option as the
parent. This gives freedom to put options and values either in the
parent or in the descendant command, providing flexibility.

This is a YAML overview of how to set one option as a hash:

   name: «string»
   help: «string»
   transmit: «boolean»
   transmit_exact: «boolean»
   getopt: «string»
   environment: «string» or 1
   default: any value

A few keys inside the hash regard the option itself, like:

=over

=item * C<name>

name of the option. This is not mandatory if C<getopt> is present, which
gets the name automatically from the first alias of the option itself;

=item * C<help>

some help about the option.

=item * C<transmit>

boolean to set whether an option can be easily "inherited" by a
sub-command (without the need to put all attributes of the option once
again).

=item * C<transmit_exact>

boolean to set whether the option must be spelled exactly to be
inherited (no inheritance via a regular expression).

=back

=head2 Option Values Collection (C<sources>)

The collection is performed thanks to I<sources>, which can be set with
the corresponding C<sources> key or method (depending on the style).
C<App::Easer> comes with several sources for getting configurations from
a variety of places, but still leaves the door open to add more
customized ones.

Up to version C<2.007001> included, the C<sources> key could only point
to an I<array reference> holding a list of sources. After that release,
it has been expanded to I<also> accept a I<hash reference>, allowing for
a new and more sophisticated handling of option values collection. In
either case, anyway, processing arrives at a point where there is a
I<list of sources> to be processed as described below; using the I<array
ref> keeps backwards compatibility with the old behaviour. See
L</Sources as hash reference> for additional details on the new way.

Sources are I<considered> with respect to two different ordering
methods: their place in the array pointed by key C<sources> and their
I<priority>. The former sets the order in which data from each source is
collected, the latter sets the precedence while assembling conflicting
data from several different sources (lower priorities means higher
precedence).

Each source can be set either as a C<$locator> (see ahead) or as an
array reference with the following structure:

   [ $locator, @args ]

The C<$locator> can be a reference to a sub, which is used as the source
itself, or a string that allows getting the source sub to handle the
specific source. Strings starting with the C<+> character are reserved
for sources provided by C<App::Easer::V2> natively.

If C<$locator> is a plain string, it is possible to set the I<priority>
directly inside it with C<=NN> (e.g. C<+Default=100>).  It's not
necessary to set the priority; if missing, it will be assumed to be 10
more than the previous one in the array (with the first item starting at
10). This also means that, by default, the ordering of sources also
doubles down as the ordering of precedence.

The C<@args> part can provide additional arguments to the specific
source; its applicability is dependent on the source itself. As the only
exception, if the I<first> item of C<@args> is a hash reference, it will
be removed from the array and used to gather additional I<meta-options>
used directly by C<App::Easer>. At the moment, this is an alternative
way to set the priority of the specific source using the key
C<priority>. This means that the following examples are equivalent:

   # priority in source name, like anywhere else
   [ '+FromTrail=90', qw< defaults foo baz > ],

   # priority in meta-options first-arguments hash reference
   [ '+FromTrail', {priority => 90}, qw< defaults foo baz > ],

After the C<$locator> has been resolved to a sub reference
C<$located_sub>, and the first item in C<@args> has been analyzed and
possibly removed (because it contains I<meta-options> as described
above), the sub reference is invoked like follows:

   $located_sub->($command, $args_arrayref, $inputs_arrayref);

where:

=over

=item *

C<$command> is the instance of the (sub-)command under analysis

=item *