view release on metacpan or  search on metacpan

lib/App/Cmdline.pm  view on Meta::CPAN

the usage and exits.

This distribution contains few such classes (see the L<"PREDEFINED
SETS OF OPTIONS">). Later, they may be published other similar classes
providing different sets of options.

The method returns a list of options definitions that is suitable
for including in the returned values of the L<opt_spec|"opt_spec">
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 element of the returned
list is a hashref containing configuration for the L<Getopt::Long> -
as described in the L<Getopt::Long::Descriptive>. 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 anything
after that:

   sub opt_spec {
       my $self = shift;
       my @db_options = $self->composed_of ('App::Cmdline::Options::DB');
       pop @db_options;
       return
           @db_options,
           [ 'latitude|y=s'  => "geographical latitude"  ],
           [ 'longitude|x=s' => "geographical longitude" ],
           $self->composed_of (
               'App::Cmdline::Options::Basic',
           );
   }

The last example looks a bit inconvenient. And you do not need to do
it that way - because the C<composed_of> method accepts also any
arrayrefs, ignoring them and just passing them to its return
value. That's why you really can call this method only once and not to
be bothered with the hashref at the end. Here is an example how you
can combine class names (predefined sets) with your own option
specification and/or usage separators (the empty arrayrefs):

    return
        [ 'check|c' => "only check the configuration"  ],
        [],
        $self->composed_of (
            'App::Cmdline::Options::DB',
            [ 'show|s' => "show database access properties"  ],
            [],
            'App::Cmdline::Options::Basic',
        );

which - when called with the -h option - shows this nicely formatted
usage:

    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

=head2 B<check_for_duplicates>

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, and returning the same list
unchanged. It can, therefore, be used like this:

   sub opt_spec {
       my $self = shift;
       return $self->check_for_duplicates (
           [ 'latitude|y=s'  => "geographical latitude"  ],
           [ 'longitude|x=s' => "geographical longitude" ],
           $self->composed_of (
               'App::Cmdline::Options::Basic',
               'App::Cmdline::Options::DB',
           )
       );
   }

=head2 B<getopt_conf>

The machinery behind the scene is done by the L<Getopt::Long>
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 recognized strings you need to read the
L<Getopt::Long/"Configuring Getopt::Long">. Here is shown how and
when to use them.

The C<App::Cmdline> provides a default set of strings:

   sub getopt_conf {
       return [
          'no_bundling',
          'no_ignore_case',
          'auto_abbrev',
       ];
   }

If you need it differently, override the getopt_conf method, returning
an arrayref with configuration strings you want. Here are the examples
showing the difference. Using the default configuration and having the
following options:

   sub opt_spec {
       my $self = shift;
       return
           [ 'xpoint|x' => 'make an X point'],
           [ 'ypoint|y' => 'make a  Y point'],
           [],
           $self->composed_of (
               'App::Cmdline::Options::Basic',
           );