The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Getopt-Valid-v0.1.4
River stage zero No dependents
++
/ Getopt::Valid

NAME

Getopt::Valid - Extended processing and validation of command line options

DESCRIPTION

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

SYNOPSIS

    #!/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();
    }

VALIDATOR SYNTAX

  • 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
            },
        }
    ];

EXPORTED METHODS

In functional context, you can access the errors via @Getopt::Valid::ERRORS and the usage via $Getopt::Valid::USAGE

GetOptionsValid $validator_ref

See "VALIDATOR SYNTAX"

CLASS METHODS

new $validator_ref

Constructor. See "VALIDATOR SYNTAX"

collect_argv

Collect args found in @ARGV using Getopt::Long#GetOptions

args

Set/get args.

validate

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";
    }

valid_args

Returns validated args

usage

Returns usage as string

errors

Returns errors as joined string or array of strings of the last valid-run

SEE ALSO

AUTHOR

  • Ulrich Kautz <uk@fortrabbit.de>

COPYRIGHT AND WARRANTY

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.

LICENCSE

This library is free software and may be distributed under the same terms as perl itself.