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

NAME

Getopt::Alt - Command line option passing with with lots of features

VERSION

This documentation refers to Getopt::Alt version 0.5.5.

SYNOPSIS

use Getopt::Alt;

# OO Style usage
# 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!',
    'fixed_values|fixed-values|f=[a|bunch|of|fixed|values]',
);
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!',
    'fixed_values|fixed-values|f=[a|bunch|of|fixed|values]',
);

# 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!',
        'fixed_values|fixed-values|f=[a|bunch|of|fixed|values]',
    ],
);
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!',
        'fixed_values|fixed-values|f=[a|bunch|of|fixed|values]',
    ],
);
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. Getopt::Lon can be expanded from a simple command line option passer to allow sub-commands. Option processing may stop at the sub-command or with the help of modules can cascade the processing into the sub command's module or config.

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 (Default true)

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

ignore_case - bool (Default true)

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 options list. (i.e. you get --help --man and --version arguments for you program.)

help_package - Str

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

name - Str (Default $0's basename)

Used when displaying --version info

options - Str (Default Getopt::Alt::Dynamic)

The parent class for generating options.

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.

config

Stores the data in the configuration files

conf_prefix - Str (Default ".")

The prefix for finding the configuration files. By default the following is used:

  • ./$conf_prefix$name

  • ~/$conf_prefix$name

  • /etc/$conf_prefix$name

conf_section

Used if the using program wants the ability to set up configuration groups so that the user can have a bunch of default values. This attribute sets the name in the configuration where configuration groups can be found. There should also be a matching argument so that the user can choose the appropriate configuration.

Object Methods

BUILD ()

internal method

process ()

list_options ()

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

best_option ()

Decides on the best matching option.

complete ()

Command line auto complete helper

Auto Complete

For your program (say eg) you can add the following to your ~/.bashrc file to get auto-completion.

_eg() {
    COMPREPLY=($(vtide --auto-complete ${COMP_CWORD} -- ${COMP_WORDS[@]}))
}
complete -F _eg eg

Note: This is different from version 0.5.5 and earlier

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.