NAME

Getopt::Function - provide mixed options with help information

SYNOPSIS

    use Getopt::Function qw(maketrue makevalue);
    $::opthandler = new Getopt::Function 
      [ <option-list> ], { <option> => [ <function>, <short descript>, 
                                       <argument type>] }
   $result = GetOptions (...option-descriptions...);
   $::opthandler->std_opts;
   $::opthandler->check_opts;

DESCRIPTION

The aim of this module is to make it easy to provide sophisticated and complex interfaces to commands in a simple to use and clear manner with proper help facilities.

It is designed to do this by making it possible to write the options, with documentation and subroutines to implement them, directly into a hash and then call the appropriate ones as options detected on the command line.

$gto = new Getopt::Function

This constructor takes two arguments. the first is a reference to a list of options names in Getopt::Mixed format (see the documentation for Getopt::Mixed), but with options grouped in strings with their different forms.

The second argument is a reference to a hash of option functions and descriptions. Example:-

  new Getopt::Function 
    [ "red r>red", "green g>green", 
      "bright=s b>bright"] ,
    { "red" => [ &maketrue,
                   "print using red" ],
      "green" => [ sub { print STERR "warning: the green isn't very "
                                 . "good\n"; &maketrue},
                           "print using green" ],
      "bright" => [ &makevalue, "set brightness", "INTENSITY" ],
    }

EXAMPLE

This is a basic code example using most features

    use Getopt::Function qw(maketrue makevalue);

    use vars qw($not_perfect $redirect $since);

    $::ignore_missing=0;
    @::exclude=();
    @::include=();
    $::maxno=0;

    $::opthandler = new Getopt::Function
      [ "version V>version",
        "usage h>usage help>usage",
        "help-opt=s",
        "verbose:i v>verbose",
        "exclude=s e>exclude",
        "include=s i>include",
        "maxno=i",
      ],
      {
          "exclude" => [ sub { push @::exclude, $::value; },
            "Add a list of regular expressions for URLs to ignore.",
            "EXCLUDE RE" ],
          "include" => [ sub { push @::include, $::value; },
            "Give regular expression for URLs to check (if this "
            . "option is given others aren't checked).",
            "INCLUDE RE" ],
          "maxno" => [ \&makevalue, 
            "stop after a certain number",
            "ITERATIONS" ],
      };
    $::opthandler->std_opts;

    $::opthandler->check_opts;

    sub usage() {
      print <<EOF;
    example [options]

    EOF
      $::opthandler->list_opts;
      print <<EOF;

    Show off how we could use uptions
    EOF
    }

    sub version() {
      print <<'EOF';
    example version
    $NOTId: example.pl,v 1.3 1010/10/22 09:10:46 joebloggs Exp $
    EOF
    }

    my @list=biglist(); #get a list of things
    foreach $item ( @biglist ) {
      $maxno--;
      $maxno==0 && last;
      is_member ($item, @include) or is_member ($item, @exclude) && next;
      do_big_things @item;
    }

$gto->std_opts

This adds the standard options provided by the options module its self to the hash. It says nothing about the option list so some of these options may be made inaccessible.

To use these you have to provide the usage() and version() functions in the main package. Something like this.

        sub usage() {
          print <<EOF;
        lists-from-files.pl [options] url-base file-base

        EOF
          $::opthandler->list_opts;
          print <<EOF;

        Extract the link and index information from a directory containing
        HTML files.
        EOF
        }

        sub version() {
          print <<'EOF';
        lists-from-files version 
        $Id: Function.pm,v 1.10 2001/08/30 21:31:11 mikedlr Exp $
        EOF
        }

The standard functions will not override ones you have already provided.

usage: This just gives the usage information for the program then exits. Normally this should be mapped also to the --help option (and possibly a short option like -h if that's available).
version: This prints the version of the program then exits.
help-opt: This gives the help information for the options which are its parameters.
verbose: This sets the variable $::verbose to the value given as a parameter or $Getopt::Function::verbose_default (default value 4) if no value is given.
silent: This sets the variable silent to be true for hushing normal program output. Standard aliases to create for this would be --quiet and -q.

maketrue

This provides a convenience function which simply sets a variable in the main package true according to the option it is called for. If the option is negative (no-... e.g. no-delete as opposed to delete), it sets the variable false.

If the option name contains - then this is substituted for with a _.

makevalue

This provides a convenience function which simply sets a variable in the main package corresponding to the option to a the given value.

If the option name contains - then this is substituted for with a _.

check_opts

Checks all of the options calling the appropriate functions.

The following local variables are available to the function in the main package.

$::opt_obj: The option object. This can be used to call include
$::option: This is the option that was called. The same as the hash key that is used. It is determined through the option list. See above.
$::value: If the option can take a parameter this will contain it. It will be undefined if the parameter wasn't given.
$::as_entered: This will be the option string as entered.

opt_usage

This is really an internal function and is used to implement list_opts and help_opt. Given a string from the options list, this prints out the the options listed in the string and their docuentation in a neat format.

list_opts

This function prints out the usage information for all of the options.

help_opt

This function searches through the array of options until it gets one which matches then prints out its documentation.

If the help option is a single character then we only print out a single character option which matches exactly. Otherwise we print the first long option who's start matches. This doesn't guarantee that we unambiguously have chosen that option, but could be useful where someone has forgotten part of the option name...

BUGS

There is no scheme for automatic way to do negation. The workaround is to define the negative and positive options. This should be fixed.

Getopt::Function - provide mixed options with help information