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 ( $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 => (
describe => "sort args",
handler => sub {
my $self = shift;
my ( $opts, $args ) = @_;
return sort @$args;
};
};
arg help => sub {
my $self = shift;
my ( $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 exodist7@gmail.com
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.