view release on metacpan or  search on metacpan

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

(sub)commands.

The configuration is collected by a function provided by
C<App::Easer::V1> that can be optionally overridden by setting a
different executable for C<collect> under C<configuration>. This of
course requires re-implementing the options value gathering from
scratch. Calling convention:

   sub ($app, $spec, $args)
   # $app:  hash ref with the details on the whole applications
   # $spec: hash ref with the specification of the command
   # $args: array ref with residual (command line) arguments

This function is expected to return a list with two items, the first a
hash reference with the collected configuration options, the second an
array reference with the residual arguments. The function is called
according to the following calling convention:

   sub ($app, $cspec, $ospec)
   # $app:   hash ref with the details on the whole applications
   # $cspec: hash ref with the specification of the command
   # $ospec: hash ref with the specification of the option

The C<merge> executable allows setting a function that merges several
hashes together. The default implementation operates at the higher level
of the hashes only, giving priority to the first hashes provided (in
order).  Calling convention:

   sub (@list_of_hashes_to_merge) # returns a hash reference

The C<namenv> executable allows setting a function that generates the
name of environment variables based on options specifications. By
default a C<stock_NamEnv> function is used (aliased to C<+NamEnv>) is
used, generating the name of the environment variable by uppercasing the
string generated by the application's name and the option name, joined
by an underscore character.

The C<specfetch> executable allows setting a function to perform
resolution of a command identifier (as e.g. stored in the C<children>)
or an upper command) into a specification. By default the internal
function corresponding to the executable specification string
C<+SpecFromHash> is used, insisting that the whole application is
entirely pre-assembled in the specification hash/object; it's also
possible to use C<+SpecFromHashOrModule> for allowing searching through
modules too.

The C<validate> executable allows setting a validator. By default the
validation is performed using L<Params::Validate> (if available, it is
anyway loaded only when needed).

It is possible to set several I<sources> for gathering options values,
setting them using the C<sources> array. By default it is set to the
ordered list with C<+Default>, C<+CmdLine>, C<+Environment>, and
C<+Parent>, , meaning that options from the command line will have the
highest precedence, then the environment, then whatever comes from the
parent command configuration, then default values if present. This can
be set explicitly with C<+DefaultSources>.

As an alternative, C<sources> can be set to C<+SourcesWithFiles>, which
adds C<+JsonFileFromConfig> and C<+JsonFiles> to the ones above. The
former looks for a configuration named C<config> (or whatever is set as
C<config-option> in the overall configuration hash) to load a JSON file
with additional configurations; the latter looks for a list of JSON
files to try in C<config-files> inside the configuration hash.

=over

Although the C<+Default> source is put I<first>, it actually acts as the
one with the I<least precedence> by how it is coded and how the merging
algorithm is implemented. From a practical point of view it's I<like> it
were put last, but is put first instead so that its defaults can be
applied as options are gathered along the way.

One case where this comes handy is in managing a C<--config> option to
pass a configuration file name to load some external file for additional
configurations (e.g. sources option C<+SourcesWithFiles>). In it,
default configuration must still appear with the I<least precedence>,
but still it can be handy to set a default file to load upon starting,
which means that it's handy to have this default at hand before the
configuration files are supposed to be loaded.

=back

As anticipated, the C<help> and C<commands> sub-commands are
automatically generated and associated to each command by default (more
or less). If this is not the desired behaviour, it is possible to either
disable the addition of the C<auto-children> completely (by setting a
false value), or provide an array of children names that will be added
automatically to each command (again, more or less).

It should be noted that both C<validate> and C<sources> are also part of
the specific setup for each command. As such, they will be rarely set at
the higher C<configuration> level and the whole C<configuration> section
can normally be left out of an application's definition.

Option C<help-on-stderr> allows printing the two stock helper
commands C<help> and C<commands> on standard error instead of standard
output (which is the default).

Option C<auto-leaves> allows setting any command that has no I<explicit>
sub-command as a leaf, which prevents it from getting a C<help> and a
C<commands> sub-command (or whatever has been put to override them). As
of version 0.007002 this is set to a I<true> value by default, but can
still be set to a I<false> value if the automatic sub-commands above are
deemed necessary for commands that have no explicit children in the
hierarchy.

Option C<auto-environment> turns on automatic addition of environment
variables to options, by setting the associated setting to 1. This can
also be set locally in a command.

=head2 Commands Specifications

Commands are stored in a hash of hashes, where the key represents an
internal I<identifier> for the command, which is then used to build the
hierarchy (each command can have a C<children> element where these
identifier are listed, or direct definitions for some of the children).

The command definition is a hash with the following shape:

   name: foo
   help: foo the bar
   description: foo allows us to foo the bar