NAME

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

VERSION

This documentation refers to Getopt::Alt version 0.3.1.

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

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

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

Object Methods

BUILD ()

internal method

process ()

list_options ()

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

best_option ()

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.

cpanm Getopt::Alt

perl -MCPAN -e shell
install Getopt::Alt