view release on metacpan or  search on metacpan

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

   $ ./example.pl help inexistent
   cannot find sub-command 'inexistent'

=head1 DESCRIPTION

B<NOTE>: THIS DOCUMENT HAS TO BE REVIEWED TO MAKE IT EXPLICIT THAT IT
REFERS TO VERSION 2 OF THE API.

App::Easer::V2 provides the scaffolding for implementing hierarchical
command-line applications in a very fast way. This is Version 2 of the
provided API, which does everything described below.

It makes it extremely simple to generate an application based on
specific interfacing options, while still leaving ample capabilities for
customising the shape of the application. As such, it aims at making
simple things easy and complex things possible, in pure Perl spirit.

There are multiple ways to define an application. The two extremes are:

=over

=item *

a hash reference with all the needed elements inside (see L</SYNOPSIS>
for an example)

=item *

a sub-class of C<App::Easer::V2::Command> with methods overriding the
needed elements where the programmer sees fit.

=back

App::Easer::V2 allows also to leverage both aspects at the same time for
the same command, e.g. setting some parts through a hash reference and
other parts with overriding methods.

=head2 Top-Level Functions

The following functions are exported by C<App::Easer::V2>:

=over

=item * C<appeaser_api>

   my $api_version = appeaser_api();

Return string C<V2>.

=item * C<d>

   d($whatever);

Sends C<$whatever> through C<dd> and then to C<warn>.

=item * C<dd>

   my $dumped = dd($whatever);

Sends C<$whatever> through L<Data::Dumper> and returns it.

=item * C<run>

   my $exit_code = run($cmd_hashref, $0, @ARGV);

Run a command with the provided parameters (first the name of the
command, using C<$0>, then the command-line arguments).

=back

In addition to importing the functions above, the following keys are
also supported when C<use>ing the module:

=over

=item * C<-command>

The package from where C<App::Easer::V2> is C<use>d is a command and
inherits from C<App::Easer::V2::Command>, as well as registering as a
command. This is the combined effect of C<-inherit> and C<-register>
below.

=item * C<-inherit>

The package from where C<App::Easer::V2> is C<use>d inherits from
C<App::Easer::V2::Command>. Usually C<-command> is the right one though.

=item * C<-register>

Register this package as a valid (sub)command.

=item * C<-spec>

Provide a specification hash reference to set many attributes of the
specific command. This hash reference is saved into the package's
variable C<app_easer_spec>.

=back

The options above allow easily define a new class for a command like
this:

   use App::Easer::V2 -command => -spec => { ... };


=head2 Anatomy of a run

Running an application can be done in several ways, depending on how the
application is represented:

   # application defined as a hashref or arrayref
   use App::Easer V2 => 'run';
   exit run($app, $0, @ARGS);

   # application defined in a class
   use MyApp;
   exit MyApp->new->run($0, @ARGS);

When an application is run, the following high level algorithm is
applied: