App-Cmdline
view release on metacpan or search on metacpan
docs/App-Cmdline.html view on Meta::CPAN
.pod H4 {
background: transparent;
color: #006699;
font-size: medium;
font-weight: normal;
}
.pod IMG {
vertical-align: top;
}
.pod .toc A {
text-decoration: none;
}
.pod .toc LI {
line-height: 1.2em;
list-style-type: none;
}
/*]]>*/-->
</style>
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.16,
using Pod::Simple::PullParser v3.16,
under Perl v5.014002 at Mon Jun 3 05:59:46 2013 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<div class='indexgroup'>
<ul class='indexList indexList1'>
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
<li class='indexItem indexItem1'><a href='#VERSION'>VERSION</a>
<li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
<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>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>App::Cmdline - helper for writing command-line applications</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="VERSION"
>VERSION</a></h1>
<p>version 0.1.2</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<p>In your command-line script,
e.g.
in <em>myapp</em>:</p>
<pre> use App::myapp;
App::myapp->run;</pre>
<p>Such command-line script will be executed, for example, by:</p>
<pre> senger@ShereKhan$ myapp --version
senger@ShereKhan$ myapp --check
senger@ShereKhan$ myapp -c</pre>
<p>In your module that does the full job you are implementing, e.g. in <em>App/myapp.pm</em>:</p>
<pre> package App::myapp;
use parent 'App::Cmdline';
# Define your own options, and/or add some predefined sets.
sub opt_spec {
my $self = shift;
return $self->check_for_duplicates (
[ 'check|c' => "only check the configuration" ],
$self->composed_of (
'App::Cmdline::Options::Basic',
'App::Cmdline::Options::DB',
)
);
}
# The main job is implemented here
use Data::Dumper;
sub execute {
my ($self, $opt, $args) = @_;
print STDERR "Started...\n" unless $opt->quiet;
print STDOUT 'Options ($opt): ' . Dumper ($opt);
print STDOUT 'Arguments ($args): ' . Dumper ($args);
...
}</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>This module helps to write command-line applications, especially if they need to be fed by some command-line options and arguments. It extends the <a href="http://search.cpan.org/perldoc?App%3A%3ACmd%3A%3ASimple" class="podlinkpod"
>App::Cmd::Simple</a> module by adding the ability to use several predefined sets of options that many real command-line applications use and need anyway. For example, in most applications you need a way how to print its version or how to provide a d...
<p>Your module (representing the application you are writing) should inherit from this module and implement, at least, the method <a href="#opt_spec" class="podlinkpod"
>opt_spec</a> (optionally) and the method <a href="#execute" class="podlinkpod"
>execute</a> (mandatory).</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="METHODS"
>METHODS</a></h1>
<p>In order to use the ability of composing list of options from the existing sets of predefined options (which is, after all, the main <i>raison d'être</i> of this module) use the method <a href="#composed_of" class="podlinkpod"
>composed_of</a>. And to find out that various predefined sets of options do not step on each other toes, use the method <a href="#check_for_duplicates" class="podlinkpod"
>check_for_duplicates</a>.</p>
<p>When writing a subclass of App::Cmdline, there are only a few methods that you might want to overwrite (except for <a href="#execute" class="podlinkpod"
>execute</a> that you <b>must</b> overwrite). Below are those that may be of your interest, or those that are implemented here slightly differently from the <a href="http://search.cpan.org/perldoc?App%3A%3ACmd%3A%3ASimple" class="podlinkpod"
>App::Cmd::Simple</a>.</p>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="Summary_of_methods"
>Summary of methods</a></h3>
<dl>
<dt><a name="Methods_that_you_must_overwrite"
>Methods that you must overwrite</a></dt>
<dd>
<pre> execute()</pre>
<dt><a name="Methods_that_you_should_overwrite"
>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()
usage_error()</pre>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="opt_spec"
><b>opt_spec</b></a></h2>
<p>This method returns a list with option definitions, each element being an arrayref. This returned list is passed (starting as its second argument) to <code>describe_options</code> from <a href="http://search.cpan.org/perldoc?Getopt%3A%3ALong%3A%3A...
>Getopt::Long::Descriptive</a>. You need to check the documentation on how to specify options, but mainly each element is a pair of <i>option specification</i> and the <i>help text for this option</i>. For example:</p>
<pre> sub opt_spec {
my $self = shift;
return
[ 'latitude|y=s' => "geographical latitude" ],
[ 'longitude|x=s' => "geographical longitude" ],
;
}</pre>
<p>The <i>option specification</i> (the first part of each pair) is how the option can appear on the command-line, in its short or long version, if it takes a value, how/if can be repeated, etc.</p>
<p>The option elements can be richer. Another useful piece of the option definition is its default value - see an example of it in <a href="http://search.cpan.org/perldoc?App%3A%3ACmdline%3A%3AOptions%3A%3ADB#OPTIONS" class="podlinkpod"
>"OPTIONS" in App::Cmdline::Options::DB</a>.</p>
<p>The example above, however, does not add anything new to the <a href="http://search.cpan.org/perldoc?App%3A%3ACmd%3A%3ASimple" class="podlinkpod"
>App::Cmd::Simple</a>. Specifying the options this way, you could (and probably should) inherit directly from the <a href="http://search.cpan.org/perldoc?App%3A%3ACmd%3A%3ASimple" class="podlinkpod"
>App::Cmd::Simple</a> without using <code>App::Cmdline</code>. Therefore, let's have another example:</p>
<pre> sub opt_spec {
my $self = shift;
return
[ 'latitude|y=s' => "geographical latitude" ],
[ 'longitude|x=s' => "geographical longitude" ],
$self->composed_of (
'App::Cmdline::Options::Basic',
'App::Cmdline::Options::DB',
);
}</pre>
<p>In this example, your command-line application will recognize the same options (latitude and longitude) as before and, additionally, all options that were predefined in the <i>role</i> classes <a href="http://search.cpan.org/perldoc?App%3A%3ACmdli...
>App::Cmdline::Options::Basic</a> and <a href="http://search.cpan.org/perldoc?App%3A%3ACmdline%3A%3AOptions%3A%3ADB" class="podlinkpod"
>App::Cmdline::Options::DB</a>. See more about these classes in <a href="#PREDEFINED_SETS_OF_OPTIONS" class="podlinkpod"
>"PREDEFINED SETS OF OPTIONS"</a>;</p>
<p>If not overridden, it returns an empty list.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="composed_of"
><b>composed_of</b></a></h2>
docs/App-Cmdline.html view on Meta::CPAN
<p>I can run (and get dumped the recognized options and arguments in the <code>execute</code> method:</p>
<pre> senger@ShereKhan2:myapp -x -y
Executing...
Options ($opt): $VAR1 = bless( {
'xpoint' => 1,
'ypoint' => 1
}, 'Getopt::Long::Descriptive::Opts::__OPT__::2' );
Arguments ($args): $VAR1 = [];</pre>
<p>You can see that both options, <code>-x</code> and <code>-y</code>, were recognized. But if I bundle them (and by default, the bundling is disabled), I get no recognized options; instead they will be shown as arguments (arguments being everything ...
<pre> senger@ShereKhan2:myapp -x -y
Executing...
Options ($opt): $VAR1 = bless( {}, 'Getopt::Long::Descriptive::Opts::__OPT__::2' );
Arguments ($args): $VAR1 = [ '-xy' ];</pre>
<p>But if I change the configuration by implementing:</p>
<pre> sub getopt_conf {
return [ 'bundling' ];
}</pre>
<p>the bundled options are now recognized as options (and no argument reminded):</p>
<pre> senger@ShereKhan2:myapp -xy
Executing...
Options ($opt): $VAR1 = bless( {
'xpoint' => 1,
'ypoint' => 1
}, 'Getopt::Long::Descriptive::Opts::__OPT__::2' );
Arguments ($args): $VAR1 = [];</pre>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="usage_desc"
><b>usage_desc</b></a></h2>
<p>The returned value from this method will be used as the first line of the usage message. The full usage is returned by another method, <code>usage</code>, that you usually do not overwrite because its default behaviour is to create a reasonable su...
>opt_spec</a> method and, possibly, by this <code>usage_desc</code> method.</p>
<p>Behind the scene, the returned string is interpreted by the <a href="http://search.cpan.org/perldoc?Getopt%3A%3ALong%3A%3ADescriptive" class="podlinkpod"
>Getopt::Long::Descriptive</a> which accepts also few special constructs:</p>
<ul>
<li>%c will be replaced with what <code>Getopt::Long::Descriptive</code> thinks is the program name (it is computed from $0).</li>
<li>%o will be replaced with a list of the short options, as well as the text "[long options...]" if any have been defined.</li>
<li>Literal % characters will need to be written as %%, just like with sprintf.</li>
</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
-v --version display a version</pre>
<p>The example also shows calling the method <code>usage_error</code>. Unless you overwrite also this method, it prints the given error message together with the usage and dies.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="execute"
><b>execute</b></a></h2>
<p>Last but definitely not least. You <b>have</b> to implement this method and put here whatever your command-line application is supposed to do.</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>
<pre> sub execute {
my ($self, $opt, $args) = @_;
if ($opt->crystal eq 'ball') {
print ask_ball ($args->[0]);
} else {
die "All is vanity...\n"
unless $opt->godess;
}
}</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="PREDEFINED_SETS_OF_OPTIONS"
>PREDEFINED SETS OF OPTIONS</a></h1>
<p>The predefined sets of options are represented by classes that are considered rather <code>roles</code>. You do not extend them (inherit from them) but you just use them (by naming them in the method <a href="#composed_of" class="podlinkpod"
>composed_of</a>).</p>
<p>This distribution bundles several of such classes. See their own documentation to find out what options they provide. Here is just a quick summary:</p>
<dl>
<dt><a name="App::Cmdline::Options::Basic"
><a href="http://search.cpan.org/perldoc?App%3A%3ACmdline%3A%3AOptions%3A%3ABasic" class="podlinkpod"
>App::Cmdline::Options::Basic</a></a></dt>
<dd>
<p>Provides basic options (help and version).</p>
<dt><a name="App::Cmdline::Options::ExtBasic"
><a href="http://search.cpan.org/perldoc?App%3A%3ACmdline%3A%3AOptions%3A%3AExtBasic" class="podlinkpod"
>App::Cmdline::Options::ExtBasic</a></a></dt>
<dd>
<p>Provides the same options as in <a href="http://search.cpan.org/perldoc?App%3A%3ACmdline%3A%3AOptions%3A%3ABasic" class="podlinkpod"
>App::Cmdline::Options::Basic</a> and adds options for richer documentation.</p>
<dt><a name="App::Cmdline::Options::DB"
><a href="http://search.cpan.org/perldoc?App%3A%3ACmdline%3A%3AOptions%3A%3ADB" class="podlinkpod"
>App::Cmdline::Options::DB</a></a></dt>
<dd>
<p>Provides options for accessing a database (user authentication, host and port name, etc.).</p>
<dt><a name="App::Cmdline::Options::ExtDB"
><a href="http://search.cpan.org/perldoc?App%3A%3ACmdline%3A%3AOptions%3A%3AExtDB" class="podlinkpod"
>App::Cmdline::Options::ExtDB</a></a></dt>
<dd>
<p>Provides the same options as in <a href="http://search.cpan.org/perldoc?App%3A%3ACmdline%3A%3AOptions%3A%3ADB" class="podlinkpod"
>App::Cmdline::Options::DB</a> and adds an option for showing what values were given by the database-related options.</p>
</dd>
</dl>
<h3><a class='u' href='#___top' title='click to go to top of document'
name="How_to_create_a_new_predefined_set"
>How to create a new predefined set</a></h3>
<p>You may wish to create a new set of options if you want to re-use them. For application-specific options, used only once, you do not need to have a predefined set, you just specify them directly in the <a href="#opt_spec" class="podlinkpod"
>opt_spec</a> method.</p>
<p>The classes that can be used as the predefined sets of options do not inherit from any common class (so far, there was no need for it) - unless one extends another one (as is the case of <a href="http://search.cpan.org/perldoc?App%3A%3ACmdline%3A%...
>App::Cmdline::Options::ExtBasic</a>). It is, however, recommended, to use the namespace <i>App::Cmdline::Options::</i> - just to find them easier on CPAN.</p>
<p>Each of these classes should implement up to two methods:</p>
<dl>
<dt><a name="get_opt_spec"
><b>get_opt_spec</b></a></dt>
<dd>
<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>
<p>Martin Senger <martin.senger@gmail.com></p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="COPYRIGHT_AND_LICENSE"
>COPYRIGHT AND LICENSE</a></h1>
<p>This software is copyright (c) 2013 by Martin Senger, CBRC - KAUST (Computational Biology Research Center - King Abdullah University of Science and Technology) All Rights Reserved.</p>
<p>This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.</p>
<!-- end doc -->
</body></html>
( run in 2.068 seconds using v1.01-cache-2.11-cpan-39bf76dae61 )