view release on metacpan or  search on metacpan

README  view on Meta::CPAN

       Options ($opt):    $VAR1 = bless( {
          'xpoint' => 1,
          'ypoint' => 1
           }, 'Getopt::Long::Descriptive::Opts::__OPT__::2' );
       Arguments ($args): $VAR1 = [];

    You can see that both options, "-x" and "-y", 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 what remained not recognized on the command-line):

       senger@ShereKhan2:myapp -x -y
       Executing...
       Options ($opt):    $VAR1 = bless( {}, 'Getopt::Long::Descriptive::Opts::__OPT__::2' );
       Arguments ($args): $VAR1 = [ '-xy' ];

    But if I change the configuration by implementing:

       sub getopt_conf {
           return [ 'bundling' ];
       }

    the bundled options are now recognized as options (and no argument
    reminded):

       senger@ShereKhan2:myapp -xy
       Executing...
       Options ($opt):    $VAR1 = bless( {
          'xpoint' => 1,
          'ypoint' => 1
           }, 'Getopt::Long::Descriptive::Opts::__OPT__::2' );
       Arguments ($args): $VAR1 = [];

  usage_desc
    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,
    "usage", that you usually do not overwrite because its default behaviour
    is to create a reasonable summary from the help texts you provided in
    the opt_spec method and, possibly, by this "usage_desc" method.

    Behind the scene, the returned string is interpreted by the
    Getopt::Long::Descriptive which accepts also few special constructs:

    *   %c will be replaced with what "Getopt::Long::Descriptive" thinks is
        the program name (it is computed from $0).

    *   %o will be replaced with a list of the short options, as well as the
        text "[long options...]" if any have been defined.

    *   Literal % characters will need to be written as %%, just like with
        sprintf.

    By default, the "App::Cmdline" returns slightly different usage
    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
            -v --version    display a version

    The example also shows calling the method "usage_error". Unless you
    overwrite also this method, it prints the given error message together
    with the usage and dies.

  execute
    Last but definitely not least. You have to implement this method and put
    here whatever your command-line application is supposed to do.

    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.

       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;
           }
       }

PREDEFINED SETS OF OPTIONS
    The predefined sets of options are represented by classes that are
    considered rather "roles". You do not extend them (inherit from them)
    but you just use them (by naming them in the method composed_of).

    This distribution bundles several of such classes. See their own
    documentation to find out what options they provide. Here is just a
    quick summary:

    App::Cmdline::Options::Basic
        Provides basic options (help and version).

    App::Cmdline::Options::ExtBasic
        Provides the same options as in App::Cmdline::Options::Basic and
        adds options for richer documentation.

    App::Cmdline::Options::DB
        Provides options for accessing a database (user authentication, host
        and port name, etc.).

    App::Cmdline::Options::ExtDB
        Provides the same options as in App::Cmdline::Options::DB and adds
        an option for showing what values were given by the database-related
        options.