Enrique Castilla Contreras > Getopt-Yagow-1.01 > Getopt::Yagow

Download:
Getopt-Yagow-1.01.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 1.01   Source  

NAME ^

Getopt::Yagow - Yet another Getopt::Long (and Pod::Usage) wrapper.

SYNOPSIS ^

    my $opt = Getopt::Yagow->new;
    $opt->load_options(
           'config=s' => '',
           'srcdir:s' => '',
           'tardir:s' => '',
           # 'help' => '',             # Added by default.
           'css:s' => 'style.css',
           'file_icon|f_icon:s' => 'c:\Perl\site\lib\tk\file.xbm',
           'dir_icon|d_icon:s' => 'c:\Perl\site\lib\tk\folder.xbm'
    );
    $o->parse_cmd_line;    

    # or

    my $opt = Getopt::Yagow->new(
           'config=s' => '',
           'srcdir:s' => '',
           'tardir:s' => '',
           # 'help' => '',             # Added by default.
           'css:s' => 'style.css',
           'file_icon|f_icon:s' => 'c:\Perl\site\lib\tk\file.xbm',
           'dir_icon|d_icon:s' => 'c:\Perl\site\lib\tk\folder.xbm'
    );
    $opt->parse_cmd_line( '--config configuration.file', '--css active.css', ...);
    my $opt_values = $opt->get_options_values;

    # or more compact

    my $opt = Getopt::Yagow->new( ... )->parse_cmd_line( ... );
    my $opt_values = $opt->get_options_values;

DESCRIPTION ^

Class wrapper of Getopt::Long and Pod::Usage for parsing and management of command line options.

FUNCTIONS. ^

$opt = Getopt::Yagow->new( [argument_list] )

Creates a new object and returns a hash ref. Supports same argument list as load_options, because it is an abbrev of:

    my $this = bless {}, $class;
    $this->load_options( @_ );
    return $this;

So, see load_options for arguments.

$opt = $opt->load_options( argument_list )

Sets specification of command line arguments (passed as arguments) and prepares for parsing.

Returns object itself.

argument_list may be:

load_options creates some hash members in %$opt:

For example:

     $opt->load_options ( {
               'file1|f1=s' => undef,
               'file2=s' => '',
               'file3=s' => 'three'
                          } );

Creates three members in %$opt:

    $opt->{options} == {
                           'file1|f1=s' => undef,
                           'file2=s' => '',
                           'file3=s' => 'three'                       
                       }

    $opt->{mandatory} == ['file1']

    $opt->{default} == {
                           'file2' => '',
                           'file3' => 'three'                       
                       }

There is not a $opt-{configuration}> entry because there are not configuration options specified in function call. So, don`t expect to see all mentioned entries. Only options is always present.

Mandatory options may have any option specification, not only = (but also :, !, +).

$opt = $opt->parse_cmd_line( argument_list )

Parses command line arguments or arguments specified in argument_list, and returns object itself.

In case arguments to be parsed be specified in argument list, use same syntax that were used in command line, but with each argument and associated value(s) in between quotes. Sample:

    $opt->parse_cmd_line( '--f1=one_file.txt', '--file2=C:\icon.jpg' );

Argument list may contain one or two hash references, one for help documentation and one for usage doc in case of wrong syntax, in this order. Both docs are displayed via Pod::Usage::pod2usage. The function acts as pass through with these last two arguments, so see doc of Pod::Usage for valid options. In case these hash refs exists, they must be last arguments in list.

Sample:

    $opt->parse_cmd_line( '--f1=one_file.txt', '--file2=C:\icon.jpg', 
                          '--unknown=any_string',
                          {-msg => $copyrigth, -verbose => 2},         # help.
                          {-msg => $wrong_syntax, -verbose => 0}   );  # wrong syntax.

This functions adds one or two entries to %$opt:

As a summary, all these keys may be created in %$opt:

    configuration
    options
    default
    mandatory
    used
    unhandled_options

$arrayref = $opt->get_configuration()

Returns $opt->{configuration} .

$hashref = $opt->get_options()>

Returns $opt->{options}> .

$hashref = $opt->get_default()

Returns $opt->{default}.

$arrayref = $opt->get_mandatory()

Returns $opt->{mandatory}.

$hashref = $opt->get_used()

Returns $opt->{used}.

$arrayref = $opt->get_unhandled()

Returns $opt->{unhandled_options}.

$hashref = $opt->get_options_values()

Returns a hash reference that is the union of two hashes: key-value pairs of $opt->{used} and key-value pairs of $opt->{default}.

SAMPLES ^

    my $opt = Getopt::Yagow->new;

    $opt->load_options( 
           {
               'config_file=s' => '',
               'css:s' => 'C:\Perl\html\active.css',
               'dir_icon|d_icon|di:s'  => 'c:\Perl\site\lib\tk\file.xbm',
               'file_icon|f_icon|fi:s' => 'c:\Perl\site\lib\tk\file.xbm'
           },
           ['pass_through']
    );

    $opt->parse_cmd_line split(/\s+/,'--config_file=pepe.conf --di=pepe.jpg'),  
                          {-msg => $copyright, -verbose => 2},     # help.
                          {-msg => $wrong_syntax, -verbose => 0};  # wrong syntax.

    foreach ( keys $opt->{options} )
    {
        if( exists $opt->{used}->{$_} or exists $opt->{default}->{$_})
        {
            # Argument $_ has been specified in command line or
            # is a default.

            ... (do this)
        }
        else
        {
            # Argument not used.

            ... (do that)
        }
    }

Or more compact:

    $opt = Getopt::Yagow->new(
           {
               'config_file=s' => '',
               'css:s' => 'C:\Perl\html\active.css',
               'dir_icon|d_icon|di:s'  => 'c:\Perl\site\lib\tk\folder.xbm',
               'file_icon|f_icon|fi:s' => 'c:\Perl\site\lib\tk\file.xbm'
           },
           ['pass_through']

    )->parse_cmd_line(

           split(/\s+/,'--config_file=pepe.conf --di=pepe.jpg'),  
           {-msg => $copyrigth, -verbose => 2},      # help.
           {-msg => $wrong_syntax, -verbose => 0}    # wrong syntax.       
    );

For copy, paste and experiment:

    #!/usr/local/perl -w

    # >perl samp1.pl --opt1 string [--option2 string]

    use Getopt::Yagow;

    $opt = Getopt::Yagow->new(
        'option1|opt1|o1=s' => undef, 'option2=s' => 'two'
    );

    $opt->parse_cmd_line({-verbose=>0},{-verbose=>0});

    # Si la ejecucion llega hasta aqui.
    print "There is no error in command line nor --help were used\n";

    $opt->DEBUG;

    print "get_options_values:\n";
    my $values = $opt->get_options_values();
    while( my($key,$val) = each %{ $values } )
    {
        print "$key => $val\n";
    }

    __END__

    =head1 NAME

    samp1.pl - Test for options with syntax 'option=s'.

    =head1 SYNOPSIS

        > perl samp1.pl --{option1|opt1|o1} any_string [--option2 another_string]

    =head1 OPTIONS AND ARGUMENTS

    =over 4

    =item {--option1|--opt1|--o1} string

    =item --option2 string

    =back

Also for copy, paste and experiment:

    samp2.pl
    ========

    #!/usr/local/perl -w

    # >perl samp2.pl 0|1|2 --help

    use Getopt::Yagow;

    die if $ARGV[0] != 0 && $ARGV[0] != 1 && $ARGV[0] != 2;

    my $opt = Getopt::Yagow->new->parse_cmd_line({-verbose=>$ARGV[0]},{-verbose=>$ARGV[0]});

    __END__

    =head1 NAME

    samp2.pl - Sample script for Getopt::Yagow module.

    =head1 SYNOPSIS

        % perl samp2.pl {0|1|2} --help

    =head1 DESCRIPTION

    Sample file for Getopt::Yagow module.

    =head1 OPTIONS AND ARGUMENTS

    =over 4

    =item 0 or 1 or 2

    Level of detail displaying help info.

    =item --help

    Display help info.

    =back

HINTS ^

Difference between 'option' and 'option!' specification.

Both specifications allows --option to take no argument, and if used in command line, corresponding hash value is assigned a boolean value: true if used incommand line and false otherwise.

Also, second specification allows the form --nooption as a sinonym of 'not specified in command line'.

For example:

     $opt->load_options ( {
               'file1'  => 1,
               'file2!' => 1
                          } );

With this option specifications, a command line with no arguments leaves 0 in both hash values, but second allows also the syntax --nofile2 to do the same, while first doesn't allow.

Options names and values separators.

There is a slithly difference when command line options are pased with @ARGV and when passed with arguments of parse_cmd_line.

With @ARGV each blank in command line acts as a separator of two distinct members of @ARGV. For example:

    > perl util.pl --arg1 value1 --arg2 value2

Makes 4 elements in @ARGV: one for '--arg1', one for 'value1', one for '--arg2' and one for 'value2'. Then, Getopt::Long do the rest.

From the point of view of Getopt::Long, same efect is achieved using POSIX separators:

    > perl util.pl --arg1=value1 --arg2=value2

With arguments in parse_cmd_line, same is not true:

    $opt->parse_cmd_line('--arg1 value1 --arg2 value2');

Interprets all the string as an unique option, as if only $ARGV[0] were asigned. So, the command line syntax is incorrect becasuse --arg1 expects only one string and not three. To achieve same effect, must be written as:

    $opt->parse_cmd_line('--arg1', 'value1', '--arg2', 'value2');

    or equivalently

    $opt->parse_cmd_line( @ARGV );

Or with POSIX separator:

    $opt->parse_cmd_line('--arg1=value1', '--arg2=value2');

Remember that any blank in command line means a separator between elements of @ARGV.

Trapping syntax errors with $SIG{__WARN__}

Function parse_cmd_line warns and calls exit(...) when syntax is wrong (in case help usage is invoqued no warn is issued).

Warnings can be captured defining a warn handler. See tests for an example.

Do not exit programm in case of help invocation or wrong syntax.

pod2usage, and also parse_cmd_line in their hash refs, allows the use of -exitval = 'noexit'>, meaning that program must not be terminated (pod2usage does not call exit).

REQUIREMENTS ^

As a wrapper of Getopt::Long and Pod::Usage, these modules are required.

SEE ALSO. ^

See Getopt::Long for syntax specification of command line options and configuration in new and load_options.

See Pod::Usage for last two optional arguments of parse_cmd_line.

AUTHOR AND LICENSE ^

Enrique Castilla Contreras (ecastillacontreras@yahoo.es).

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION ^

  $Id: Yagow.pm,v 1.1 2004/02/10 12:58:02 ecastilla Exp $
syntax highlighting: