Getopt::Valid - Extended processing and validation of command line options
Implements an extended getopt mechanism relying on Getopt::Long but provides extended validation and filtering capabilities.
Useful for shell scripts.
I wrote this, because i need input validation / processing in most of my scripts. This keeps it formal and readable while not making me re-implement the wheel over and over again.
The dependency footprint is rather small (only Getopt::Long).
#!/usr/bin/perl use strict; use warnings; use Getopt::Valid; # # VALIDATION DEFINITION # my $validation_ref = { # name of the program name => 'MyScript', # fallback to $0, if not set # version info version => '1.0.1', # fallback to $main::VERSION or "unknown", if not set # the struct of the params struct => [ # extended example 'somestring|s=s' => { description => 'The description of somestring', constraint => sub { my ( $val ) = @_; return index( $val, '123' ) > -1 }, required => 1, }, # Example using only validator and fallback to default description. # This value is optional (mind: no "!") 'otherstring|o=s' => qr/^([a-z]+)$/, # all lowercase words # Example of using integer key with customized description. # This value is optional (mind the "!") 'someint|i=i!' => 'The description of someint', # Bool value using the default description 'somebool|b' => undefm # the following is implicit, prints out the usag and exists.. can be overwritten #'help|h' => 'Show this help' ] }; # # FUNCTIONAL USAGE # my $validated_args_ref = GetOptionsValid( $validation_ref ) || die "Failed to validate input\n". join( "\nERRORS:\n", @Getopt::Valid::ERRORS, "\n\nUSAGE:\n", $Getopt::Valid::USAGE ); # acces the user input print "Got $validated_args_ref->{ somestring }\n"; # # OBJECT USAGE # my $opt = Getopt::Valid->new( $validation_ref ); # collect data from @ARGV.. you could manipulate @ARGV and run again.. $opt->collect_argv; # whether validates if ( $opt->validate ) { # acces valid input data print "Got ". $opt->valid_args->{ somestring }. "\n"; } # oops, not valid else { # print errors print "Oops ". $opt->errors( " ** " ). "\n"; # print usage print $opt->usage(); }
name STRING
Name of the program. Use in help output.
Defaults to $0
version VERSION STRING
Version of the program. Used in help output. Tries $main::VERSION, if not set.
Defaults to "unknown"
underscore BOOL
Whether "-" characters in arguments shall be rewritten to "_" in the result.
Default: 0 (disabled)
struct ARRAYREF
Structure of the arguments. The order will be respected in the help generation.
Can be written in 4 styles
SCALAR
$struct_ref = [ 'argument-name|a=s' => 'Description text for help', 'other-arg' => 'Description text for help' ];
REGEXP
$struct_ref = [ 'argument-name|a=s' => qr/(bla|blub), ];
CODE
$struct_ref = [ 'argument-name|a=s' => sub { my ( $value, $name, $validator ) = @_; warn "Checking '$name' = '$value'\n"; return $value eq 'ok'; } ];
HASH
$struct_ref = [ 'argument-name|a=s' => { # the description for the help description => 'Description text for help', # default value, if not given default => 'Some Default', # whether required (redundant for bool), default: 0 required => 1|0, # constraint can be regexp or code-ref, see above constraint => sub { .. }, # modify value before handing to constraint (if any) prefilter => sub { my ( $value, $name, $validator ) = @_; return "THE NEW $value\n"; }, # modify value after constraint check (if any). runs only if valid (or no constraint). postfilter => sub { my ( $value, $name, $validator ) = @_; return "THE NEW $value\n"; }, # trigger is called in any case, even if arg not given anytrigger => sub { my ( $value, $name, $validator ) = @_; return ; # ignored }, # trigger is called if value is defined / given (independent if validated) settrigger => sub { my ( $value, $name, $validator ) = @_; return ; # ignored }, # trigger is called if value is validated (or no validator is given) oktrigger => sub { my ( $value, $name, $validator ) = @_; return ; # ignored }, # trigger is called if value is invalid (or no validator is given) oktrigger => sub { my ( $value, $name, $validator ) = @_; return ; # ignored }, } ];
In functional context, you can access the errors via @Getopt::Valid::ERRORS and the usage via $Getopt::Valid::USAGE
@Getopt::Valid::ERRORS
$Getopt::Valid::USAGE
See "VALIDATOR SYNTAX"
Constructor. See "VALIDATOR SYNTAX"
Collect args found in @ARGV using Getopt::Long#GetOptions
@ARGV
Set/get args.
Performs validation of the input. Returns differently in array- or scalar-context.
Array context
Returns ( has_errors, hashref_of_valid_input )
my ( $valid, $input_ref ) = $obj->validate(); if ( $valid ) { print "All good, got arg 'some_arg': $input_ref->{ some_arg }\n"; }
Scalar context
Returns whether validation was successfull (or any error ocurred)
if ( scalar $obj->validate() ) { print "All good, got arg 'some_arg': ". $opt->valid_args->{ some_arg }. "\n"; }
Returns validated args
Returns usage as string
Returns errors as joined string or array of strings of the last valid-run
Getopt::Long
Latest release on Github http://github.com/ukautz/Getopt-Valid
Ulrich Kautz <uk@fortrabbit.de>
Copyright (c) 2012 the "AUTHOR" as listed above.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
This library is free software and may be distributed under the same terms as perl itself.
To install Getopt::Valid, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::Valid
CPAN shell
perl -MCPAN -e shell install Getopt::Valid
For more information on module installation, please visit the detailed CPAN module installation guide.