view release on metacpan or  search on metacpan

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

This source expliticly ignores I<inherited> options, to prevent
overwriting previously set options. It is possible to override this:

   [ '+Default', include_inherited => 1 ]

Another alternative to do this is use C<+FinalDefault>.

=item * C<+FinalDefault>

This source works the same as C<+Default>, except that it works also for
options that have been inherited. This is particularly useful when using
L<Sources as hash reference>.

=item * C<+JsonFileFromConfig>

Get keys/values from a JSON file, whose path is pointed by a key in the
collected options. By default this key is C<config>. To set a different
key, pass this source as an array reference with the source name and the
key, like this:

   [ JsonFileFromConfig => 'jcnf' ]

=item * C<+JsonFiles>

Get keys/values from a few JSON files (it's OK if they do not exist). To
set the files to try, pass this source as an array reference:

   [ JsonFiles => @paths ]

=item * C<+FromTrail>

Get keys/values from a sub-hash of the already collected options (e.g.
after loading them from a configuration file). The I<trail> to the
position of the sub-hash is provided like this:

   [ FromTrail => qw< topcmd subcmd additional_values > ]

=back

It is possible to set a I<default> value for the option used by
C<JsonFileFromConfig>, as long as the C<+Default> source is placed
before C<JsonFileFromConfig>. In this case, it's usually necessary to
assign a lower priority value to C<JsonFileFromConfig> to make sure
values read from there take precedence over the defaults:

   sources => [qw<
      +CmdLine=10 +Environment=20 +Parent=30 +Default=100
      +JsonFileFromConfig=40
   >];

This is the main reason why the I<priority> has been detached from order
of appearance.

=head3 Sources as hash reference

Up to version C<2.007001>, the C<sources> key can only be set to an
array reference holding a list of sources. Each command level can have
its own list, or rely on the default one provided by C<App::Easer>.

This setup works in many situation but becomes too rigid when dealing
with inherited options. As an example, suppose that we define an option
C<loglevel> allowing to set the log level (e.g. info, debug, trace, ...)
for our suite of commands. At this point, either we limit the option at
the highest level only (then setting the logger configuration in the
topmost command's C<commit>), or we have to wait until the leaf command
is determined, which implies that every leaf command must repeat the
code to set the logger's configuration.

Additionally, this setup might not play well with options that load
configurations from files, because some files might be loaded based on
command line configurations that appear in upper commands but might
eventually be overridden in lower commands. So, in the following
example, we want to be able to only load C<second.json> and disregard
C<first.json>:

   myprg --config first.json foo --config second.json

For this reason, release past C<2.007001> (which is not included) also
support an alternative way of configuring C<sources>, namely through a
hash reference that supports three keys:


=over

=item C<current>

(mandatory) this is the equivalent of the I<old> behaviour, i.e. a list
of sources that is used to figure out the order and precedence of
collecting options.

=item C<next>

(optional) this allows setting the list of sources for the children
sub-commands (unless the sub-command has one already configured), i.e.
its C<current> when it will be called. It can be a straight list or a
sub reference, in which case it will be called to determine the list.

When absent, by default the children inherits the same C<current> list
as the parent command.

=item C<final>

(optional) this allows setting a list of sources that is used at the
very end of the child determination process, i.e. when the program
determines the descendant sub-command for which the C<execute>
method/callback will be called, in a new sub-phase aptly named
C<final_collect>.

=back

With the new hash-based configuration, the determination of the right
sub-command proceeds like before, using the C<current> list of sources
at each step (the C<current> for a sub-command might have been set using
the C<next> of the parent command). During this phase, the C<commit>
method/callback is called at every level just like before.

After the search for the right command to C<execute> is finished, method
C<final_collect> is called, using the C<final> list of the hash
reference. This allows deferring the collection of data from
non-commmand-line sources at the very end.