view release on metacpan or  search on metacpan

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

           [ '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"
>&#34;OPTIONS&#34; 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&#39;s have another example:</p>

<pre>   sub opt_spec {
       my $self = shift;
       return
           [ &#39;latitude|y=s&#39;  =&#62; &#34;geographical latitude&#34;  ],
           [ &#39;longitude|x=s&#39; =&#62; &#34;geographical longitude&#34; ],
           $self-&#62;composed_of (
               &#39;App::Cmdline::Options::Basic&#39;,
               &#39;App::Cmdline::Options::DB&#39;,
           );
   }</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"
>&#34;PREDEFINED SETS OF OPTIONS&#34;</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>

<p>The core method of this module. You call it with a list of names of the classes that are able to give back a list of predefined options that you may instantly use. The classes are not only specifying their options but, for some options, they also ...
>App::Cmdline::Options::Basic</a>) prints the usage and exits.</p>

<p>This distribution contains few such classes (see the <a href="#PREDEFINED_SETS_OF_OPTIONS" class="podlinkpod"
>&#34;PREDEFINED SETS OF OPTIONS&#34;</a>). Later, they may be published other similar classes providing different sets of options.</p>

<p>The method returns a list of options definitions that is suitable for including in the returned values of the <a href="#opt_spec" class="podlinkpod"
>opt_spec</a> method (as it was shown in the example above). The returned value should always be used only at the end, after your application specifies its own options (those that are not coming from any predefined set). This is because the last elem...
>Getopt::Long</a> - as described in the <a href="http://search.cpan.org/perldoc?Getopt%3A%3ALong%3A%3ADescriptive" class="podlinkpod"
>Getopt::Long::Descriptive</a>. Therefore, if you need to call this method more than once or not at the end, perhaps because you wish to see the options in the help usage in a different order, you need to remove its last element before you add anythi...

<pre>   sub opt_spec {
       my $self = shift;
       my @db_options = $self-&#62;composed_of (&#39;App::Cmdline::Options::DB&#39;);
       pop @db_options;
       return
           @db_options,
           [ &#39;latitude|y=s&#39;  =&#62; &#34;geographical latitude&#34;  ],
           [ &#39;longitude|x=s&#39; =&#62; &#34;geographical longitude&#34; ],
           $self-&#62;composed_of (
               &#39;App::Cmdline::Options::Basic&#39;,
           );
   }</pre>

<p>The last example looks a bit inconvenient. And you do not need to do it that way - because the <code>composed_of</code> method accepts also any arrayrefs, ignoring them and just passing them to its return value. That&#39;s why you really can call ...

<pre>    return
        [ &#39;check|c&#39; =&#62; &#34;only check the configuration&#34;  ],
        [],
        $self-&#62;composed_of (
            &#39;App::Cmdline::Options::DB&#39;,
            [ &#39;show|s&#39; =&#62; &#34;show database access properties&#34;  ],
            [],
            &#39;App::Cmdline::Options::Basic&#39;,
        );</pre>

<p>which - when called with the -h option - shows this nicely formatted usage:</p>

<pre>    Usage: myapp [short or long options, not bundled]
        -c --check      only check the configuration

        --dbname        database name
        --dbhost        hostname hosting database
        --dbport        database port number
        --dbuser        user name to access database
        --dbpasswd      password to access database
        --dbsocket      UNIX socket accessing the database
        -s --show       show database access properties

        -h              display a short usage message
        -v --version    display a version</pre>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="check_for_duplicates"
><b>check_for_duplicates</b></a></h2>

<p>When you are composing options from more sets, it is worth to check whether, unintentionally, some options are not duplicated. It can be done by this method that gets the list of options definitions, checks it (warning if any duplicate was found, ...

<pre>   sub opt_spec {
       my $self = shift;
       return $self-&#62;check_for_duplicates (
           [ &#39;latitude|y=s&#39;  =&#62; &#34;geographical latitude&#34;  ],
           [ &#39;longitude|x=s&#39; =&#62; &#34;geographical longitude&#34; ],
           $self-&#62;composed_of (
               &#39;App::Cmdline::Options::Basic&#39;,
               &#39;App::Cmdline::Options::DB&#39;,
           )
       );
   }</pre>

<h2><a class='u' href='#___top' title='click to go to top of document'
name="getopt_conf"
><b>getopt_conf</b></a></h2>

<p>The machinery behind the scene is done by the <a href="http://search.cpan.org/perldoc?Getopt%3A%3ALong" class="podlinkpod"
>Getopt::Long</a> module. This module can be configured by a list of strings in order to achieve a different interpretation of the command-line options. Such as to treat them case-insensitively, or to allow them to be bundled together. For the recogn...
>&#34;Configuring Getopt::Long&#34; in Getopt::Long</a>. Here is shown how and when to use them.</p>

<p>The <code>App::Cmdline</code> provides a default set of strings:</p>

<pre>   sub getopt_conf {
       return [
          &#39;no_bundling&#39;,
          &#39;no_ignore_case&#39;,
          &#39;auto_abbrev&#39;,