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

    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;

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

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.

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

Returns object itself.

argument_list may be:

• A hash with options specifications as keys, with syntax described in Getopt::Long documentation, and default values as hash values. For example:
  
  

       $opt->load_options ( 
           'file=s' => '',
           'file_icon|f_icon|fi:s' => 'c:\Perl\site\lib\tk\file.xbm'
       ); 
  
  

• A hash reference. The referenced hash is supposed to have the preceding syntax.
• A hash ref and an array ref. The referenced hash with the preceding syntax, and the referenced array must be a list of configuration options for Getopt::Long::Configure (see doc for valid options). Sample:
  
  

       $opt->load_options ( {
                 'file=s' => '',
                 'file_icon|f_icon|fi:s' => 'c:\Perl\site\lib\tk\file.xbm' },
                 ['require_order','pass_through'] 
       );
  
  

load_options creates some hash members in %$opt:

• If configuration options (passed to Getopt::Long) are specified, a key named configuration is created in %$opt. Its value is same array ref passed as argument ( ['require_order','pass_through'] in last example).
• Options specifications whose default value is undef are intended to be mandatory, i.e. they MUST BE specified in command line with correct syntax. Also, for this options specifications a mandatory key is created in %$opt. So, $opt-{mandatory}> is an array reference of (mandatory) option names.
• For options specifications whose default value is not undef, an entry named default is added to %$opt. So, $opt-{default}> is a hash ref whose keys are option names and their values are default values taken if these options are not specified in command line.
• In any case, all options specified are stored in an entry named options, added to %$opt. So, $opt-{options}> is a hash whose keys are options names, and their values are options specifications.

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 :, !, +).

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:

• Options used in command line or argument list are saved in $opt-{used}>. This is a hash whose keys are options names, and their values are those used in command line or function call. So, in last example:
  
  

      $opt->{used} == {
                          file1 => 'one_file.txt',
                          file2 => 'C:\icon.jpg'   
                      }
  
  

  
  
  Note that option names are used as keys, not option abbreviations as specified in command line or call to parse_cmd_line.
  
  Also, used options are deleted from $opt-{default}>. As a result when parse_cmd_line returns $opt-{default}> contains only default values for options not used in command line or function arguments.
• If 'pass_through' is used in load_options (or new) or command line, then unknown arguments are stored in $opt-{unhandled_options}>. This is an array ref with a list of unknown arguments as specified in command line or function call. So, in last example:
  
  

      $opt->{unhandled_options} == ['--unknown=any_string']
  
  

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

    configuration
    options
    default
    mandatory
    used
    unhandled_options

Returns $opt->{configuration} .

Returns $opt->{options}> .

Returns $opt->{default}.

Returns $opt->{mandatory}.

Returns $opt->{used}.

Returns $opt->{unhandled_options}.

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

    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

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.

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.

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.

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).

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

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.

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.

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