view release on metacpan or  search on metacpan

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

=item C<children_prefixes>

   my $aref = $self->children_prefixes;
   $self->children_prefixes(\@new_prefixes);

See L</Application High Level View>.

=item C<collect>

   $self->collect;

Collect options values from the configured sources, see L</OPTIONS>.

Not assumed to be used directly. Overloading is a liability.

=item C<commit>

   $self->commit;

Commit the collected options.

Not assumed to be used directly.

It can be overloaded to provide a custom behaviour, which can e.g.
modify C<residual_args> or C<config_hash> to drive following steps of
looking for a sub-command.

=item C<config>

   my $value = $self->config($key);   # returns a scalar anyway
   my @values = $self->config(@keys);

Retrieve collected option values.

=item C<config_hash>

   my $merged_hash = $self->config_hash;
   my $detailed    = $self->config_hash(1);

Get the collected option values as a hash.

In the basic case, a I<merged> hash is returned, with values taken from
sources according to their priorities.

In the advanced case where a I<true> value is passed as optional
argument, a hash with two keys C<merged> and C<sequence> is returned.
The explanation of the data format is beyond the scope of this manual
page.

=item C<default_child>

   my $dc = $self->default_child;
   $self->default_child($new_name);

See L</Application High Level View>.

=item C<description>

   my $text = $self->description;
   $self->description($updated_description);

See L</Application High Level View>.

=item C<environment_prefix>

   my $prefix = $self->environment_prefix;
   $self->environment_prefix($new_prefix);

See L</Application High Level View>.

=item C<environment_variable_name>

   my $name = $self->environment_variable_name($opt_hash);

Get the environment variable name set for the specific option described
by C<$opt_hash>. If it contains an C<environment> key and it has a name,
that is returned, otherwise if it is C<1> then an environment variable
is generated from C<envoronment_prefix> and C<name>.

=item C<execute>

   $self->execute;

Code that executes the main logic of the command.

If a sub reference was provided with C<execute> in the application
definition, that is called receiving the object as its only parameter.
Otherwise, the intended use is to override this method in a derived
class for a command.

It is not meant to be called directly.

=item C<execution_reason>

   my $reason = $self->execution_reason;

A string representing the reason why the specific C<execute>
method/callback was selected, can be one of:

=over

=item * C<-default>

The command was selected as the default child set for a command.

=item * C<-fallback>

The command was selected as a result of the C<fallback> method.

=item * C<-leaf>

The command is a leaf and has no sub-commands.

=back

=item C<fallback>

   my $name = $self->fallback;

Select a fallback child, or the invoking command itself (returning

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

then the environment, then the defaults.

In summary: all command-line parameters with precedence from right to
left, then the environment, then defaults.

It is easy to also add the C<+JsonFileFromConfig> source, like in the
following example:


   {
      current => [ qw< +CmdLine +Parent > ],
      final =>
         [
            qw<
               +LastCmdLine=10
               +Parent=20
               +FinalEnvironment=30
               +FinalDefault=100
               +JsonFileFromConfig=40
            >
         ],
   }

Priorities for the first three sources in C<final> are set explicitly
but would take the same values implicitly, they have been put in the
example only for clarity.

As before, we put the C<+FinalDefault> option I<before> the
C<+JsonFileFromConfig> so that we can read the default value for the
C<config> option (if present), while still giving stuff from the file
precendence over the defaults.

After this information gathering phase, method/callback C<final_commit>
is called (much like C<commit> is called after C<collect>).

It is possible to set key C<final_collect> or override it as a method,
for maximum flexibility. Doing this is a liability.


=head3 New commit finalization: C<final_commit>

in the new L</Sources as hash reference> way of setting C<sources>,
after the final roundup of options done by C<final_collect>, the
C<final_commit> method/callback is executed.

By default, this triggers calling it all up the commands ladder, i.e.
from the leaf command that will be executed up to the root command. This
allows setting "final configurations" (like a logger) in the
C<final_commit> method of the topmost command, once and for all.

It is anyway possible to set callbacks or override the method at each
intermediate or at the leaf level, of course. In this case, the return
value of the method/callback will be used to determine whether to
continue up the ladder or not; I<true> values will continue the call
chain, I<false> values will interrupt it.

It's also possible to break the chain of calls by setting the key to a
I<false> value.

It MUST be considered that the method is specific to each command, which
usually does not have an I<updated> view of the whole configuration,
because that is only known to the leaf command's object. For this
reason, method/callback C<final_commit> can also call method
C<final_commit_stack>, which provides a list of all command objects that
are involved in the chain, starting from the leaf command down towards
the root.

For this reason, the way to get the I<full> configuration in the topmost
command is the following:

   sub final_commit ($self) {
      my ($leaf) = $self->final_commit_stack;
      my $final_config = $leaf->config_hash;
      ...
   }

Method C<final_commit_stack> is only available (predictably) inside
method/callback C<final_commit>; its availability elsewhere is not
guaranteed.

=head2 Specification Inheritance vs. Value Acquisition

C<App::Easer> provides two different ways of I<sharing> options between
parents and children.

One way of doing this is by means of source C<+Parent>
(L<< /Option Values Collection (C<sources>) >>: this allows I<absorbing>
configurations from a parent inside a child. Every options that has been
set in the parent command is copied into the child, subject to
priorities etc.

Another way of doing this is by I<inheriting> options specifications by
a child from its parent. This makes the parent's option appear also as a
child's option, which might ease the life of users because they would
not need to set options exactly in the I<first> command that supports
it.

The latter behaviour has two halves: one in the parent and the other in
the child command.

Parent commands can declare which option specifications can be inherited
by children by setting C<transmit> to a true value in the option's
speficiation. By default, options are I<not> set as inheritable.

Children can then inherit options by using string or regular expressions
instead of hash references. In this way, a child can cherry-pick which
options from the parent make sense and ignore the other ones.

Consider the following example:

   my $app = {
      aliases => [ 'main' ],
      options => [
         {
            getopt => 'transmittable',
            help => 'option available in parent, transmit => 1',
            transmit => 1,
         },
         {
            getopt => 'parent-only',
            help => 'option available in parent only',