view release on metacpan or  search on metacpan

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

a sub-command is searched and, if present, the process restarts from the
first step above

=item *

when the final sub-command is reached, its C<execute> function is run.

=back

=head2 Factory and Executables

   factory:
      create: «executable»
      prefixes: «hash or array of hashes»

Many customization options appear as C<«executable»>.

At the basic level, these can be just simple references to a sub. In
this case, it is used directly.

When they are provided in some other form, though, a I<factory> function
is needed to turn that alternative representation into a sub reference.

C<App::Easer::V1> comes with a default I<factory> function (described below)
that should cover most of the needs. It is possible to override it by
setting the value for key C<create> inside C<factory>; the default
function is used to generate this new factory, which is then installed
to parse all other C<«executable»> values in the definition.

The default factory manages the following representations:

=over

=item *

sub references are passed through directly;

=item *

strings are first filtered according to the mapping/mappings provided by
the field C<prefixes> in C<factory>, then parsed to get the name of a
package and optionally the name of a sub in that package (each field
that carries an C<«executable»> is associated to a default sub name).

=back

The C<prefixes> can be either a hash reference, or an array of hashes.
The latter allows setting an order for substitutions, e.g. to make sure
that prefix C<::> is tried first if there is also prefix C<:> defined:

   prefixes:
      - '::' : 'What::Ever::'
      - ':' :  'My::App::'

Otherwise, the I<unordered> nature of Perl hashes would risk that the
expansion associated to C<:> is tried first, spoiling the result and
making it unpredictable.

By default, the C<+> character prefix is associated to a mapping into
functions in C<App::Easer::V1> starting with C<stock_>. As an example, the
string C<+CmdLine> is expanded into C<App::Easer::V1::stock_CmdLine>, which
happens to be an existing function (used in parsing command-line
options). It is possible to suppress this expansion by setting a mapping
from C<+> to C<+> in the C<prefixes>, although this will deviate from
the normal working of C<App::Easer::V1>.

=head2 Configuration Parsing Customization

   configuration:
      name:      «string»
      collect:   «executable»
      merge:     «executable»
      namenv:    «executable»
      specfetch: «executable»
      validate:  «executable»
      sources:   «array»
      'auto-children':    «false or array»
      'help-on-stderr':   «boolean»
      'auto-leaves':      «boolean»
      'auto-environment': «boolean»

The C<name> configuration allows setting a name for the application,
which can e.g. be used to generate automatic names for environment
variables to be associated to command options.

One of the central services provided by C<App::Easer::V1> is the automatic
gathering of options values from several sources (command line,
environment, commands upper in the hierarchy, defaults). Another service
is the automatic handling of two sub-commands C<help> and C<commands> to
ease navigating in the hierarchy and get information on the
(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

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

an I<application> definition, which can be provided as:

=over

=item *

hash reference ("native" format)

=item *

reference to a string, containing either a JSON or a Perl definition for
the application.

For the JSON alternative, the string must contain a JSON object so that
the parsing returns a reference to a hash.

For the Perl alternative, the text is C<eval>ed and must return  a
reference to a hash.

=item *

a string with a file path, pointing to either a JSON or a Perl file. The
file is loaded and treated as described above for the I<reference to a
string> case;

=item *

a filehandle, allowing to load either a JSON or a Perl file. The content
is treated as described above for the I<reference to a string> case.

=back

=item *

the command-line arguments to parse (usually taken from C<@ARGV>),
provided as a reference to an array.

=back

=begin hidden

=head2 add_auto_commands

=head2 appeaser_api

=head2 collect

=head2 collect_options

=head2 commandline_help

=head2 commit_configuration

=head2 default_getopt_config

=head2 env_namer

=head2 execute

=head2 expand_children

=head2 stock_factory

   # just the sub
   $subref = factory(sub {});

   # eval it - note the initial space in the string
   $subref = factory(' sub {}');

   # Expand the '+', by default with 'App::Easer::V1#stock_'
   # \&App::Easer::V1::options_CmdLine
   $subref = factory('+CmdLine');

   # Expand the '::' with the provided mapping to 'Myapp::'
   # \&Myapp::Whatever::galook
   $subref = factory('::Whatever', 'galook', {prefixes => {'::' => 'Myapp::'}});

   # No expansion
   # \&Myapp::Whatever::galook
   $subref = factory('Myapp::Whatever', 'galook');

   # No expansion, use provided sub name 'foobar' instead of default 'galook'
   # \&Myapp::Whatever::foobar
   $subref = factory('Myapp::Whatever#foobar', 'galook');

   # Expand empty prefix with 'Myapp::Whatever', use provided sub name 'foo'
   # \&Myapp::Whatever::foobar
   $subref = factory('#foobar', 'galook', {prefixes => {'' => 'Myapp::Whatever}});

   # Expand '::' to 'Myapp::', setting the order in which expansions
   # apply and using the empty expansion as a last resort
   # \&Myapp::Another::galook
   $subref = factory('::Another', 'galook',
      {prefixes => [{'::' => 'Myapp::'}, {'' => 'Myapp::Whatever'}]});

This function is a factory to return other functions for several reasons.

The signature is the following, with three positional arguments:

   sub factory ($executable, $default_subname = '', $opts = {})

The arguments are:

=over

=item * C<$executable> (mandatory)

is the locator for the executable, i.e. the sub reference.

If a sub reference, it is already resolved and returned.

Otherwise, it is interpreted as a string, subject to the expansion explained
below.

=item * C<$default_subname> (optional, defaults to '')

is the default name of a sub to look for in the selected package;

=item * C<$opts>

is a hash reference with additional options, e.g. a C<prefixes> sub-hash or
sub-array mapping string prefixes to expaned ones (see below).

=back

When C<$executable> is a string, it is first I<expanded> according to the
available prefixes in C<< $opts->{prefixes} >>. This contains mapping from
prefixes to expanded versions of those prefixes; it can be either a hash
reference with the mappings, or an array of those hash references (this
allows setting the order to use for doing the expanion, e.g. making sure
that C<:::> is attempted before C<:>, should both be possible).

By default, prefix C<+> is expanded with C<App::Easer::V1::>; e.g. the
input executor C<+CmdLine> becomes C<App::Easer::V1::CmdLine>. It is
possible to change this or disable it (disabling can be achieved by
providing a mapping from C<+> to C<+>, although this will probably make
loading of the package fail in a later stage).

After this expansion of the prefix, if any, the string in C<$executor> is
split into two parts, based on the character C<#>. What comes before is a
I<package> name, what comes after is a I<subroutine> name (defaulting to
C<$default_subname>).

The I<package> is loaded using C<require>, then a reference to the desired
I<subroutine> is taken and returned. If no subroutine exists, an exception
is thrown (C<no '$subname' in '$package'>);


=head2 fetch_spec_for

   my $spec = fetch_spec_for($self, $name);

Encapsulation for accessing the specification of one available commands.
It normally maps onto C<< $self->{application}{commands}{$name} >> but
it can be extended, e.g. with C<specfetch> set to
C<+SpecFromHashOrModule> or a custom resolution method.

Calling it can return a hash reference with the command specification or
C<undef> if no command can be found.

=head2 fetch_subcommand_default

=head2 fetch_subcommand

=head2 fetch_subcommand_wh

=head2 generate_factory

=head2 get_child

=head2 get_children

=head2 get_descendant

=head2 has_children

=head2 hash_merge

=head2 list_commands

=head2 load_application

=head2 merger

=head2 name_for_option

=head2 params_validate

=head2 print_commands

=head2 print_help

=head2 slurp