command-line option parsing and usage

NAME

Options - Yet another Perl module to provide support for command-line option parsing and usage generation.

SYNOPSIS

    use Options;
    
    $options = new Options(params => [
                                ['port',   'p', undef,       'The port to connect to.'],
                                ['host',   'h', 'localhost', 'The host to connect to.']
                           ],
                           flags =>  [
                                ['secure', 's', 'Use SSL for encryption.'],
                                ['quit',   'q', 'Quit after connecting.'],
                                ['help',   'h', 'Display this usage guide.'],
                           ]);
    
    # Parse the default option source (@ARGV)
    %results = $options->get_options();
    
    # Provide usage
    if($options->get_result('help')){
        $options->print_usage();
        exit(1);
    }

CONTENTS

 Options 1.5.2

DESCRIPTION

Options was created to somewhat emulate the syntax of the Twisted Python's usage library. It provides a parser for command-line options that is integrated with an automatic usage generator. Support exists for both flags and parameters, in long and short form, required parameters, and default params.

GETTING OPTIONS

• new Options()

  Create a new instance of the Options class. To do so, pass the constructor two optional, named arguments. 'params' are command-line switches with arguments, while flags are boolean switches. (duh.)

  Each argument consists of an anonymous array reference which contains an anonymous array for each option you wish to support.

  Params arrays must be four elements long, consisting of the long and short versions of the switch, a default value, and a description to be printed in the usage guide. If the default value is specified as "undef", it becomes a required value, and the program will not continue without it. Options without defaults can specify the empty string ("") to omit the default.

  Flags arrays are simpler, and omit the default element.

• $options->get_options()

  This method is called with no arguments, and begins the parsing of the global variable @ARGV, or an array passed as the first argument to the function. When finished, it returns a hash where the keys are the long option names, and the values are the result of the parse, i.e., strings for params, and boolean values (1 or 0 actually) for flag-type options.

  If the parser encounters an unknown flag, or a bare word without a recognized switch before it, these are left in the $options->{'unrecognized'} array in the order they are found.

  If no array was passed in (i.e., @ARGV was parsed), the unrecognized items are left in @ARGV so that a script can do additional processing.

  If the result is missing a required parameter, the module prints the usage table, and calls exit(1).

• $options->get_result(option)

  Although get_options() returns a hash, and that is an acceptable way to use the results, this function provides some level of convenience when dealing with options that may return a reference to a list of results for that option. When called in a list context, this will return a list of results, even if only one argument was provided. However, calling it in a scalar context when there are multiple arguments will be, shall we say, disappointing.

• $options->print_usage($optional_message)

  Options will automatically display usage information if a required parameter is omitted, but this method can be used to implement a --help parameter.

ADVANCED USAGE

Options.pm has a couple of hidden hooks that you may find useful when using the module in different ways.

The first allows you to control the default behavior when an error occurs:

    $options->{'exit'} = 0;

When this flag has been set to 0, get_options() will no longer call exit(1) after printing the usage when an error occurs. Instead it will simply call die($reason), which you can trap in an eval block.

The second (and more interesting) hook also allows you to specify a subroutine reference to execute when an error occurs in get_options(). For example, the following code will replicate the default behavior of get_options():

    $options->{'error_handler'} = sub {
        # the Options instance
        $self = shift;
        
        # what caused the error
        $error_msg = shift;
        
        # Do whatever you need to do here, possibly
        # including calling print_usage()
        
        # Returning true would ignore all errors, and attempt
        # to parse as much as possible, whereas false will
        # exit immediately with an error code of 1
        return 0;
    };

Finally, if you want to do something else with the output of print_usage(), you can have it sent to any filehandle object you have kicking around.

For example, if you're on Perl 5.8.6, you can use the StringIO services to retrieve a string version of the usage text:

        open(STRINGIO, '+>', \$usage_text) or die $!;
        $options->{'usage_fh'} = \*STRINGIO;
        ...
        ...
        ...
        $options->get_options();
        @usage_lines = <$options->{'usage_fh'}>;
        
        # don't forget to close the handle
        close($options->{'usage_fh'});

AUTHOR

Phil Christensen,

COPYRIGHT AND LICENSE

Copyright (C) 2005-2007 by Phil Christensen

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.