/ 
Getopt-Alt-v0.2.5
River stage two • 11 direct dependents • 16 total dependents
/ Getopt::Alt

NAME

Getopt::Alt - Alternate method of processing command line arguments

VERSION

This documentation refers to Getopt::Alt version 0.2.5.

SYNOPSIS

use Getopt::Alt;

# Create a new options object
my $opt = Getopt::Alt->new(
    {
        default => { string => 'default' },
    },
    [
        'string|s=s',
        ...
    ],
);
print "String = " . $opt->opt->{string} . "\n";

# Getopt::Long like usage
use Getopt::Alt qw/get_options/;

# most basic form
my $options = get_options(
    'string|s=s',
    'int|i=i',
    'hash|h=s%',
    'array|a=s@',
    'increment|c+',
    'nullable|n=s?',
    'negatable|b!',
);
print Dumper $options->opt;           # passed parameters
print join ',', @{ $options->files }; # non option parameters

# with defaults
my $options = get_options(
    { negatable => 1 },
    'string|s=s',
    'int|i=i',
    'hash|h=s%',
    'array|a=s@',
    'increment|c+',
    'nullable|n=s?',
    'negatable|b!',
);

# with configuration
my $options = get_options(
    {
        helper => 1, # default when using get_options
        sub_command => 1, # stop processing at first non argument parameter
    },
    [
        'string|s=s',
        'int|i=i',
        'hash|h=s%',
        'array|a=s@',
        'increment|c+',
        'nullable|n=s?',
        'negatable|b!',
    ],
);
print $cmd;   # sub command

# with sub command details
my $options = get_options(
    {
        helper => 1, # default when using get_options
        sub_command => {
            sub   => [ 'suboption' ],
            other => [ 'verbose|v' ],
        },
    },
    [
        'string|s=s',
        'int|i=i',
        'hash|h=s%',
        'array|a=s@',
        'increment|c+',
        'nullable|n=s?',
        'negatable|b!',
    ],
);
print Dumper $option->opt;  # command with sub command options merged in

# auto_complete
my $options = get_options(
    {
        helper        => 1, # default when using get_options
        auto_complete => sub {
            my ($opt, $auto) = @_;
            # ... code for auto completeion
            # called if --auto-complete specified on the command line
        },
    },
    [
        'string|s=s',
        'int|i=i',
    ],
);

DESCRIPTION

The aim of Getopt::Alt is to provide an alternative to Getopt::Long that allows a simple command line program to easily grow in complexity. It or to a package with multiple commands. The simple usage is quite similar to Getopt::Long:

In Getopt::Long you might get your options like:

use Getopt::Long;
my %options = ( string => 'default' );
GetOptions(
    \%options,
    'string|s=s',
    ...
);

The found options are now stored in the %options hash.

In Getopt::Alt you might do the following:

use Getopt::Alt qw/get_options/;
my %default = ( string => 'default' );
my $opt = get_options(
    \%default,
    'string|s=s',
    ...
);
my %options = %{ $opt->opt };

This will also result in the options stored in the %options hash.

Some other differences between Getopt::Alt and Getopt::Long include:

  • Bundling - is on by default

  • Case sensitivity is on by default

  • Throws error rather than returning errors.

  • Can work with sub commands

SUBROUTINES/METHODS

Exported

get_options (@options | $setup, $options)

get_options ($default, 'opt1', 'opt2' ... )

This is the equivalent of calling new(...)->process but it does some extra argument processing.

Note: The second form is the same basically the same as Getopt::Long's GetOptions called with a hash ref as the first parameter.

Class Methods

new ( \%config, \@optspec )

config

default - HashRef

Sets the default values for all the options. The values in opt will be reset with the values in here each time process is called

files - ArrayRef[Str]

Any arguments that not consumed as part of options (usually files), if no arguments were passed to process then this value would also be put back into @ARGV.

bundle - bool

Turns on bundling of arguments eg -rv is equivalent to -r -v. This is on by default.

ignore_case - bool

Turns ignoring of the case of arguments, off by default.

helper - bool

If set to a true value this will cause the help, man, and VERSION options to be added the end of your

help_package -

The Perl package with the POD documentation for --help and --man, by default it's the callers package.

cmds - ArrayRef[Getopt::Alt::Command]

If the Getopt::Alt is being used as part of a package where individual commands have their own modules this parameter stores an instance of each commands. (Not yet fully implemented.

options - ArrayRef[Getopt::Alt::Option]

The individual command option specifications processed.

opt - HashRef

The values processed from the $ARGV or arguments passed to the process method..

default - HashRef

The default values for each option. The default value is not modified by processing, so if set the same default will be used from call to call.

aliases - HashRef[ArrayRef[Str]]

When using sub-commands this allows you to configure aliases for those commands, aliases are recursed, they can have extra arguments though. If a configuration file is used aliases can be specified in that file.

Return: Getopt::Alt -

Description:

Object Methods

BUILD ()

internal method

process ()

list_options ()

Returns a list of all command line options in the current object.

best_option ()

get_files ()

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

Configuration files can be used to specify default values and aliases. They can be located in the current directory, $HOME or /etc.The file name is specified by the name attribute (which defaults to the program's name) and is prepended with a dot. eg:

For a program called as $ ./foo or $ foo name would be set to foo and possible configuration names would be

  • .foo.yml

  • ~/.foo.rc

  • /etc/.foo.yml

See Config::Any for information about config formats and file extensions.

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

There are no known bugs in this module.

Please report problems to Ivan Wills (ivan.wills@gmail.com).

Patches are welcome.

AUTHOR

Ivan Wills - (ivan.wills@gmail.com)

LICENSE AND COPYRIGHT

Copyright (c) 2009 Ivan Wills (14 Mullion Close, Hornsby Heights, NSW Australia 2077). All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. This program 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.