Ryan P. Kelly > Getopt-Flex-0.11 > Getopt::Flex

Download:
Getopt-Flex-0.11.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 0.11   Source   Latest Release: Getopt-Flex-1.07

NAME ^

Getopt::Flex

VERSION ^

version 0.11

SYNOPSIS ^

  use Getopt::Flex;
  my $foo; my $use; my $num; my %has; my @arr;
  
  my $cfg = {
      'non_option_mode' => 'STOP',
  };
  
  my $spec = {
      'foo|f' => {'var' => \$foo, 'type' => 'Str'},
      'use|u' => {'var' => \$use, 'type' => 'Bool'},
      'num|n' => {'var' => \$num, 'type' => 'Num'},
      'has|h' => {'var' => \%has, 'type' => 'HashRef[Int]'},
      'arr|a' => {'var' => \@arr, 'type' => 'ArrayRef[Str]'}
  };
  
  my $op = Getopt::Flex->new({spec => $spec, config => $cfg});
  $op->getopts();

DESCRIPTION ^

Getopt::Flex is an object-oriented way to go about option parsing. Creating an option specification is easy and declarative, and configuration is optional and defualts to a few, smart parameters. Generally, it adheres to the POSIX syntax with GNU extensions for command line options. As a result, options may be longer than a single letter, and would begin with "--". Support also exists for bundling of command line options, but is not enabled by defualt.

NAME ^

Getopt::Flex - Option parsing, done differently

Getting started with Getopt::Flex ^

Getopt::Flex supports long and single character options. Any character from [a-zA-Z0-9_?-] may be used when specifying an option. Options must not end in -, nor may they contain two consecutive dashes.

To use Getopt::Flex in your perl program, it must contain the following line:

  use Getopt::Flex;

In the default configuration, bundling is not enabled, long options must start with "--" and non-options may be placed between options.

Specifying Options

Options are specified by way of a hash whose keys define valid option forms and whose values are hashes which contain information about the options. For instance,

  my $spec = {
      'file|f' => {
          'var' => \$file,
          'type' => 'Str'
      }
  };

Defines a switch called file with an alias f which will set variable $var with a value when encountered during processing. type specifies the type that the input must conform to. Both var and type are required when specifying an option. In general, options must conform to the following:

  $_ =~ m/^[a-zA-Z0-9|_?-]+$/ && $_ !~ m/\|\|/ && $_ !~ /--/ && $_ !~ /-$/

The following is an example of all possible arguments to an option specification:

  my $spec = {
      'file|f' => {
          'var' => \$file,
          'type' => 'Str',
          'desc' => 'The file to process',
          'required' => 1,
          'validator' => sub { $_[0] =~ /\.txt$/ },
          'callback' => sub { print "File found\n" },
          'default' => 'input.txt',
      }
  };

Specifying a var

When specifying a var, you must provide a reference to the variable, and not the variable itself. So \$file is ok, while $file is not. You may also pass in an array reference or a hash reference, please see "Specifying a type" for more information.

Specifying a type

A valid type is one of the following:

  Bool Str Num Int ArrayRef[Str] ArrayRef[Num] ArrayRef[Int] HashRef[Str] HashRef[Num] HashRef[Int] Inc

These work like exactly like Moose type constraints of the same name, except Inc. Inc defines an incremental type (actually simply an alias for Moose's Int type), whose value will be increased by one each time its appropriate switch is encountered on the command line. When using an ArrayRef type, the supplied var must be an array reference, like \@arr and NOT @arr. Likewise, when using a HashRef type, the supplied var must be a hash reference, e.g. \%hash and NOT %hash. For more information about types, see Moose::Manual::Types.

All of the following arguments to the option specification are optional.

Specifying a desc

desc is used to provide a description for an option. It can be used to provide an autogenerated help message for that switch. If left empty, no information about that switch will be displayed in the specification. See "Using Getopt::Flex" for more information.

Specifying required

Setting required to a true value will cause it make that value required during option processing, and if it is not found will cause an error condition.

Specifying a validator

A validator is a function that takes a single argument and returns a boolean value. Getopt::Flex will call the validator function when the option is encountered on the command line and pass to it the value it finds. If the value does not pass the supplied validation check, an error condition is caused.

Specifying a callback

A callback is a function that takes a single argument which Getopt::Flex will then call when the option is encountered on the command line, passing to it the value it finds.

Specifying a default

defaults come in two flavors, raw values and subroutine references. For instance, one may specify a string as a default value, or a subroutine which returns a string:

  'default' => 'some string'

or

  'default' => sub { return "\n" }

When specifying a default for an array or hash, it is necessary to use a subroutine to return the reference like,

  'default' => sub { {} }

or

  'default' => sub { [] }

This is due to the way Perl handles such syntax. Additionally, defaults must be valid in relation to the specified type and any specified validator function. If not, an error condition is signalled.

Configuring Getopt::Flex ^

Configuration of Getopt::Flex is very simple. Such a configuration is specified by a hash whose keys are the names of configuration option, and whose values indicate the configuration. Below is a configuration with all possible options:

  my $cfg = {
      'non_option_mode' => 'STOP',
      'bundling' => 0,
      'long_option_mode' => 'SINGLE_OR_DOUBLE',
      'usage' => 'foo [OPTIONS...] [FILES...]',
      'desc' => 'Use foo to manage your foo archives'
  };

What follows is a discussion of each option.

Configuring non_option_mode

non_option_mode tells the parser what to do when it encounters anything which is not a valid option to the program. Possible values are as follows:

  STOP IGNORE

STOP indicates that upon encountering something that isn't an option, stop processing immediately. IGNORE is the opposite, ignoring everything that isn't an option. The default value is IGNORE.

Configuring bundling

bundling is a boolean indicating whether or not bundled switches may be used. A bundled switch is something of the form:

  -laR

Where equivalent unbundled representation is:

  -l -a -R

By turning bundling on, long_option_mode will automatically be set to REQUIRE_DOUBLE_DASH.

Configuring long_option_mode

This indicates what long options should look like. It may assume the following values:

  REQUIRE_DOUBLE_DASH SINGLE_OR_DOUBLE

REQUIRE_DOUBLE_DASH is the default. Therefore, by default, options that look like:

  --verbose

Will be treated as valid, and:

  -verbose

Will be treated as invalid. Setting long_option_mode to SINGLE_OR_DOUBLE would make the second example valid as well. Attempting to set bundling to 1 and long_option_mode to SINGLE_OR_DOUBLE will signal an error.

Configuring usage

usage may be set with a string indicating appropriate usage of the program. It will be used to provide help automatically.

Configuring desc

desc may be set with a string describing the program. It will be used when providing help automatically.

Using Getopt::Flex ^

Using Getopt::Flex is simple. You define a specification, as described above, optionally define a configuration, as desribed above, and then construct a new Getopt::Flex object.

  my $spec = {
      'foo|f' => {'var' => \$foo, 'type' => 'Str'},
  };
  
  my $op = Getopt::Flex->new({spec => $spec});

You then call $op-getopts()> to process options. Getopt::Flex automatically uses the global @ARGV array for options. If you would like to supply your own, you may use set_args, like this:

  $op->set_args(\@args);

Which expects an array reference. Getopt::Flex also stores information about valid options, invalid options and extra options. Valid options are those which Getopt::Flex recognized as valid, and invalid are those that were not. Anything that is not an option can be found in extra options. These values can be retrieved via:

  my @va = $op->get_valid_args();
  my @ia = $op->get_invalid_args();
  my @ea = $op->get_extra_args();

Getopt::Flex may also be used to provide an automatically formatted help message. By setting the appropriate desc when specifying an option, and by setting usage and desc in the configuration, a full help message can be provided, and is available via:

  my $help = $op->get_help();

Usage and description are also available, via:

  my $usage = $op->get_usage();
  my $desc = $op->get_desc();

An automatically generated help message would look like this:

  Usage: foo [OPTIONS...] [FILES...]
  
  Use this to manage your foo files
  
  Options:
  
        --alpha, --beta,          Pass any greek letters to this argument
        --delta, --eta, --gamma
    -b, --bar                     When set, indicates to use bar
    -f, --foo                     Expects a string naming the foo

METHODS ^

getopts

Invoking this method will cause the module to parse its current arguments array, and apply any values found to the appropriate matched references provided.

set_args

Set the array of args to be parsed. Expects an array reference.

get_args

Get the array of args to be parsed.

num_valid_args

After parsing, this returns the number of valid switches passed to the script.

get_valid_args

After parsing, this returns the valid arguments passed to the script.

num_invalid_args

After parsing, this returns the number of invalid switches passed to the script.

get_invalid_args

After parsing, this returns the invalid arguments passed to the script.

num_extra_args

After parsing, this returns anything that wasn't matched to a switch, or that was not a switch at all.

get_extra_args

After parsing, this returns the extra parameter passed to the script.

get_usage

Returns the supplied usage message, or a single newline if none given.

get_help

Returns an automatically generated help message

get_desc

Returns the supplied description, or a single newline if none provided.

AUTHOR ^

  Ryan P. Kelly <rpkelly22@gmail.com>

COPYRIGHT AND LICENSE ^

This software is Copyright (c) 2009 by Ryan P. Kelly.

This is free software, licensed under:

  The MIT (X11) License
syntax highlighting: