The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Zoidberg::Utils::GetOpt - Yet another GetOpt module

SYNOPSIS

        use Zoidberg::Utils qw/getopt/;
        
        sub export {
                my (undef, $args) = getopt '%', @_;
                for (keys %$args) { $ENV{$_} = $$args{$_} }
        }
        
        export( 'PS1=\\u\\h\\$ ' );
        export( {PS1 => '\\u\\h\\$ '} ); # equivalent with the above
        
        sub kill {
                my ($opts, $args) = getopt 'list,l s$ n$ @', @_;
                die 'to many arguments' if @$args > 1;
                goto &list_sigs if $$opts{list};
                my $sig = $$opts{s} || $$opts{n} || '15';
                for my $pid (@$args) {
                    ...
                }
        }
        
        kill( '-n', 'TERM', '--', @pids );
        kill( '-n' => 'TERM', \@pids ); # equivalent with the above
        

DESCRIPTION

Although when working within the Zoidberg framework this module should be used through the Zoidberg::Utils interface, it also can be used on it's own.

This module provides a general 'getopt' interface, aimed at built-in functions for zoid. The idea is that this library can handle both commandline arguments and perl data structures. Also it should be flexible enough to parse most common styles for commandline arguments.

EXPORT

The function getopt() is exported by default whe nusing the module directly. Also you can ask for usage() and version() to be exported.

METHODS

getopt($config)

Returns references to data structures with options and arguments.

Otions are seperated by whitespace in the config string. A single letter in the config string represents a bit-wise option, a word is regarded as a (gnu-style) long option. You can have long and short versions of the same option by writing them seperated by a ','. When a option (or a combination of option and aliases) is followed by a sigil ('$' or '@') argument(s) of that type are read. Note that the array sigil ('@') does not mean that an option takes multiple arguments at once, but that the option can occur multiple times, it also means that the option can take an array reference as argument. For short options a '+' variant is used for the non-true value.

If an options config string starts with an '-' or an '+' it is considered a long option with a single '-' (not gnu but X-style) or '+'.

If the config string ends in a single sigil ('%' or '@') a reference of this type is returned containing all the arguments following the options. If the config string end in a single '*' two references are returned, an array reference containing all arguments, and a hash reference containing values for those arguments that formed key-value pairs. If no sigil is given a array reference is returned containing all remaining arguments exactly as they were found.

The options '--version' (alias '-V') and '--usage' (alias '-u', '--help' and '-h') are by default special. TODO how are these returned / printed ?

Options can not start with an '_', it is reserved for some meta fields.

FIXME tell about globs and _opts

version()

Returns a version string for the calling module. Used for the default '--version' option.

usage($cmd)

Returns a usage message for $cmd based on the POD of the calling module. Used for the default '--usage' and '--help' options.

path2hashref(\%hash, $path)

Returns a reference to a sub-hash of %hash, followed by a key and the path to that sub-hash. Intended to be used by built-in commands that manipulate hash structures for handling commandline args.

AUTHOR

Jaap Karssenberg (Pardus) <pardus@cpan.org>

Copyright (c) 2011 Jaap G Karssenberg and Joel Berger. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Zoidberg, Zoidberg::Utils