Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Getopt::EvaP
evaluate Perl command line parameters.

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:
  • Use all uppercase characters.

  • Begin the variable name with D_, to suggest a default variable.

  • Continue with the name of the command or its alias followed by an underscore.

  • Complete the variable name with the name of the parameter or its alias.

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:

  • password is abbreviated pw.

  • The words minimum and maximum are abbreviated min and max. So, the abbreviation for the parameter maximum_byte_count is maxbc.

  • There are no abbreviations for the parameters usage_help and full_help; I do not want to prevent uh and fh from being used as valid command line parameters.

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.




COPYRIGHT

Copyright (C) 1993 - 1999 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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy