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

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.

To install Getopt::Param, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Getopt::Param

CPAN shell

perl -MCPAN -e shell
install Getopt::Param

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)