App-Cmd
view release on metacpan or search on metacpan
lib/App/Cmd.pm view on Meta::CPAN
#pod
#pod sub description { "Long description on blortex algorithm" }
#pod
#pod sub opt_spec {
#pod return (
#pod [ "blortex|X", "use the blortex algorithm" ],
#pod [ "recheck|r", "recheck all results" ],
#pod );
#pod }
#pod
#pod sub validate_args {
#pod my ($self, $opt, $args) = @_;
#pod
#pod # no args allowed but options!
#pod $self->usage_error("No args allowed") if @$args;
#pod }
#pod
#pod sub execute {
#pod my ($self, $opt, $args) = @_;
#pod
#pod my $result = $opt->{blortex} ? blortex() : blort();
lib/App/Cmd.pm view on Meta::CPAN
#pod command line. The default default is "help"
#pod
#pod =cut
sub default_command { "help" }
#pod =method execute_command
#pod
#pod $app->execute_command($cmd, \%opt, @args);
#pod
#pod This method will invoke C<validate_args> and then C<run> on C<$cmd>.
#pod
#pod =cut
sub execute_command {
my ($self, $cmd, $opt, @args) = @_;
local our $active_cmd = $cmd;
$cmd->validate_args($opt, \@args);
$cmd->execute($opt, \@args);
}
#pod =method plugin_search_path
#pod
#pod This method returns the plugin_search_path as set. The default implementation,
#pod if called on "YourApp::Cmd" will return "YourApp::Cmd::Command"
#pod
#pod This is a method because it's fun to override it with, for example:
#pod
lib/App/Cmd.pm view on Meta::CPAN
reverse sort map { s/^--?//; $_ }
grep { $cmd->{$_} eq 'App::Cmd::Command::help' } keys %$cmd;
return (@help ? [ join('|', @help) => "show help" ] : ());
}
#pod =method usage_error
#pod
#pod $self->usage_error("Something's wrong!");
#pod
#pod Used to die with nice usage output, during C<validate_args>.
#pod
#pod =cut
sub usage_error {
my ($self, $error) = @_;
die "Error: $error\nUsage: " . $self->_usage_text;
}
sub _usage_text {
my ($self) = @_;
lib/App/Cmd.pm view on Meta::CPAN
sub description { "Long description on blortex algorithm" }
sub opt_spec {
return (
[ "blortex|X", "use the blortex algorithm" ],
[ "recheck|r", "recheck all results" ],
);
}
sub validate_args {
my ($self, $opt, $args) = @_;
# no args allowed but options!
$self->usage_error("No args allowed") if @$args;
}
sub execute {
my ($self, $opt, $args) = @_;
my $result = $opt->{blortex} ? blortex() : blort();
lib/App/Cmd.pm view on Meta::CPAN
=head2 default_command
This method returns the name of the command to run if none is given on the
command line. The default default is "help"
=head2 execute_command
$app->execute_command($cmd, \%opt, @args);
This method will invoke C<validate_args> and then C<run> on C<$cmd>.
=head2 plugin_search_path
This method returns the plugin_search_path as set. The default implementation,
if called on "YourApp::Cmd" will return "YourApp::Cmd::Command"
This is a method because it's fun to override it with, for example:
use constant plugin_search_path => __PACKAGE__;
lib/App/Cmd.pm view on Meta::CPAN
=head2 global_opt_spec
Returns a list with help command unless C<no_help_plugin> has been specified or
an empty list. Can be overridden for pre-dispatch option processing. This is
useful for flags like --verbose.
=head2 usage_error
$self->usage_error("Something's wrong!");
Used to die with nice usage output, during C<validate_args>.
=head1 TODO
=over 4
=item *
publish and bring in Log::Speak (simple quiet/verbose output)
=item *
lib/App/Cmd/Command.pm view on Meta::CPAN
#pod after the first.)
#pod
#pod If not overridden, it returns an empty list.
#pod
#pod =cut
sub opt_spec {
return;
}
#pod =method validate_args
#pod
#pod $command_plugin->validate_args(\%opt, \@args);
#pod
#pod This method is passed a hashref of command line options (as processed by
#pod Getopt::Long::Descriptive) and an arrayref of leftover arguments. It may throw
#pod an exception (preferably by calling C<usage_error>, below) if they are invalid,
#pod or it may do nothing to allow processing to continue.
#pod
#pod =cut
sub validate_args { }
#pod =method usage_error
#pod
#pod $self->usage_error("This command must not be run by root!");
#pod
#pod This method should be called to die with human-friendly usage output, during
#pod C<validate_args>.
#pod
#pod =cut
sub usage_error {
my ( $self, $error ) = @_;
die "Error: $error\nUsage: " . $self->_usage_text;
}
sub _usage_text {
my ($self) = @_;
lib/App/Cmd/Command.pm view on Meta::CPAN
the result of the C<command_names> method.
=head2 opt_spec
This method should be overridden to provide option specifications. (This is
list of arguments passed to C<describe_options> from Getopt::Long::Descriptive,
after the first.)
If not overridden, it returns an empty list.
=head2 validate_args
$command_plugin->validate_args(\%opt, \@args);
This method is passed a hashref of command line options (as processed by
Getopt::Long::Descriptive) and an arrayref of leftover arguments. It may throw
an exception (preferably by calling C<usage_error>, below) if they are invalid,
or it may do nothing to allow processing to continue.
=head2 usage_error
$self->usage_error("This command must not be run by root!");
This method should be called to die with human-friendly usage output, during
C<validate_args>.
=head2 abstract
This method returns a short description of the command's purpose. If this
method is not overridden, it will return the abstract from the module's Pod.
If it can't find the abstract, it will look for a comment starting with
"ABSTRACT:" like the ones used by L<Pod::Weaver::Section::Name>.
=head2 description
lib/App/Cmd/Simple.pm view on Meta::CPAN
#pod package YourApp::Cmd 0.01;
#pod use parent qw(App::Cmd::Simple);
#pod
#pod sub opt_spec {
#pod return (
#pod [ "blortex|X", "use the blortex algorithm" ],
#pod [ "recheck|r", "recheck all results" ],
#pod );
#pod }
#pod
#pod sub validate_args {
#pod my ($self, $opt, $args) = @_;
#pod
#pod # no args allowed but options!
#pod $self->usage_error("No args allowed") if @$args;
#pod }
#pod
#pod sub execute {
#pod my ($self, $opt, $args) = @_;
#pod
#pod my $result = $opt->{blortex} ? blortex() : blort();
lib/App/Cmd/Simple.pm view on Meta::CPAN
#pod
#pod This method should be overridden to provide the top level usage line.
#pod It's a one-line summary of how the command is to be invoked, and
#pod should be given in the format used for the C<$usage_desc> parameter to
#pod C<describe_options> in Getopt::Long::Descriptive.
#pod
#pod If not overridden, it returns something that prints out like:
#pod
#pod yourapp [-?h] [long options...]
#pod
#pod =head2 validate_args
#pod
#pod $cmd->validate_args(\%opt, \@args);
#pod
#pod This method is passed a hashref of command line options (as processed by
#pod Getopt::Long::Descriptive) and an arrayref of leftover arguments. It may throw
#pod an exception (preferably by calling C<usage_error>) if they are invalid, or it
#pod may do nothing to allow processing to continue.
#pod
#pod =head2 execute
#pod
#pod Your::App::Cmd::Simple->execute(\%opt, \@args);
#pod
lib/App/Cmd/Simple.pm view on Meta::CPAN
package YourApp::Cmd 0.01;
use parent qw(App::Cmd::Simple);
sub opt_spec {
return (
[ "blortex|X", "use the blortex algorithm" ],
[ "recheck|r", "recheck all results" ],
);
}
sub validate_args {
my ($self, $opt, $args) = @_;
# no args allowed but options!
$self->usage_error("No args allowed") if @$args;
}
sub execute {
my ($self, $opt, $args) = @_;
my $result = $opt->{blortex} ? blortex() : blort();
lib/App/Cmd/Simple.pm view on Meta::CPAN
This method should be overridden to provide the top level usage line.
It's a one-line summary of how the command is to be invoked, and
should be given in the format used for the C<$usage_desc> parameter to
C<describe_options> in Getopt::Long::Descriptive.
If not overridden, it returns something that prints out like:
yourapp [-?h] [long options...]
=head2 validate_args
$cmd->validate_args(\%opt, \@args);
This method is passed a hashref of command line options (as processed by
Getopt::Long::Descriptive) and an arrayref of leftover arguments. It may throw
an exception (preferably by calling C<usage_error>) if they are invalid, or it
may do nothing to allow processing to continue.
=head2 execute
Your::App::Cmd::Simple->execute(\%opt, \@args);
lib/App/Cmd/Tutorial.pod view on Meta::CPAN
#pod =head1 DESCRIPTION
#pod
#pod App::Cmd is a set of tools designed to make it simple to write sophisticated
#pod command line programs. It handles commands with multiple subcommands,
#pod generates usage text, validates options, and lets you write your program as
#pod easy-to-test classes.
#pod
#pod An App::Cmd-based application is made up of three main parts: the script,
#pod the application class, and the command classes.
#pod
#pod =head2 The Script
#pod
#pod The script is the actual executable file run at the command line. It can
#pod generally consist of just a few lines:
#pod
lib/App/Cmd/Tutorial.pod view on Meta::CPAN
#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
lib/App/Cmd/Tutorial.pod view on Meta::CPAN
#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 );
#pod }
#pod
#pod Where C<options> and C<validate> are "inner" methods which your command
#pod subclasses implement to provide command-specific options and validation.
#pod
#pod Note: this is a new file, previously not mentioned in this tutorial and this
#pod tip does not recommend the use of global_opt_spec which offers an alternative
#pod way of specifying global options.
#pod
#pod =head1 TIPS
#pod
#pod =over 4
#pod
lib/App/Cmd/Tutorial.pod view on Meta::CPAN
App::Cmd::Tutorial - getting started with App::Cmd
=head1 VERSION
version 0.337
=head1 DESCRIPTION
App::Cmd is a set of tools designed to make it simple to write sophisticated
command line programs. It handles commands with multiple subcommands,
generates usage text, validates options, and lets you write your program as
easy-to-test classes.
An App::Cmd-based application is made up of three main parts: the script,
the application class, and the command classes.
=head2 The Script
The script is the actual executable file run at the command line. It can
generally consist of just a few lines:
lib/App/Cmd/Tutorial.pod view on Meta::CPAN
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
lib/App/Cmd/Tutorial.pod view on Meta::CPAN
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 );
}
Where C<options> and C<validate> are "inner" methods which your command
subclasses implement to provide command-specific options and validation.
Note: this is a new file, previously not mentioned in this tutorial and this
tip does not recommend the use of global_opt_spec which offers an alternative
way of specifying global options.
=head1 PERL VERSION
This library should run on perls released even a long time ago. It should
work on any version of perl released in the last five years.
t/callback.t view on Meta::CPAN
my $app = $CLASS->new;
is_deeply(
[ sort $app->command_names ],
[ sort qw(help --help -h --version -? commands lol version) ],
"got correct list of registered command names",
);
my $return = test_app('Test::WithCallback', [ qw(lol -e 2) ]);
is($return->stdout, 'yay', "Callback validated correctly");
$return = test_app('Test::WithCallback', [ qw(lol -e 1) ]);
like(
$return->error,
qr/even.+valid.email/,
"Failing Params::Validate callback prints nice error message"
);
t/lib/Test/MySimple.pm view on Meta::CPAN
use Data::Dumper;
sub execute {
my ($self, $opt, $args) = @_;
local $Data::Dumper::Terse = 1;
print Dumper([ $opt, $args ]);
}
sub validate_args {
my ($self, $opt, $args) = @_;
$self->usage_error("not enough args") unless @$args > 0;
}
sub opt_spec {
return [ "fooble|f", "check all foobs for foobling" ],
}
1;
( run in 0.579 second using v1.01-cache-2.11-cpan-4d50c553e7e )