Getopt::EvaP - evaluate Perl command line parameters.


NAME

Getopt::EvaP - evaluate Perl command line parameters.


SYNOPSIS

 use vars qw/@PDT @MM %OPT/;
 use Getopt::EvaP;
 EvaP \@PDT, \@MM, \%OPT;


EXPORT

use Getopt::EvaP exports the subs EvaP and EvaP_PAC into your name space.


DESCRIPTION

@PDT is the Parameter Description Table, which is a reference to a list of strings describing the command line parameters, aliases, types and default values. @MM is the Message Module, which is also a reference to a list of strings describing the command and it's parameters. %OPT is an optional hash reference where Evaluate Parameters should place its results. If specified, the historical behaviour of modifying the calling routines' namespace by storing option values in %Options, %options and $opt* is disabled.

Introduction

Function Evaluate Parameters parses a Perl command line in a simple and consistent manner, performs type checking of parameter values, and provides the user with first-level help. Evaluate Parameters is also embeddable in your application; refer to the evap_pac(2) man page for complete details. Evaluate Parameters handles command lines in the following format:

  command [-parameters] [file_list]

where parameters and file_list are all optional. A typical example is the C compiler:

  cc -O -o chunk chunk.c

In this case there are two parameters and a file_list consisting of a single file name for the cc command.

Parameter Description Table (PDT) Syntax

Here is the PDT syntax. Optional constructs are enclosed in [], and the | character separates possible values in a list.

  PDT [program_name, alias]
    [parameter_name[, alias]: type [ = [default_variable,] default_value]]
  PDTEND [optional_file_list | required_file_list | no_file_list]

So, the simplest possible PDT would be:

  PDT
  PDTEND

This PDT would simply define a -help switch for the command, but is rather useless.

A typical PDT would look more like this:

  PDT frog
    number, n: integer = 1
  PDTEND no_file_list

This PDT, for command frog, defines a single parameter, number (or n), of type integer with a default value of 1. The PDTEND no_file_list indicator indicates that no trailing file_list can appear on the command line. Of course, the -help switch is defined automatically.

The default_variable is an environment variable - see the section Usage Notes for complete details.

Usage Notes

Usage is similar to getopt/getopts/newgetopt: define a Parameter Description Table declaring a list of command line parameters, their aliases, types and default values. The command line parameter -help (alias -h) is automatically included by Evaluate Parameters. After the evaluation the values of the command line parameters are stored in variable names of the form $opt_parameter, except for lists which are returned as @opt_parameter, where parameter is the full spelling of the command line parameter. NOTE: values are also returned in the hashes %options and %Options, with lists being passed as a reference to a list.

Of course, you can specify where you want Evaluate Parameters to return its results, in which case this historical feature of writing into your namespace is disabled.


An optional PDT line can be included that tells Evaluate Parameters whether
or not trailing file names can appear on the command line after all the
parameters.  It can read I<no_file_list>, I<optional_file_list> or
I<required_file_list> and, if not specified, defaults to optional.  Although
placement is not important, this line is by convention the last line of the
PDT declaration.

Additionally a Message Module is declared that describes the command and provides examples. Following the main help text an optional series of help text messages can be specified for individual command line parameters. In the following sample program all the parameters have this additional text which describes that parameter's type. The leadin character is a dot in column one followed by the full spelling of the command line parameter. Use -full-help rather than -help to see this supplemental information. This sample program illustrates the various types and how to use EvaP(). The key type is a special type that enumerates valid values for the command line parameter. The boolean type may be specified as TRUE/FALSE, YES/NO, ON/OFF or 1/0. Parameters of type file have ~ and $HOME expanded, and default values stdin and stdout converted to `-' and `>-', respectively. Of special note is the default value $required: when specified, Evaluate Parameters will ensure a value is specified for that command line parameter.

All types except switch may be list of, like the tty parameter below. A list parameter can be specified multiple times on the command line. NOTE: in general you should ALWAYS quote components of your lists, even if they're not type string, since Evaluate Parameters uses eval to parse them. Doing this prevents eval from evaluating expressions that it shouldn't, such as file name shortcuts like $HOME, and backticked items like `hostname`. Although the resulting PDT looks cluttered, Evaluate Parameters knows what to do and eliminates superfluous quotes appropriately.


Finally, you can specify a default value via an environment variable.  If
a command line parameter is not specified and there is a corresponding
environment variable defined then Evaluate Parameters will use the value
of the environment variable.  Examine the I<command> parameter for the syntax.
With this feature users can easily customize command parameters to their
liking.   Although the name of the environment variable can be whatever you
choose,  the following scheme is suggested for consistency and to avoid
conflicts in names:

So, for example, D_DISCI_DO would name a default variable for the display_option (do) parameter of the display_command_information (disci) command. Works for MS-DOS and Unix.


Example

 #!/usr/local/bin/perl
     
 use Getopt::EvaP;
 @PDT = split /\n/, <<'end-of-PDT';
 PDT sample
   verbose, v: switch
   command, c: string = D_SAMPLE_COMMAND, "ps -el"
   scale_factor, sf: real = 1.2340896e-1
   millisecond_update_interval, mui: integer = $required
   ignore_output_file_column_one, iofco: boolean = TRUE
   output, o: file = stdout
   queue, q: key plotter, postscript, text, printer, keyend = printer
   destination, d: application = `hostname`
   tty, t: list of name = ("/dev/console", "/dev/tty0", "/dev/tty1")
 PDTEND optional_file_list
 end-of-PDT
 @MM = split /\n/, <<'end-of-MM';
 sample
        A sample program demonstrating typical Evaluate Parameters
        usage.
        Examples:
          sample
          sample -usage-help
          sample -help
          sample -full-help
          sample -mui 1234
 .verbose
        A switch type parameter emulates a typical standalone
        switch. If the switch is specified Evaluate Parameters
        returns a '1'.
 .command
        A string type parameter is just a list of characters,
        which must be quoted if it contains whitespace. 
        NOTE:  for this parameter you can also create and
        initialize the environment variable D_SAMPLE_COMMAND to
        override the standard default value for this command
        line parameter.  All types except switch may have a
        default environment variable for easy user customization.
 .scale_factor
        A real type parameter must be a real number that may
        contain a leading sign, a decimal point and an exponent.
 .millisecond_update_interval
        An integer type parameter must consist of all digits
        with an optional leading sign.  NOTE: this parameter's
        default value is $required, meaning that
        Evaluate Parameters ensures that this parameter is
        specified and given a valid value.  All types except
        switch may have a default value of $required.
 .ignore_output_file_column_one
        A boolean type parameter may be TRUE/YES/ON/1 or
        FALSE/NO/OFF/0, either upper or lower case.  If TRUE,
        Evaluate Parameters returns a value of '1', else '0'.
 .output
        A file type parameter expects a filename.  For Unix
        $HOME and ~ are expanded.  For EvaP/Perl stdin and
        stdout are converted to '-' and '>-' so they can be
        used in a Perl open() function.
 .queue
        A key type parameter enumerates valid values.  Only the
        specified keywords can be entered on the command line.
 .destination
        An application type parameter is not type-checked in
        any - the treatment of this type of parameter is
        application specific.  NOTE:  this parameter' default
        value is enclosed in grave accents (or "backticks").
        Evaluate Parameters executes the command and uses it's
        standard output as the default value for the parameter.
 .tty
        A name type parameter is similar to a string except
        that embedded white-space is not allowed.  NOTE: this
        parameter is also a LIST, meaning that it can be
        specified multiple times and that each value is pushed
        onto a Perl LIST variable.  In general you should quote
        all list elements.  All types except switch may be
        'list of'.
 end-of-MM
 EvaP \@PDT, \@MM;              # evaluate parameters
 print "\nProgram name:\n  $Options{'help'}\n\n";
 if (defined $Options{'verbose'}) {print "\nverbose = $Options{'verbose'}\n";}
 print "command = \"$Options{'command'}\"\n";
 print "scale_factor  = $Options{'scale_factor'}\n";
 print "millisecond_update_interval = $Options{'millisecond_update_interval'}\n";
 print "ignore_output_file_column_one = $Options{'ignore_output_file_column_one'}\n";
 print "output = $Options{'output'}\n";
 print "queue = $Options{'queue'}\n";
 print "destination = $Options{'destination'}\n";
 print "'list of' tty = \"", join('", "', @{$Options{'tty'}}), "\"\n";
 print "\nFile names:\n  ", join ' ', @ARGV, "\n" if @ARGV;

Using the PDT as a guide, Evaluate Parameters parses a user's command line, returning the results of the evaluation to global variables of the form $opt_parameter, @opt_parameter, %Options{'parameter'} or %options{'parameter'}, where parameter is the full spelling of the command line parameter.

Of course, you can specify where you want Evaluate Parameters to return its results, in which case this historical feature of writing into your namespace is disabled.

Every command using Evaluate Parameters automatically has a -help switch which displays parameter help; no special code is required in your application.

Customization of EvaP's Help Output

There are several Help Hook strings that can be altered to customize EvaP's help output. Currently there is only one general area that can be customized: usage and error text dealing with the trailing file_list. For instance, if a command requires one or more trailing file names after all the command line switches, the default -help text is:

 file(s) required by this command

Some commands do not want trailing ``file names'', but rather some other type of information. An example is display_command_information where a single Program_Name is expected. The following code snippet shows how to do this:

  $Getopt::EvaP::evap_Help_Hooks{'P_HHURFL'} = " Program_Name\n";
  $Getopt::EvaP::evap_Help_Hooks{'P_HHBRFL'} =
        "\nA Program_Name is required by this command.\n\n";
  $Getopt::EvaP::evap_Help_Hooks{'P_HHERFL'} =
        "A trailing Program_Name is required by this command.\n";
  EvaP \@PDT, \@MM;

As you can see, the hash %evap_Help_Hooks is indexed by a simple ordinal. The ordinals are shown below and are mostly self-explanatory. In case you don't have access to the source for Evaluate Parameters, here are the default values of the Help Hook strings.

  $Getopt::EvaP:evap_Help_Hooks{'P_HHURFL'} = " file(s)\n";
  $Getopt::EvaP:evap_Help_Hooks{'P_HHUOFL'} = " [file(s)]\n";
  $Getopt::EvaP:evap_Help_Hooks{'P_HHUNFL'} = "\n";
  $Getopt::EvaP:evap_Help_Hooks{'P_HHBRFL'} =
         "\nfile(s) required by this command\n\n";
  $Getopt::EvaP:evap_Help_Hooks{'P_HHBOFL'} =
        "\n[file(s)] optionally required by this command\n\n";
  $Getopt::EvaP:evap_Help_Hooks{'P_HHBNFL'} = "\n";
  $Getopt::EvaP:evap_Help_Hooks{'P_HHERFL'} =
        "Trailing file name(s) required.\n";
  $Getopt::EvaP:evap_Help_Hooks{'P_HHENFL'} =
        "Trailing file name(s) not permitted.\n";

The Help Hooks naming convention is rather simple:

  P_HHtf
    where:
      P_HH  implies an Evaluate Parameters Help Hook
     t     type:
              U=Usage Help
              B=Brief and Full Help
              E=error message
      f     file_list:
              RFL=required_file_list
              OFL=optional_file_list
              NFL=no_file_list

Note to genPerlTk and genTclTk users: using these Help Hooks may cause the ``genTk programs'' to generate an unuseable Tk script. This happens because the ``genTk programs'' look for the strings ``required by this command'' or ``optionally required by this command'' in order to generate the file_list Entry widget - if these string are missing the widget is not created. An easy solution is to ensure that your Help Hook text contains said string, just like the code snippet above; otherwise you must manually add the required Tk code yourself.

Human Interface Guidelines

To make Evaluate Parameters successful, you, the application developer, must follow certain conventions when choosing parameter names and aliases.

Parameter names consist of one or more words, separated by underscores, and describe the parameter (for example, verbose and spool_directory).

You can abbreviate parameters: use the first letter of each word in the parameter name. Do not use underscores. For example, you can abbreviate command as c and delay_period as dp.

There are exceptions to this standard:

Variables MANPAGER, PAGER and D_EVAP_DO_PAGE

The environment variable MANPAGER (or PAGER) is used to control the display of help information generated by Evaluate Parameters. If defined and non-null, the value of the environment variable is taken as the name of the program to pipe the help output through. If no paging program is defined then the program more is used.

The boolean environment variable D_EVAP_DO_PAGE can be set to FALSE/NO/OFF/0, any case, to disable this automatic paging feature (or you can set your paging program to cat).

Return Values

EvaP() behaves differently depending upon whether it's called to parse an application's command line, or as an embedded command line parser (for instance, when using evap_pac()).

            Application      Embedded
            Command Line     Command Line 
 ----------------------------------------
 error      exit(1)          return(0)
 success    return(1)        return(1)
 help       exit(0)          return(-1)


SEE ALSO

 evap(2)
 evap.c(2)
 EvaP.pm(2)
 evap.tcl(2)
 evap_pac(2)
 addmm, add_message_modules(1)
 disci, display_command_information(1)
 genmp, generate_man_page(1)
 genpdt, generate_pdt(1)
 genPerlTk, generate_PerlTk_program(1)
 genTclTk, generate_TclTk_program(1)
 All available from directory F<ftp://ftp.Lehigh.EDU:/pub/evap/evap-2.x/>;.


BUGS

The code is messy (written in Perl4-ese), and should be redone, but I can't rationalize the time expenditure for code that still works so well.


AUTHOR

Stephen.O.Lidie@Lehigh.EDU


HISTORY

 lusol@Lehigh.EDU 94/10/28 (PDT version 2.0)  Version 2.2
   . Original release - derived from evap.pl version 2.1.
   . Undef option values for subsequent embedded calls.
 lusol@Lehigh.EDU 95/10/27 (PDT version 2.0)  Version 2.3.0
   . Be a strict as possible.
   . Revert to -h alias rather than -?.  (-? -?? -??? still available.)
   . Move into Getopt class.
   . Format for 80 columns (mostly).
   . Optional third argument on EvaP call can be a reference to your own
     %Options hash.  If specified, the variabes %Options, %options and 
     $opt* are not used.
 lusol@Lehigh.EDU 97/01/12 (PDT version 2.0)  Version 2.3.1
   . Fix Makefile.PL so it behaves properly.  Convert nroff man data to pod
     format.
 Stephen.O.Lidie@Lehigh.EDU 98/01/14 (PDT version 2.0)  Version 2.3.2
   . Incorporate Achim Bohnet's POD patch while updating for Win32.
 Stephen.O.Lidie@Lehigh.EDU 98/07/25 (PDT version 2.0)  Version 2.3.3
   . Update Makefile.PL so it works in the standard fashion.
   . Update for perl 5.005 and Tk 800.008.
   . Remove use of ENGLISH.
   . Add genpTk to generate a Perl/TK GUI wrapper around command line
     programs.  Primarily for users of EvaP(), can be used by other codes
     as well.
 Stephen.O.Lidie@Lehigh.EDU 99/04/03 (PDT version 2.0)  Version 2.3.5
   . Update Makefile.PL for ActiveState, fix a -w message found by 5.005_03.
 sol0@lehigh.edu 2010/01/19 (PDT version 2.0)  Version 2.3.6
   . Patch by Avner Moshkovitz to handle embedded quotes and spaces in string
     options.
 sol0@lehigh.edu 2013/04/06 (PDT version 2.0)  Version 2.5
   . Change -full_help and -usage_help to -full-help and -usage-help (change
     underscore to dash).
   . Evap_PAC obeys IGNOREEOF.
   . Embed the disac and ! MMs and PDTs in the code.
   . Messages now use a longer output line width.
   . Use fewer empty lines for -full-help output.
   . Allow "help" and "h" to stand for "disac -do f".
   . Evap_PAC now ensures that an application command exists.
   . disac now determines length of longest command for a tidy column display.
 sol0@lehigh.edu 2013/05/14 (PDT version 2.0)  Version 2.6
   . Add Term::ReadLine support in EvaP_PAC: uses readline() automatically if the 
     module is installed and input is coming from a terminal.

 sol0@lehigh.edu 2013/10/22 (PDT version 2.0)  Version 2.7
   . shellwords.pl is deprecated, use Text::ParseWords instead.

 sol0@lehigh.edu 2014/11/01 (PDT version 2.0)  Version 2.8
   . fix 2 defined() warnings.


COPYRIGHT

Copyright (C) 1993 - 2015 Stephen O. Lidie. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

 Getopt::EvaP - evaluate Perl command line parameters.