view release on metacpan or  search on metacpan

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

false value), only the I<merged> configuration hash is set, i.e. what is
returned by a call like C<< $instance->configuration_hash >>. In
practical terms, it replaces what can be taken when setting
L</config_hash_key> to either C<merged> (the default value) or
C<override>.

The second form allows setting the whole underlying data structure that
can be taken by a call like C<< $instance->configuration_hash(1) >>.
This allows messing up with the whole process.

=item C<slot>

   my $hashref = $self->slot;
   $self->slot($new_data);

C<App::Easer::V2> uses a blessed hash reference to manage all data
related to an object representing a command. To minimize overlapping
with a user's object data, all data for C<App::Easer::V2> is kept in a
sub-hash pointed by the C<slot> key, like this:

   bless {
      $class_name => {
         ... all actual App::Easer::V2 stuff here ...
      }
   }, $hashy_class;

This method gives access to this slot and can be overridden to keep this
data elsewhere, e.g. in an array element or in an inside-out object,
without the need to re-implement all accessors.

=item C<slurp>

   my $contents   = $self->slurp($filename);
   my $contents_2 = $self->slurp($filename, '<:raw');

Get the whole contents from a file, optionally specifying the mode for
openining the file. By default, UTF-8 encoding is assumed and enforced.

Use of this method is discouraged and not future-proof.

=item C<sources>

   my @sources = $self->sources;
   $self->sources(\@new_sources_list);

See L</Application High Level View> and L</OPTIONS>.

=item C<validate>

   $self->validate(\&validation_sub);
   $self->validate;

Performs validation.

When a validation sub is set (either calling with a parameter, or
setting it via C<validate> in L</new>) it will be called, receiving
C<$self> as the only parameter:

   $sub->($self);

The validator is supposed to throw an exception upon validation failure.

If no validation sub is set, L</params_validate> is looked for. If
present, validation is applied according to it, using
L<Params::Validate>.

=back

=head1 OPTIONS

The main capability provided by C<App::Easer> is the flexibility to
handle options, collecting them from several sources and merging them
together according to priorities.

Supported options are set in an array of hashes (or strings) pointed by
the C<options> key. Each hash in the array sets the details regarding a
single option.  When provided as string, the option is I<inherited> from
a parent, allowing the sub-command to expose the same option as the
parent. This gives freedom to put options and values either in the
parent or in the descendant command, providing flexibility.

This is a YAML overview of how to set one option as a hash:

   name: «string»
   help: «string»
   transmit: «boolean»
   transmit_exact: «boolean»
   getopt: «string»
   environment: «string» or 1
   default: any value

A few keys inside the hash regard the option itself, like:

=over

=item * C<name>

name of the option. This is not mandatory if C<getopt> is present, which
gets the name automatically from the first alias of the option itself;

=item * C<help>

some help about the option.

=item * C<transmit>

boolean to set whether an option can be easily "inherited" by a
sub-command (without the need to put all attributes of the option once
again).

=item * C<transmit_exact>

boolean to set whether the option must be spelled exactly to be
inherited (no inheritance via a regular expression).

=back

=head2 Option Values Collection (C<sources>)

The collection is performed thanks to I<sources>, which can be set with
the corresponding C<sources> key or method (depending on the style).