Getopt::Param - param() style opt handling
This document describes Getopt::Param version 0.0.5
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"
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
Can take no arguments or one hashref whose keys are desribed below (non are required)
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
A language object that can() maketext(), see "LOCALIZATION" below and Locale::Maketext::Pseudo
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'
Boolean that when true supresses the FYI about invalid options in the array.
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.
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.
Array reference of all known flags, if unknown flags are passed a warning is issued and the help function is called.
Array reference of all required flags, if any are not passed warning is issued and the help function is called.
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
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.
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.
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');
my $name = $prm->get_param('name'); my @names = $prm->get_param('name');
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"; }
Like set_param() but puts values after existing values (if any).
Like set_param() but puts values before existing values (if any).
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
Returns true if there was a param of that "name" passed
if( $prm->exists_param('name') ) { ... }
Returns a serializable hashref of the param's and their values (in array refs)
Executes the object's help coderef. If you did not specify a 'help_coderef' you'll get an error about that instead.
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.
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.
Getopt::Param requires no configuration files or environment variables.
Class::Std, Class::Std::Utils, Locale::Maketext::Pseudo
None reported.
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.
bug-getopt-param@rt.cpan.org
- (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++; }
Daniel Muey <http://drmuey.com/cpan_contact.pl>
<http://drmuey.com/cpan_contact.pl>
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.
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.