view release on metacpan or  search on metacpan

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

If passed as a hash reference, two keys are supported:

=over

=item C<args>

call C<Params::Validate::validate_pos> on the C<residual_args> (see
L</OPTIONS>).

=item C<config>

call C<Params::Validate::validate> on the collected I<merged>
configuration (see L</OPTIONS>).

=back

=item C<sources>

Array of items.

See L</OPTIONS>.

=item C<validate>

Sub reference for performing validation. Will be called during the
validation phase and passed the command object instance:

   $validation_sub->($self);

If set, L</params_validate> is ignored.

=back

The following YAML representation gives an overview of the elements that
define an application managed by C<App::Easer::V2>, highlighting the
necessary or I<strongly suggested> ones at the beginning:

  aliases: «array of strings»
  execute: «executable»
  help: «string»
  options: «array of hashes»

  allow_residual_options: «boolean»
  auto_environment: «boolean»
  children: «array of hashes»
  children_prefixes: «array of strings»
  commit: «executable»
  default_child: «string»
  description: «string»
  environment_prefix: «string»
  fallback_to: «string»
  force_auto_children: «boolean»
  hashy_class: «string»
  help_channel: «string»
  name: «string»
  params_validate: «hash»
  sources: «array of items»
  validate: «executable»

As anticipated, it's entirely up to the user to decide what style is
best, i.e. define applications through metadata only, through
object-oriented derivation, or through a mix of the two. The following
examples are aimed at producing the same application:

   # metadata (mostly)
   my $app_as_metadata = {
      aliases => [qw< this that >],
      help => 'this is the application, but also that',
      options => [ { getopt => 'foo|f=s', default => 'bar' } ],
      execute => sub ($app) {
         say 'foo is ', $app->config('foo');
         return 0;
      },
   };

   # class only
   package ThisThatApp;
   use App::Easer::V2 '-command';
   sub aliases ($self) { return [qw< this that >] }
   sub help ($self) { return 'this is the application, but also that' }
   sub options ($self) { [ { getopt => 'foo|f=s', default => 'bar' } ] }
   sub execute ($self) {
      say 'foo is ', $self->config('foo');
      return 0;
   }

   # mixed style
   package ThisThatMixedApp;
   use App::Easer::V2 -command => -spec => {
      aliases => [qw< this that >],
      help => 'this is the application, but also that',
      options => [ { getopt => 'foo|f=s', default => 'bar' } ],
   };
   sub execute ($self) {
      say 'foo is ', $self->config('foo');
      return 0;
   }

The last style allows keeping data mostly as data, while leaving the
freedom to implement the logic as proper methods, which can be
beneficial for e.g. sharing common logic among several commands.

=head1 App::Easer::V2::Command METHODS

When a command is created, it is (usually) an instance of class
C<App::Easer::V2::Command> or a descendant. As such, it has the
methods explained in the following list, which at the moment appear as
public ones although some might be hidden in the future (stable ones are
expressely marked so).

=over

=item C<auto_children>

   my @classes = $self->auto_children;
   my @objects = $self->auto_children(1);

Return a list of the automatic children (C<help>, C<commands>, and
C<tree>) as inflatable children, i.e. as fully qualified class names. If
an optional true value is passed, children are inflated into objects.