View on
MetaCPAN
Phil Christensen > Options-1.5.2 > Options

Download:
Options-1.5.2.tgz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 1.5.2   Source  

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 ^

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, <phil@bubblehouse.org>

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.

syntax highlighting: