NAME
   Declare::CLI - Declarative command line interface builder.

DESCRIPTION
   This module can be used to build command line utilities. It will handle
   option and argument parsing according to your declarations. It also
   provides tools for usage statements.

SYNOPSIS
   your_prog.pl

       #!/usr/bin/perl
       use strict;
       use warnings;
       use Your::Prog;

       my @results = Your::Prog->new->handle_cli( @ARGV );

       print join "\n", @results;

   Your/Prog.pl

       package Your::Prog;
       use strict;
       use warnings;

       use Declare::CLI;

       opt 'enable-X' => (
           bool => 1,
           description => "Include X"
       );
       opt config => (
           default => "$ENV{HOME}/.config/your_prog.conf"
           validate => 'file',
           description => 'the config file'
       );
       opt types => (
           list => 1,
           default => sub { [ 'txt', 'rtf', 'doc' ] },
           description => "File types on which to act",
       );

       arg filter => sub {
           my $self = shift;
           my ( $cmd, $opts, @args ) = @_;
           my $types = { map { $_ => 1 } @{ $opts->{types}} };
           return grep {
               m/\.(.{3,4})$/;
               $1 && $types->{$1} ? 1 : 0;
           } @args;
       };

       # Descriptions are displayed in usage.
       describe_arg filter => "Filters args to only show those specified in types";

       arg sort => (
           description => "sort args",
           handler => sub {
               my $self = shift;
               my ( $cmd, $opts, @args ) = @_;
               return sort @args;
           },
       );

       arg help => sub {
           my $self = shift;
           my ( $cmd, $opts, @args ) = @_;

           return (
               "Usage: $0 [OPTS] [COMMAND] [FILES]\n",
               $self->usage
           );
       };

   Using it:

   Note: not all options are used here. Other options are for example only
   and not really useful.

       # Show all options and args
       $ your_prod.pl help

       # Find all txt, jpg, and gif files in the current dir
       $ your_prog.pl -types txt,jpg,gif filter ./*

       # Sort files in the current dir
       $ your_prog.pl sort ./*

       # Options and arguments can be short form as well, the shortest unambiguous
       # match will be used. For instance if you have options tyaaaa and tybbbbb
       # you could use -tya and -tyb to set them. just -ty is ambiguous and will
       # fail.
       $ your_prog.pl -t txt,jpg,gif filt ./*

EXPORTS
   $meta = CLI_META()
   $meta = $CLASS->CLI_META()
   $meta = $obj->CLI_META()
       Get the meta oject. Meta object will be returned in any usage,
       method on class, method on object, or function.

   arg 'NAME' => ( %PROPERTIES )
   $obj->arg( 'NAME' => %PROPERTIES )
       Can be used as function in class, or method on class/object.

       Declare a new argument. See the "ARGUMENT PROPERTIES" section for
       more details.

   opt 'NAME' => ( %PROPERTIES )
   $obj->opt( 'NAME' => %PROPERTIES )
       Can be used as function in class, or method on class/object.

       Declare a new option. See the "OPTION PROPERTIES" section for more
       details.

   describe_opt 'NAME' => "DESCRIPTION"
   $obj->describe_opt( 'NAME' => "DESCRIPTION" )
       Can be used as function in class, or method on class/object.

       Used to add a description to an option that is already defined.

   describe_arg 'NAME' => "DESCRIPTION
   $obj->describe_arg( 'NAME' => "DESCRIPTION" )
       Can be used as function in class, or method on class/object.

       Used to add a description to an argument that is already defined.

   $usage = usage()
   $usage = $obj->usage()
       Can be used as function in class, or method on class/object.

       Get a usage string listing all options and arguments.

   ( $opts, $args ) = preparse_cli( @cli )
       Pre-process the command line. No triggers or transforms are called.
       Only recognised options will be added to $opts. $args will contain
       everything else. The primary use of this method is if you have an
       option to specify a config file which may add additional options.
       This lets you get the config file, then use the real parse() method
       once everything is loaded from the config.

   ( $opts, $args ) = $obj->parse_cli( @cli )
       Must be used as an object method.

       Process the command line in @cli. Methods for options (default, etc)
       will be run against the $consumer object.

   $result = $obj->run_cli( $opts, $args )
       Must be used as an object method.

       Run the provided opts and args combination. Handler methods will be
       run on the $consumer object.

   $result = $obj->handle_cli( @ARGS )
       Must be used as an object method.

       Combines parse() and run(). Replacement for "process_cli".

   $result = $obj->process_cli( @ARGS )
       Note: Deprecated this functions interface was offensive. See
       handle_cli() instead.

       Must be used as an object method.

       Process some command line input. If an argument is provided as input
       the result of it will be returned. If no argument is specified, the
       options hash is returned.

OPTION PROPERTIES
   alias => "ALIAS_NAME"
   alias => [ "ALIAS_NAME", ... ]
       Set aliases for the option. Any alias can be used to set the option.
       Aliases can be used for partial matches (short form)

   list => $FLAG
       If true the option will hold a list of values. Values can be comma
       seperated, or you can provide the option multiple times and each
       value will be added to the others.

   bool => $FLAG
       If true the option can only have a true or false value, and will not
       accept an argument in the '-option value' form. You can specify a
       true or false value using the '-option=VAL' form. Normally however
       simply specifying the option '-option' will set it to true. If you
       provide a default value that is true, specifying the opton will
       negate that so that specifying the option on the command line turns
       it off.

   default => $VALUE
   default => sub { [ @VALUES ] }
       Specify the value that will be used by default when the option is
       not listed on the command line. The default sub is called as a
       function with no arguments.

   description => $STRING
       Provide a description for the option. This is used in the 'usage'
       output.

   trigger => sub { ... }
       This gets called when the option is set, even if it is set to the
       default value. The the sub is called as a method on your instance.
       The method receives 3 arguments, the name of the option, the value
       set, and the hashref of "{ option =" value } of all options
       processed so far. The return value is ignored.

           trigger => sub {
               my $self = shift;
               my ( $name, $value, $opts ) = @_;
               ...
           },

   transform => sub { ... }
       This is called whenever the value is set, before any triggers. This
       sub allows you to modify the value before it is assigned. For list
       params each value is passed to the transform sub seperately. This
       sub is called as a method on the instance. This method receives the
       value as its only argument.

   check => ...
       See "OPTION "check" PROPERTY"

 OPTION "check" PROPERTY
   The "check" option is used to validate inputs to options. You can
   provide a regex, a coderef, or a couple of premade options.

   check => qr/.../
       Validate the value(s) against a regex.

   check => sub { ... }
       Validate the value against the sub. The sub is called as a function,
       not a method. The function receives only one argument, the value to
       be checked. In list options each item is checked seperately.

   check => 'file'
       Validate that the value(s) are all valid files. (-f check)

   check => 'dir'
       Validate that the value(s) are all valid directories. (-f check)

   check => 'number'
       Validate that the value(s) are all numerical. (rejects values that
       contain a character matched by qr/\D/).

ARGUMENT PROPERTIES
   alias => "ALIAS_NAME"
   alias => [ "ALIAS_NAME", ... ]
       Set aliases for the argument. Any alias can be used to set the
       argument. Aliases can be used for partial matches (short form)

   description => "The Description"
       Provide a description for the argument. This is used in the 'usage'
       output.

   handler => sub { ... }
       This is the sub that gets called if the argument is provided on the
       command line. The sub is called as a method on your instance. This
       method is called with 2+ argument, the name of the arg, the { option
       => value } hash, and the rest of the arguments from the command line
       are the remaining arguments.

           handler => sub {
               my $self = shift;
               my ( $name, $options, @args ) = @_;
               ...
           },

META OBJECT METHODS
   You should rarely if ever need to access these directly.

   $meta = $meta_class->new( opts => {...}, args => {...} )
       Create a new meta object.

   $class = $meta->class
       Get the class for which the meta object was constructed.

   $args = $meta->args
       Get the hashref of { arg => \%config }

   $opts = $meta->opts
       Get the hashref of { opt => \%config }

   $regex = $meta->valid_arg_params
       Get a regex that can be used to validate the options available for
       args.

   $regex = $meta->valid_opt_params
       Get a regex that can be used to validate the options available for
       opts.

   $usage = $meta->usage
       Get the usage information.

   ( $opts, $args ) = $meta->preparse( @cli )
       Pre-process the command line. No triggers or transforms are called.
       Only recognised options will be added to $opts. $args will contain
       everything else. The primary use of this method is if you have an
       option to specify a config file which may add additional options.
       This lets you get the config file, then use the real parse() method
       once everything is loaded from the config.

   ( $opts, $args ) = $meta->parse( $INSTANCE, @cli )
       Process the command line in @cli. Methods for options (default, etc)
       will be run against the $INSTANCE object.

   $result = $meta->run( $INSTANCE, $opts, $args )
       Run the provided opts and args combination. Handler methods will be
       run on the $INSTANCE object.

   $result = $meta->handle( $INSTANCE, @cli )
       Combines parse() and run(). Replacement for "process_cli".

   $result = $meta->process( $INSTANCE, @ARGS )
   $result = $meta->process_cli( $INSTANCE, @ARGS )
       Note: Deprecated This interface was offensive. See handle() instead.

       Process the command line arguments on $INSTANCE.

   $meta->describe( $TYPE, $NAME, $DESCRIPTION )
       Add a description to an argument or option.

   $meta->add_arg( $NAME => %PROPERTIES )
       Add an argument.

   $meta->add_opt( $NAME => %PROPERTIES )
       Add an option.

AUTHORS
   Chad Granum [email protected]

COPYRIGHT
   Copyright (C) 2012 Chad Granum

   Declare-Opts is free software; Standard perl licence.

   Declare-Opts is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for
   more details.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.