view release on metacpan or  search on metacpan

docs/App-Cmdline.html  view on Meta::CPAN

           $self->composed_of (
               'App::Cmdline::Options::Basic',
           );
   }</pre>

<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( {
      &#39;xpoint&#39; =&#62; 1,
      &#39;ypoint&#39; =&#62; 1
       }, &#39;Getopt::Long::Descriptive::Opts::__OPT__::2&#39; );
   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( {}, &#39;Getopt::Long::Descriptive::Opts::__OPT__::2&#39; );
   Arguments ($args): $VAR1 = [ &#39;-xy&#39; ];</pre>

<p>But if I change the configuration by implementing:</p>

<pre>   sub getopt_conf {
       return [ &#39;bundling&#39; ];
   }</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( {
      &#39;xpoint&#39; =&#62; 1,
      &#39;ypoint&#39; =&#62; 1
       }, &#39;Getopt::Long::Descriptive::Opts::__OPT__::2&#39; );
   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 &#34;[long options...]&#34; 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-&#62;SUPER::usage_desc() . &#39; ...and anything else&#39;;
   }</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"
>&#34;PREDEFINED SETS OF OPTIONS&#34;</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>&#39;s validate_args method. Therefore, it is strongly recommend...

<pre>   sub validate_args {
       my ($self, $opt, $args) = @_;
       $self-&#62;SUPER::validate_args ($opt, $args);
       if ($opt-&#62;number and scalar @$args != $opt-&#62;number) {
          $self-&#62;usage_error (&#34;Option --number does not correspond with the number of arguments&#34;);
       }
   }

   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] &#60;some arguments...&#62;
        -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-&#62;crystal eq &#39;ball&#39;) {
          print ask_ball ($args-&#62;[0]);
       } else {
          die &#34;All is vanity...\n&#34;
             unless $opt-&#62;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"