view release on metacpan or  search on metacpan

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

   # 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

=head2 sources

=head2 stock_ChildrenByPrefix

=head2 stock_CmdLine

=head2 stock_Default

=head2 stock_DefaultSources

=head2 stock_Environment