App-Cmdline
view release on metacpan or search on metacpan
Summary of methods
Methods that you must overwrite
execute()
Methods that you should overwrite
opt_spec()
Methods that you may overwrite
usage_desc()
validate_args()
usage_error()
getopt_conf()
...
Methods that you just call
composed_of()
check_for_duplicates()
usage_error()
opt_spec
description depending on the bundling configuration option (see
getopt_conf): if the bundling is disabled, the bundle of all short
options is not shown. Often, you want to use whatever "App::Cmdline"
returns plus what you wish to add on the first line of the usage. For
example:
sub usage_desc {
return shift->SUPER::usage_desc() . ' ...and anything else';
}
validate_args
Originally, this method was meant to check (validate) the command-line
arguments (remember that arguments are whatever remains on the
command-line after options defined in the opt_spec method have been
processed). The options themselves could be already validated by various
subroutines and attributes given in the option specifications (as
described, sometimes only vaguely, in the Getopt::Long::Descriptive).
But sometimes, it is useful to have all validation, of options and of
arguments, in one place - so we have this method.
The method gets two parameters, $opt and $args. The first one is an
instance of Getopt::Long::Descriptive::Opts giving you access to all
existing options, using their names (as were defined in opt_spec) as the
access methods. The second parameter is an arrayref containing all
remaining arguments on the command-line.
*Important:* Some predefined sets of options (see the "PREDEFINED SETS
OF OPTIONS") do also some checking (or other actions, like printing the
version and exiting) and this checking is invoked from the
"App::Cmdline"'s validate_args method. Therefore, it is strongly
recommended that if you overwrite this method, you also call the SUPER:
sub validate_args {
my ($self, $opt, $args) = @_;
$self->SUPER::validate_args ($opt, $args);
if ($opt->number and scalar @$args != $opt->number) {
$self->usage_error ("Option --number does not correspond with the number of arguments");
}
}
senger@ShereKhan2:myapp -n 2 a b c
Error: Option --number does not correspond with the number of arguments
Usage: myapp [short or long options, not bundled] <some arguments...>
-n --number expected number of args
-h display a short usage message
class can hardly predefine any new options. The method should return
a list of arrayrefs, suitable to be consumed by the opt_spec method.
For example (taken from the App::Cmdline::Options::Basic):
sub get_opt_spec {
return
[ 'h' => "display a short usage message" ],
[ 'version|v' => "display a version" ];
}
validate_opts
This method, if exists, will be called from the validate_args
method. Its purpose is to do something with the options belonging to
(predefined by) this class.
It gets four parameters, $app (the class name of your application),
$caller (who is calling), $opts (an object allowing to access all
options) and $args (an arrayref with the remaining arguments from
the command-line).
If it finds an error, it usually dies by calling
$caller->"usage_error".
docs/App-Cmdline.html view on Meta::CPAN
<li class='indexItem indexItem1'><a href='#METHODS'>METHODS</a>
<ul class='indexList indexList2'>
<ul class='indexList indexList3'>
<li class='indexItem indexItem3'><a href='#Summary_of_methods'>Summary of methods</a>
</ul>
<li class='indexItem indexItem2'><a href='#opt_spec'>opt_spec</a>
<li class='indexItem indexItem2'><a href='#composed_of'>composed_of</a>
<li class='indexItem indexItem2'><a href='#check_for_duplicates'>check_for_duplicates</a>
<li class='indexItem indexItem2'><a href='#getopt_conf'>getopt_conf</a>
<li class='indexItem indexItem2'><a href='#usage_desc'>usage_desc</a>
<li class='indexItem indexItem2'><a href='#validate_args'>validate_args</a>
<li class='indexItem indexItem2'><a href='#execute'>execute</a>
</ul>
<li class='indexItem indexItem1'><a href='#PREDEFINED_SETS_OF_OPTIONS'>PREDEFINED SETS OF OPTIONS</a>
<ul class='indexList indexList2'>
<ul class='indexList indexList3'>
<li class='indexItem indexItem3'><a href='#How_to_create_a_new_predefined_set'>How to create a new predefined set</a>
</ul>
</ul>
<li class='indexItem indexItem1'><a href='#AUTHOR'>AUTHOR</a>
<li class='indexItem indexItem1'><a href='#COPYRIGHT_AND_LICENSE'>COPYRIGHT AND LICENSE</a>
docs/App-Cmdline.html view on Meta::CPAN
>Methods that you should overwrite</a></dt>
<dd>
<pre> opt_spec()</pre>
<dt><a name="Methods_that_you_may_overwrite"
>Methods that you may overwrite</a></dt>
<dd>
<pre> usage_desc()
validate_args()
usage_error()
getopt_conf()
...</pre>
<dt><a name="Methods_that_you_just_call"
>Methods that you just call</a></dt>
<dd>
<pre> composed_of()
check_for_duplicates()
docs/App-Cmdline.html view on Meta::CPAN
</ul>
<p>By default, the <code>App::Cmdline</code> returns slightly different usage description depending on the bundling configuration option (see <a href="#getopt_conf" class="podlinkpod"
>getopt_conf</a>): if the bundling is disabled, the bundle of all short options is not shown. Often, you want to use whatever <code>App::Cmdline</code> returns plus what you wish to add on the first line of the usage. For example:</p>
<pre> sub usage_desc {
return shift->SUPER::usage_desc() . ' ...and anything else';
}</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="validate_args"
><b>validate_args</b></a></h2>
<p>Originally, this method was meant to check (validate) the command-line arguments (remember that arguments are whatever remains on the command-line after options defined in the <a href="#opt_spec" class="podlinkpod"
>opt_spec</a> method have been processed). The options themselves could be already validated by various subroutines and attributes given in the option specifications (as described, sometimes only vaguely, in the <a href="http://search.cpan.org/perldo...
>Getopt::Long::Descriptive</a>). But sometimes, it is useful to have all validation, of options and of arguments, in one place - so we have this method.</p>
<p>The method gets two parameters, <code>$opt</code> and <code>$args</code>. The first one is an instance of <a href="http://search.cpan.org/perldoc?Getopt%3A%3ALong%3A%3ADescriptive%3A%3AOpts" class="podlinkpod"
>Getopt::Long::Descriptive::Opts</a> giving you access to all existing options, using their names (as were defined in <a href="#opt_spec" class="podlinkpod"
>opt_spec</a>) as the access methods. The second parameter is an arrayref containing all remaining arguments on the command-line.</p>
<p><i>Important:</i> Some predefined sets of options (see the <a href="#PREDEFINED_SETS_OF_OPTIONS" class="podlinkpod"
>"PREDEFINED SETS OF OPTIONS"</a>) do also some checking (or other actions, like printing the version and exiting) and this checking is invoked from the <code>App::Cmdline</code>'s validate_args method. Therefore, it is strongly recommend...
<pre> sub validate_args {
my ($self, $opt, $args) = @_;
$self->SUPER::validate_args ($opt, $args);
if ($opt->number and scalar @$args != $opt->number) {
$self->usage_error ("Option --number does not correspond with the number of arguments");
}
}
senger@ShereKhan2:myapp -n 2 a b c
Error: Option --number does not correspond with the number of arguments
Usage: myapp [short or long options, not bundled] <some arguments...>
-n --number expected number of args
-h display a short usage message
docs/App-Cmdline.html view on Meta::CPAN
<p>Strictly speaking, it is not mandatory, but without this method the class can hardly predefine any new options. The method should return a list of arrayrefs, suitable to be consumed by the <a href="#opt_spec" class="podlinkpod"
>opt_spec</a> method. For example (taken from the <a href="http://search.cpan.org/perldoc?App%3A%3ACmdline%3A%3AOptions%3A%3ABasic" class="podlinkpod"
>App::Cmdline::Options::Basic</a>):</p>
<pre> sub get_opt_spec {
return
[ 'h' => "display a short usage message" ],
[ 'version|v' => "display a version" ];
}</pre>
<dt><a name="validate_opts"
><b>validate_opts</b></a></dt>
<dd>
<p>This method, if exists, will be called from the <a href="#validate_args" class="podlinkpod"
>validate_args</a> method. Its purpose is to do something with the options belonging to (predefined by) this class.</p>
<p>It gets four parameters, <code>$app</code> (the class name of your application), <code>$caller</code> (who is calling), <code>$opts</code> (an object allowing to access all options) and <code>$args</code> (an arrayref with the remaining arguments ...
<p>If it finds an error, it usually dies by calling $caller-><code>usage_error</code>.</p>
</dd>
</dl>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
lib/App/Cmdline.pm view on Meta::CPAN
my $config = { map { $_ => 1 } @{ $self->getopt_conf() } };
if (exists $config->{'no_bundling'}) {
return "%c [short or long options, not bundled]";
} else {
return "%c %o";
}
}
# ----------------------------------------------------------------
# Create (and return) option definitions from wanted option sets
# (given as class names). Also install the validate_args() subroutine
# that will call validate_opts() on all wanted option sets.
# ----------------------------------------------------------------
sub composed_of {
my $self = shift;
my @option_classes = @_; # list of class names with wanted options sets
# create option definitions
my @opt_spec = ();
foreach my $set (@option_classes) {
push (@opt_spec, $set) and next if ref ($set);
## no critic
lib/App/Cmdline.pm view on Meta::CPAN
} else {
warn "Cannot find the set of options $set. The set is, therefore, ignored.\n";
}
}
# install a dispatcher of all validating methods
Sub::Install::reinstall_sub ({
code => sub {
foreach my $set (@option_classes) {
next if ref ($set);
if ($set->can ('validate_opts')) {
$set->validate_opts ($self, @_);
}
}
},
as => 'validate_args',
});
# add the configuration options
return (@opt_spec, { getopt_conf => $self->getopt_conf() } );
}
# ----------------------------------------------------------------
# Check if the given set of options has duplications. Warn if yes.
# ----------------------------------------------------------------
sub check_for_duplicates {
my ($self, @opt_spec) = @_;
lib/App/Cmdline.pm view on Meta::CPAN
execute()
=item Methods that you should overwrite
opt_spec()
=item Methods that you may overwrite
usage_desc()
validate_args()
usage_error()
getopt_conf()
...
=item Methods that you just call
composed_of()
check_for_duplicates()
usage_error()
lib/App/Cmdline.pm view on Meta::CPAN
description depending on the bundling configuration option (see
L<getopt_conf|"getopt_conf">): if the bundling is disabled, the bundle
of all short options is not shown. Often, you want to use whatever
C<App::Cmdline> returns plus what you wish to add on the first line of
the usage. For example:
sub usage_desc {
return shift->SUPER::usage_desc() . ' ...and anything else';
}
=head2 B<validate_args>
Originally, this method was meant to check (validate) the command-line
arguments (remember that arguments are whatever remains on the
command-line after options defined in the L<opt_spec|"opt_spec">
method have been processed). The options themselves could be already
validated by various subroutines and attributes given in the option
specifications (as described, sometimes only vaguely, in the
L<Getopt::Long::Descriptive>). But sometimes, it is useful to have all
validation, of options and of arguments, in one place - so we have
this method.
The method gets two parameters, C<$opt> and C<$args>. The first one is
an instance of L<Getopt::Long::Descriptive::Opts> giving you access to
all existing options, using their names (as were defined in
L<opt_spec|"opt_spec">) as the access methods. The second parameter is
an arrayref containing all remaining arguments on the command-line.
I<Important:> Some predefined sets of options (see the L<"PREDEFINED
SETS OF OPTIONS">) do also some checking (or other actions, like
printing the version and exiting) and this checking is invoked from
the C<App::Cmdline>'s validate_args method. Therefore, it is strongly
recommended that if you overwrite this method, you also call the SUPER:
sub validate_args {
my ($self, $opt, $args) = @_;
$self->SUPER::validate_args ($opt, $args);
if ($opt->number and scalar @$args != $opt->number) {
$self->usage_error ("Option --number does not correspond with the number of arguments");
}
}
senger@ShereKhan2:myapp -n 2 a b c
Error: Option --number does not correspond with the number of arguments
Usage: myapp [short or long options, not bundled] <some arguments...>
-n --number expected number of args
-h display a short usage message
lib/App/Cmdline.pm view on Meta::CPAN
a list of arrayrefs, suitable to be consumed by the
L<opt_spec|"opt_spec"> method. For example (taken from the
L<App::Cmdline::Options::Basic>):
sub get_opt_spec {
return
[ 'h' => "display a short usage message" ],
[ 'version|v' => "display a version" ];
}
=item B<validate_opts>
This method, if exists, will be called from the
L<validate_args|"validate_args"> method. Its purpose is to do
something with the options belonging to (predefined by) this class.
It gets four parameters, C<$app> (the class name of your application),
C<$caller> (who is calling), C<$opts> (an object allowing to access
all options) and C<$args> (an arrayref with the remaining arguments
from the command-line).
If it finds an error, it usually dies by calling
$caller->C<usage_error>.
lib/App/Cmdline/Options/Basic.pm view on Meta::CPAN
return @OPT_SPEC;
}
# ----------------------------------------------------------------
# Do typical actions with my options.
#
# Why am I first trying with $opt->can? Just in case, somebody called
# composed_of (which instaled a call here) but has not returned (from
# opt_spec) what the composed_of returned him).
# ----------------------------------------------------------------
sub validate_opts {
my ($class, $app, $caller, $opt, $args) = @_;
# show help and exit
if ($opt->can ('h') and $opt->h) {
print "Usage: " . $caller->usage();
if ($^S) { die "Okay\n" } else { exit (0) };
}
# show version and exit
if ($opt->can ('version') and $opt->version) {
lib/App/Cmdline/Options/ExtBasic.pm view on Meta::CPAN
# ----------------------------------------------------------------
# Return definition of my options
# ----------------------------------------------------------------
sub get_opt_spec {
return shift->SUPER::get_opt_spec(), @OPT_SPEC;
}
# ----------------------------------------------------------------
# Do typical actions with my options
# ----------------------------------------------------------------
sub validate_opts {
my ($class, $app, $caller, $opt, $args) = @_;
$class->SUPER::validate_opts ($app, $caller, $opt, $args);
# show various levels of help and exit
my $pod_where = pod_where ({-inc => 1}, $app);
pod2usage (-input => $pod_where, -verbose => 1, -exitval => 'NOEXIT')
if $opt->can ('help') and $opt->help;
pod2usage (-input => $pod_where, -verbose => 2, -exitval => 'NOEXIT')
if $opt->can ('man') and $opt->man;
if ( ($opt->can ('help') and $opt->help) or ($opt->can ('man') and $opt->man) ) {
if ($^S) { die "Okay\n" } else { exit (0) };
}
lib/App/Cmdline/Options/ExtDB.pm view on Meta::CPAN
# ----------------------------------------------------------------
# Return definition of my options
# ----------------------------------------------------------------
sub get_opt_spec {
return shift->SUPER::get_opt_spec(), @OPT_SPEC;
}
# ----------------------------------------------------------------
# Do typical actions with my options
# ----------------------------------------------------------------
sub validate_opts {
my ($class, $app, $caller, $opt, $args) = @_;
if ($opt->dbshow) {
print "DBNAME: ", ($opt->dbname || 'n/a'), "\n";
print "DBHOST: ", ($opt->dbhost || 'n/a'), "\n";
print "DBPORT: ", ($opt->dbport || 'n/a'), "\n";
print "DBUSER: ", ($opt->dbuser || 'n/a'), "\n";
print "DBPASS: ", ($opt->dbpasswd ? '...given but not shown' : 'n/a'), "\n";
print "DBSOCK: ", ($opt->dbsocket || 'n/a'), "\n";
}
t/01-testapp.t view on Meta::CPAN
# # [ 'ypoint|y' => 'make a Y point'],
# [ 'number|n=i' => 'expected number of arguments'],
# $self->composed_of (
# 'App::Cmdline::Options::ExtBasic',
# );
# }
# Use this for validating your options (and remaining arguments).
# sub validate_args {
# my ($self, $opt, $args) = @_;
# $self->SUPER::validate_args ($opt, $args);
# if ($opt->number and scalar @$args != $opt->number) {
# $self->usage_error ("Option --number does not correspond with the number of arguments");
# }
# }
# Use this for changing the first line of the Usage message.
# sub usage_desc {
# my $self = shift;
# return $self->SUPER::usage_desc() . " <some arguments...>";
# }
t/App/testapp.pm view on Meta::CPAN
# # [ 'ypoint|y' => 'make a Y point'],
# [ 'number|n=i' => 'expected number of arguments'],
# $self->composed_of (
# 'App::Cmdline::Options::ExtBasic',
# );
# }
# Use this for validating your options (and remaining arguments).
# sub validate_args {
# my ($self, $opt, $args) = @_;
# $self->SUPER::validate_args ($opt, $args);
# if ($opt->number and scalar @$args != $opt->number) {
# $self->usage_error ("Option --number does not correspond with the number of arguments");
# }
# }
# Use this for changing the first line of the Usage message.
# sub usage_desc {
# my $self = shift;
# return $self->SUPER::usage_desc() . " <some arguments...>";
# }
( run in 0.607 second using v1.01-cache-2.11-cpan-a5abf4f5562 )