view release on metacpan or  search on metacpan

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

   }

In this configuration, all command levels share the same I<forward>
configuration, only gathering command-line parameters, with later
sub-commands taking precedence (C<+CmdLine> has higher priority than
C<+Parent>).

After the right sub-command to execute is determined, then the latest
command line is taken (it is not parsed again), then the parent (like
before, it only contains command-line parameters from upper commands),
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 = {