/ 
Declare-CLI-0.009
River stage one • 1 direct dependent • 1 total dependent
/ Declare::CLI

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 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.