View on
Phil Christensen > Options-1.5.2 > Options



Annotate this POD


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


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


    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


 Options 1.5.2


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.


ADVANCED USAGE ^ 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;
        @usage_lines = <$options->{'usage_fh'}>;
        # don't forget to close the handle


Phil Christensen, <>


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: