NAME

Getopt::Alt::CookBook - Example usages of Getopt::Alt;

VERSION

This documentation refers to Getopt::Alt version 0.5.4.

EXAMPLES

Simple

Comparison with Getopt::Long

Simple example comparing Getopt::Long's GetOptions to Getopt::Alt's get_options

GetOptions:

    use Getopt::Long;
    use Pod::Usage;

    my %option;
    Getopt::Long::Configure('bundling');
    GetOptions(
        \%option,
        'dir|d=s',
        'verbose|v+',
        'man',
        'help',
        'VERSION!',
    ) or pod2usage(2);

    if ( $option{'VERSION'} ) {
        print "$name Version = $VERSION\n";
        exit 1;
    }
    elsif ( $option{'man'} ) {
        pod2usage( -verbose => 2 );
    }
    elsif ( $option{'help'} ) {
        pod2usage( -verbose => 1 );
    }

    # use options found in %options

get_options:

    use Getopt::Alt qw/get_options/;

    my ($options) = get_options(
        { helper => 1 },
        [ 'dir|d=s' ],
    );

    # use options found in %$options

The helper parameter gives adds the verbose, man, help and VERSION options to your options and will if --VERSION specified output the version of the calling module, if --man or --help is used will run pod2usage on the calling script. This all reduces the amount of boiler plate code needed in your scripts (of cause this means you should also write POD for your script).

Sub-Commands

Getopt::Alt has three sub command modes:

  • simple

  • HASH

  • Module

Simple

Just stops processing at first non-option parameter (assumed to be the sub command). Any further processing of sub-commands must be made manually (eg having what ever processes the sub-command doing further processing).

    use Getopt::Alt qw/get_options/;

    my ($options, $cmd) = get_options(
        { helper => 1, sub_command => 1 },
        [ 'dir|d=s' ],
    );

    # on the command line
    $ command --dir=/some/where sub --not-processed

    # will result in $option->{dir} eq /some/where and $cmd eq 'sub' and
    # @ARGV having ['--not-processed']

HASH

A hash is passed with the keys representing the sub commands and the values are the sub-commands parameters.

    use Getopt::Alt qw/get_options/;

    my ($options, $cmd) = get_options(
        {
            helper => 1,
            sub_command => {
                sub => [
                    'to be implemented'
                ],
            },
        }
        [ 'dir|d=s' ],
    );

Module

The final form for sub-commands is that they should be picked up by other modules

Auto Completion

    use Getopt::Alt qw/get_options/;

    my ($options, $cmd) = get_options(
        { helper => 1, auto_complete => \&my_auto },
        [ 'dir|d=s' ],
    );

The auto_complete parameter takes a code reference with is called when the script is with the --auto-complete parameter (supplied by helper => 1). Getopt::Alt will try to complete any unfinished options but not their values that is left to for $self-><sub_command> to process.

Eg ~/.bashrc function for auto completion of "command"

    _command() {
        local cur prev opts
        COMPREPLY=()
        cur="${COMP_WORDS[COMP_CWORD]}"
        prev="${COMP_WORDS[COMP_CWORD-1]}"
        # get list of command line options
        opts=$(command --auto-complete --auto-complete-list)

        if [[ ${cur} == -* && ${COMP_CWORD} -eq 1 ]]; then
            COMPREPLY=($(compgen -W "${opts}" -- ${cur}))
        else
            local sonames=$(command --auto-complete ${COMP_WORDS[@]})
            COMPREPLY=($(compgen -W "${sonames}" -- ${cur}))
        fi
    }
    complete -F _command command

AUTHOR

Ivan Wills - (ivan.wills@gmail.com)

LICENSE AND COPYRIGHT

Copyright (c) 2009 Ivan Wills (14 Mullion Close, Hornsby Heights, NSW Australia 2077). 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. 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.