view release on metacpan or  search on metacpan

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

=back

See also L</set_config> and L</set_config_hash>.


=head1 MIXED STUFF

=head2 Managing help as a command-line option

To get C<help> about a command, App::Easer::V2 provides a C<help>
sub-command out of the box I<most of the times>. The exception is for
I<leaf> commands, which do not have sub-commands.

After version C<2.007001> (not included), in addition to the C<help>
command there is also a C<usage> command, which provides the same output
as C<help> but without the C<Description> section. The C<usage>
sub-command is managed as an alias of C<help>; it is possible to remove
this alias by setting C<@App::Easer::V2::Command::Help::aliases> to the
string C<help> alone.

This is not a big deal with hierarchical applications, because it's
possible to invoke the C<help> sub-command of the parent command and
pass the name of the sub-command we need help with:

   # print help about `topcmd`
   $ topcmd help

   # print help about `subcmd` under `topcmd`
   $ topcmd help subcmd

On the other hand, for non-hierarchical applications, the only available
command is also a leaf and this hinders getting a meaningful,
auto-generated help text off the shelf.

In this case, it's possible to include an option for getting help, like
this:

   my $app = {
      options => [
         {
            getopt => 'help|h!',
            help   => 'print help on the command',
         },
         ...

Then, inside the C<execute> sub, it's possible to I<run> the C<help>
sub-command explicitly:

   sub execute ($self) {
      return $self->run_help if $self->config('help');

      # ... normal code for "execute"
      # ...
   }

As of versions after C<2.007001> (not included) it is possible to pass
an additional parameter to C<run_help> with string C<usage>, to get a
shorter help which does not include the C<Description> section.

=head1 BUGS AND LIMITATIONS

Minimum perl version 5.24.

Report bugs through GitHub (patches welcome) at
L<https://github.com/polettix/App-Easer>.

=head1 AUTHOR

Flavio Poletti <flavio@polettix.it>

=head1 COPYRIGHT AND LICENSE

Copyright 2021 by Flavio Poletti <flavio@polettix.it>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.


=cut