NAME

Declare::Opts - (Deprecated) Simple and Sane Command Line Argument processing

DESCRIPTION

Deprecated: see Declare::CLI

Declare-Opts is a sane and declarative way to define and consume command line options. Any number of dashes can be used, it is not picky about -opt or --opt. You can use '-opt value' or '-opt=value', it will just work. Shortest unambiguous substring of any opt name can be used to specify the option.

WHY NOT GETOPT?

The Getopt ecosystem is bloated. Type getopt into search.cpan.org and you will be given pages and pages of results. Normally this would be a good thing, the issue is that each package provides specialised functionality, and most cannot operate together.

The Getopt ecosystem is also very crufty. Getopt is an old module that uses many outdated practices, and an even more outdated interface. Unfortunately this has been carried forward into the new getopt modules, possibly for compatability/familiarity reasons.

Declare::Opts is a full on break from the Getopt ecosystem. Designed from scratch using modern practices and interface design.

SYNOPSIS

DECLARATIVE

Code:

    #!/usr/bin/env perl
    use Declare::Opts;

    # Define a simple opt, any value works:
    opt 'simple';

    # Define a boolean opt
    opt with_x => ( bool => 1 );

    # Define a list
    opt items => ( list => 1 );

    # Other Options
    opt complex => (
        alias       => $name_or_array_of_names,
        default     => $val_or_sub,
        check       => $bultin_regex_or_sub,
        transform   => sub { my $opt = shift; ...; return $opt },
        description => "This is a complex option",
    );

    # Get the (opts => descriptions) hash, useful for a help() function
    my $info = opt_info();

    #########################
    # Now process some opts #
    #########################

    my ( $args, $opts ) = parse_opts( @ARGV );

    # $args contains the items from @ARGV that are not specified opts (or their
    # values)
    # $opts is a hashref containing the opts and their values.

Command Line:

    ./my_command.pl -simple simple_value -with_x --items "a,b, c"

The shortest unambiguous string can be used for each parameter. For instance we only have one option defined above that starts with 's', that is 'simple':

    ./my_command.pl -s simple_value

OBJECT ORIENTED

    require Declare::Opts;

    # Create
    my $opts = Declare::Opts->new( %opts );

    # Add an opt
    $opts->opt( $name, %config );

    # Get info
    my $info = $opts->info;

    # Parse some opts
    my ( $args_array, $opts_hash ) = $opts->parse( @ARGV );

META OBJECT

When you import Declare::Opts a meta-object is created in your package. The meta object can be accessed via the OPTS_META() method/function. This object is an instance of Declare::Opts and can be manipulated just like any Declare::Opts object.

EXPORTS

opt( $name, %config );

opt name => ( %config );

Define an option

my $info = opt_info();

Get a ( name => description ) hashref for use in help output.

my ( $args, $opts ) = parse_opts( @OPTS );

Parse some options. $list contains the options leftovers (those that do not start with '-'), $opts is a hashref containing the values of all the dashed opts.

METHODS

$class->new( %opts );

Create a new instance.

my $class = $opts->class;

If the object was created as a meta-object this will contain the class to which it applies. When created directly this will always be empty.

$opts->opt( $name, %config );

Define an option

my $info = $opts->info();

Get a ( name => description ) hashref for use in help output.

my ( $args_array, $opts_hash ) = $opts->parse( @OPTS );

Parse some options. $list contains the options leftovers (those that do not start with '-'), $opts is a hashref containing the values of all the dashed opts.

OPTION PROPERTIES

alias => $name

alias => [ $name1, $name2 ]

Set aliases for the option.

list => $true_or_false

If true, the option can be provided on the command line any number of times, and comma seperated lists will be split for you.

bool => $true_or_false

If true, the option does not require a value and turns the option on or off. A value can be specified using the '--opt=VAL' format. However '--opt val' will not treat 'val' as the option value.

default => $scalar

default => sub { ... }

Set the default value. If the opt is not specified on the command line this value will be used. If the value is not a simple scalar it must be wrapped in a code block.

check => 'builtin'

check => qr/.../

check => sub { my $val = shift; ...; return $bool }

Used to validate option values. Can be a coderef, a regexp, or one of these bultins:

    'number'    The value(s) must be numeric (only contains digit characters)
    'file'      The value(s) must be a file (uses -f check)
    'dir'       The value(s) must be a directory (-d check)

transform => sub { my $orig = shift; ...; return $new }

Function to transform the provided value into something else. Applies to eahc item of a list when list is true.

description => $description_string

Used to describe an option, useful for help() output.

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.

cpanm Declare::CLI

perl -MCPAN -e shell
install Declare::CLI