view release on metacpan or  search on metacpan

lib/App/Cmd/Tutorial.pod  view on Meta::CPAN

#pod
#pod     print "Everything has been initialized.  (Not really.)\n";
#pod   }
#pod
#pod Now it works:
#pod
#pod   $ yourcmd initialize
#pod   Everything has been initialized.  (Not really.)
#pod
#pod =head2 Default Commands
#pod
#pod By default applications made with App::Cmd know two commands: C<commands> and
#pod C<help>.
#pod
#pod =over
#pod
#pod =item commands
#pod
#pod lists available commands.
#pod
#pod   $yourcmd commands
#pod   Available commands:
#pod
#pod     commands: list the application's commands
#pod         help: display a command's help screen
#pod
#pod         init: set up YourApp
#pod
#pod Note that by default the commands receive a description from the C<# ABSTRACT>
#pod comment in the respective command's module, or from the C<=head1 NAME> Pod
#pod section.
#pod
#pod =item help
#pod
#pod allows one to query for details on command's specifics.
#pod
#pod   $yourcmd help initialize
#pod    yourcmd initialize [-z] [long options...]
#pod
#pod           -z --zero        ignore zeros
#pod
#pod Of course, it's possible to disable or change the default commands, see
#pod L<App::Cmd>.
#pod
#pod =back
#pod
#pod =head2 Arguments and Options
#pod
#pod In this example
#pod
#pod   $ yourcmd reset -zB --new-seed xyzzy foo.db bar.db
#pod
#pod C<-zB> and C<--new-seed xyzzy> are "options" and C<foo.db> and C<bar.db>
#pod are "arguments."
#pod
#pod With a properly configured command class, the above invocation results in
#pod nicely formatted data:
#pod
#pod   $opt = {
#pod     zero      => 1,
#pod     no_backup => 1, #default value
#pod     new_seed  => 'xyzzy',
#pod   };
#pod
#pod   $args = [ qw(foo.db bar.db) ];
#pod
#pod Arguments are processed by L<Getopt::Long::Descriptive> (GLD).  To customize
#pod its argument processing, a command class can implement a few methods:
#pod C<usage_desc> provides the usage format string; C<opt_spec> provides the option
#pod specification list; C<validate_args> is run after Getopt::Long::Descriptive,
#pod and is meant to validate the C<$args>, which GLD ignores. See L<Getopt::Long>
#pod for format specifications.
#pod
#pod The first two methods provide configuration passed to GLD's C<describe_options>
#pod routine.  To improve our command class, we might add the following code:
#pod
#pod   sub usage_desc { "yourcmd %o [dbfile ...]" }
#pod
#pod   sub opt_spec {
#pod     return (
#pod       [ "skip-refs|R",  "skip reference checks during init", ],
#pod       [ "values|v=s@",  "starting values", { default => [ 0, 1, 3 ] } ],
#pod     );
#pod   }
#pod
#pod   sub validate_args {
#pod     my ($self, $opt, $args) = @_;
#pod
#pod     # we need at least one argument beyond the options; die with that message
#pod     # and the complete "usage" text describing switches, etc
#pod     $self->usage_error("too few arguments") unless @$args;
#pod   }
#pod
#pod =head2 Global Options
#pod
#pod There are several ways of making options available everywhere (globally). This
#pod recipe makes local options accessible in all commands.
#pod
#pod To add a C<--help> option to all your commands create a base class like:
#pod
#pod   package MyApp::Command;
#pod   use App::Cmd::Setup -command;
#pod
#pod   sub opt_spec {
#pod     my ( $class, $app ) = @_;
#pod     return (
#pod       [ 'help' => "this usage screen" ],
#pod       $class->options($app),
#pod     )
#pod   }
#pod
#pod   sub validate_args {
#pod     my ( $self, $opt, $args ) = @_;
#pod     if ( $opt->{help} ) {
#pod       my ($command) = $self->command_names;
#pod       $self->app->execute_command(
#pod         $self->app->prepare_command("help", $command)
#pod       );
#pod       exit;
#pod     }
#pod     $self->validate( $opt, $args );

lib/App/Cmd/Tutorial.pod  view on Meta::CPAN

    print "Everything has been initialized.  (Not really.)\n";
  }

Now it works:

  $ yourcmd initialize
  Everything has been initialized.  (Not really.)

=head2 Default Commands

By default applications made with App::Cmd know two commands: C<commands> and
C<help>.

=over

=item commands

lists available commands.

  $yourcmd commands
  Available commands:

    commands: list the application's commands
        help: display a command's help screen

        init: set up YourApp

Note that by default the commands receive a description from the C<# ABSTRACT>
comment in the respective command's module, or from the C<=head1 NAME> Pod
section.

=item help

allows one to query for details on command's specifics.

  $yourcmd help initialize
   yourcmd initialize [-z] [long options...]

          -z --zero        ignore zeros

Of course, it's possible to disable or change the default commands, see
L<App::Cmd>.

=back

=head2 Arguments and Options

In this example

  $ yourcmd reset -zB --new-seed xyzzy foo.db bar.db

C<-zB> and C<--new-seed xyzzy> are "options" and C<foo.db> and C<bar.db>
are "arguments."

With a properly configured command class, the above invocation results in
nicely formatted data:

  $opt = {
    zero      => 1,
    no_backup => 1, #default value
    new_seed  => 'xyzzy',
  };

  $args = [ qw(foo.db bar.db) ];

Arguments are processed by L<Getopt::Long::Descriptive> (GLD).  To customize
its argument processing, a command class can implement a few methods:
C<usage_desc> provides the usage format string; C<opt_spec> provides the option
specification list; C<validate_args> is run after Getopt::Long::Descriptive,
and is meant to validate the C<$args>, which GLD ignores. See L<Getopt::Long>
for format specifications.

The first two methods provide configuration passed to GLD's C<describe_options>
routine.  To improve our command class, we might add the following code:

  sub usage_desc { "yourcmd %o [dbfile ...]" }

  sub opt_spec {
    return (
      [ "skip-refs|R",  "skip reference checks during init", ],
      [ "values|v=s@",  "starting values", { default => [ 0, 1, 3 ] } ],
    );
  }

  sub validate_args {
    my ($self, $opt, $args) = @_;

    # we need at least one argument beyond the options; die with that message
    # and the complete "usage" text describing switches, etc
    $self->usage_error("too few arguments") unless @$args;
  }

=head2 Global Options

There are several ways of making options available everywhere (globally). This
recipe makes local options accessible in all commands.

To add a C<--help> option to all your commands create a base class like:

  package MyApp::Command;
  use App::Cmd::Setup -command;

  sub opt_spec {
    my ( $class, $app ) = @_;
    return (
      [ 'help' => "this usage screen" ],
      $class->options($app),
    )
  }

  sub validate_args {
    my ( $self, $opt, $args ) = @_;
    if ( $opt->{help} ) {
      my ($command) = $self->command_names;
      $self->app->execute_command(
        $self->app->prepare_command("help", $command)
      );
      exit;
    }
    $self->validate( $opt, $args );