Daniel Muey > Getopt-Param-0.0.5 > Getopt::Param

Download:
Getopt-Param-0.0.5.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.0.5   Source  

NAME ^

Getopt::Param - param() style opt handling

VERSION ^

This document describes Getopt::Param version 0.0.5

SYNOPSIS ^

    use Getopt::Param;
    my $prm = Getopt::Param->new(...);

    $prm->help() if $prm->get_param('number') !~ m{\A\d+\z}xms; # --help, see 'help_coderef' new() key
    
    $log->debug( "Start: $$ " . time() ) if $prm->get_param('debug'); # --debug
   
    print "Starting process...\n" if $prm->get_param('verbose'); # --verbose

    do_this();
  
    do_that() if that_is_needed() || $prm->get_param('force'); # run this regardless if --force
    
    do_theother() if $prm->get_param('theother'); # --theother
    
    print "...Done!\n" if $prm->get_param('verbose'); # --verbose
    
    $log->debug "End: $$ " . time() ) if $prm->get_param('debug'); # --debug 

    $lang->say(q{User '[1]' has been setup with the name '[2]'}, $prm->param('user'), $prm->param('name')); # --user=dan --name="Dan Muey"

DESCRIPTION ^

Parses an array and gives it a CGI-like param interface to the data. You can then have apps that have a cgi interface and a cli interface that just call param() to get its stuff.

Examples:

  Opt: --force=1 URI Equiv: force=1
  Opt: --force=  URI Equiv: force=
  Opt: --force   URI Equiv: force=--force
  Opt: --force=hello         URI Equiv: force=hello
  Opt: --force="hello world" URI Equiv: force=hello+world
  Opt: --force=a --force=b   URI Equiv: force=a&force=b

INTERFACE ^

new()

Can take no arguments or one hashref whose keys are desribed below (non are required)

array_ref

The array to get the params from, defaults to @ARGV if none is given.

Note: No array's are harmed inthe making of this object.

Note: An item of '--' marks the end of parameter processing like in a shell

lang_obj

A language object that can() maketext(), see "LOCALIZATION" below and Locale::Maketext::Pseudo

strict

Boolean that when true means that each option must start with two '-' and then a non dash character (or else its ignored)

   --good ---bad

When its false as long as it starts with two '-' then its ok:

   ---allowed --good

in that case your param() name will be '-allowed' not 'allowed'

quiet

Boolean that when true supresses the FYI about invalid options in the array.

help_coderef

This gets executed if the param 'help' exists (IE --help), by the help() method, and under other circumstance described in the POD.

The object is passed in as its argument.

no_args_help

If this is true and no arguments are given your help_coderef is executed. If you did not specify a 'help_coderef' you'll get an error about that instead.

known_only

Array reference of all known flags, if unknown flags are passed a warning is issued and the help function is called.

required

Array reference of all required flags, if any are not passed warning is issued and the help function is called.

validate

A code reference that gets passed the object, you can do any checking you like.

A good idea is to carp about any problems and return;

Returning false will trigger help

actions

An array reference containing array references where item 0 is the flag and item 1 is a code ref to execute (or if not a code ref then help wil be done)

    'actions' => [
        ['usage', 1], # help alias
        ['perldoc', sub {...}],
        ['man', sub {...}],
        ['bincheck', sub { print "Binary ok!";exit; } ],
    ]

Like help, each of these is a passed the object.

param()

Acts like the get/set param you are used to in CGI based object's param() and when called with no args returns a list of param names available. When creating a generic "param" obj for use by an app that is CGI and CLI aware you may be stuck doing this multi function param() but if possible I'd recommend using the specific ones and creating a class method that wraps them:

   sub get_param {
       my ($self, $name) = @_;
       $self->{'param_obj'} = $self->can('get_param') ? $self->{'param_obj'}->get_param( $name )
                                                      : $self->param( $name )
                                                      ;
   } 

That allows you to use a non ambiguous get_param everywhere in your app regardless of what the param_obj actually needs to do.

set_param()

Sets the param named as the first arg to the value(s) of the rest of the args:

   $prm->set_param('name', 'v1', 'v2', 'etc');
get_param()
    my $name  = $prm->get_param('name');
    my @names = $prm->get_param('name');
list_params()

Returns all available param names, like calling param() with no arguments:

    for my $param ( $prm->list_params() ) {
        print "1st $param is: " . $prm->param( $param ) . "\n";
    }
append_param()

Like set_param() but puts values after existing values (if any).

prepend_param()

Like set_param() but puts values before existing values (if any).

delete_param()

Deletes the given param name from the param data, returns its current values in an arrayref.

    # $prm->exists_param('name') is true
    my $dog_arrayref = $prm->delete_param('dog');
    # $prm->exists_param('name') is false 
exists_param()

Returns true if there was a param of that "name" passed

    if( $prm->exists_param('name') ) {
        ...
    }
get_param_hashref()

Returns a serializable hashref of the param's and their values (in array refs)

help()

Executes the object's help coderef. If you did not specify a 'help_coderef' you'll get an error about that instead.

DIAGNOSTICS ^

Argument %d did not match %s

This is just a sort of FYI that the array had a value ( at index '%d') that did not start with the regex ('%s') that detemrines if an argument was an option or not and therefore will be ignored

The regex is based on your 'strict' key value [not ]passed to new() .

This can be supressed by passing new() 'quiet' => 1

No '%s' function defined

Something has triggered a coderef as per your new() args but the given coderef was not defined in new.

Unknown argument '%s'

'known_only' was set and an argument that was not in that list was passed.

Missing argument '%s'

'required' was set and one or more of those flags were not passed.

LOCALIZATION ^

This module uses Locale::Maketext::Pseudo as a default if nothing else is specified to support localization in harmony with the apps using it.

See "DESCRIPTION" at Locale::Maketext::Pseudo for more info on why this is good and why you should use this module's language object support at best and, at worst, appreciate it being there for when you will want it later.

CONFIGURATION AND ENVIRONMENT ^

Getopt::Param requires no configuration files or environment variables.

DEPENDENCIES ^

Class::Std, Class::Std::Utils, Locale::Maketext::Pseudo

INCOMPATIBILITIES ^

None reported.

BUGS AND LIMITATIONS ^

No bugs have been reported.

Please report any bugs or feature requests to bug-getopt-param@rt.cpan.org, or through the web interface at http://rt.cpan.org.

TODO ^

- (This was a comment in BUILD()'s code) allowed/required/description hr + auto help_coderef generation ? Getopt::Param::Config ?

- Short option (-u user instead of --user=user) support

- Positional option support

For now if you want to have some positional args or args that are otherwise not --long switches:

  # 1) use 'quiet' in your construtor
  # 2) parse the array in question and set_param() as per your needs:
  
  use Getopt::Param;
  my $prm = Getopt::Param->new({ 'quiet' => 1 });
  
  $prm->set_param('revision', $ARGV[0]) if $ARGV[0] =~ m{^\d+$};
  
  my $idx = 0;
  for my $arg (@ARGV) {
      if( $arg eq '-r' ) {
          $prm->set_param('revision', $ARGV[ $idx + 1]):
      }
      $idx++;
  }

AUTHOR ^

Daniel Muey <http://drmuey.com/cpan_contact.pl>

LICENCE AND COPYRIGHT ^

Copyright (c) 2007, Daniel Muey <http://drmuey.com/cpan_contact.pl>. All rights reserved.

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

DISCLAIMER OF WARRANTY ^

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

syntax highlighting: