cmdparse

NAME

SYNOPSIS

cmdparse

[-anywhere] [-ignore-case] [-noabort] [-noguessing] [-prompt] [-plus] [-options-only] [-keywords-only] [-quiet] [-arrays] [-usage] [-version] [-true string] [-false string] [-suffix string]
[-shell shellname] [-file filename] [-env varname] [-decls string]    program-name   arguments ...

DESCRIPTION

If none of -file, -env, or -decls is given then the argument declarations will be read from standard input (unless standard input is associated with a terminal, in which case an error will result).

If more than one of -file, -env, or -decls is given then argument declarations are read from all the places specified but in the following order:

First, argument declarations are read from the string supplied with the -decls option.

Second, any argument declarations contained in the environment variable specified by the -env option are appended to the current set of argument declarations.

Lastly, any argument declarations contained in the file specified by the -file option are appended to the current set of argument declarations.

The order in which the set of argument declarations are processed is important because any positional parameters that were specified are expected to occur in the same order as the order in which the corresponding argument declarations were processed.

Depending upon which shell you are using, you may want to evaluate the output of cmdparse directly (as in "eval $cmdparse_output") or you may wish to first redirect output to a file and then evaluate it (as in ". cmdparse_output"). Some shells may not preserve all the special characters (such as a newline) correctly when the former approach is used. Other shells may not permit you to change the value of "local" variables in "sourced" files when the latter approach is used. You will have to decide which approach to use based upon your needs, and the shell you are using.

EXAMPLE

#!/bin/sh
#
# Here is a Bourne Shell script named "cmdname".
#
# The short-option syntax is:
#     cmdname [-c number] [-x] [-s char]
#             input-file [output-file ]
#
# The long-option syntax is:
#     cmdname [count number] [xmode] [separator char]
#             input-file [output-file ]
#             
NAME="`basename $0`"

## Declare the arguments.
ARGS='
   ArgInt   count  "[c|count number]"    "number of copies to print."
   ArgBool  xflag  "[x|xmode]"           "turn on x-mode."
   ArgChar  fdsep  "[s|separator char]"  "field-separator to use."
   ArgStr   input  "input-file"          "input file to read."
   ArgStr   output "[output-file ]"   "where to print output."
'

## Parse the arguments
if  cmdparse -shell=sh -decls="$ARGS"  $NAME "$@" > tmp$$
then
   ## Success - evaluate the result.
   .  tmp$$
   rm -f tmp$$
else
   ## Either usage was printed or we found a syntax error.
   EXITVAL=$?
   rm -f tmp$$
   exit $EXITVAL
fi

## Print the arguments
echo "xflag=" $xflag
echo "count=" $count
echo "fdsep=" $fdsep
echo "input=" $input
if [ "$output" ] ; then
   echo "output=" $output
fi

OPTIONS

-anywhere

Allow options (and keywords) to follow positional parameters. Unless this option is specified, anything that follows a positional parameter that resembles an option (begins with a `-') will be treated as yet another positional parameter.

-ignore-case

Ignore character case on single-character options.

-noabort

Don't exit if improper command-line syntax was used. Just ignore the errors and continue parsing.

-noguessing

By default, if an unknown single-character option appears on the command-line, cmdparse will "guess" by seeing if the option corresponds to a keyword. Similarly, if an unknown keyword (long-option) is encountered, cmdparse will see if it matches a single-character option. Specifying this option disables this behavior.

-prompt

Prompt the user interactively for any missing required arguments.

-plus

Allow the prefix ``+'' to be used to indicate a long-option. (this may also be specified by saying -+).

-options-only

Don't match keywords (long-options). Look only for single-character options.

-keywords-only

Don't match options. Look only for keywords (long-options). Using this option also allows the single-character option prefix (`-') to be used for long-options.

-quiet

Don't print command-line syntax error messages.

-arrays

Use alternative syntax for arrays. See the appropriate subsection of the section SHELLS to see how (and if) this option will affect the output of cmdparse.

-usage

Print command-line usage and exit. Don't parse anything!

-version

Print version information and exit. Don't parse anything!

-true string

The string to use for boolean arguments that are turned on. The default string is "TRUE" (unless the perl or tcl shells are used, in which case the default is "1").

-false string

The string to use for boolean arguments that are turned off. The default string is "" (unless the perl or tcl shells are used, in which case the default is "0").

-suffix string

When no value is supplied for an option that takes an optional value, the variable namesuffix, is set to TRUE (where name is the name of the corresponding variable and suffix is the string argument given to this option). If this option is not specified then the suffix "_FLAG" will be used.

-shell shellname

Set program arguments using the syntax of the given shell (default=sh).

-file filename

The file from which program argument declarations are read. If filename is ``-'' then standard input is read.

-env varname

The name of the environment variable containing the program argument declarations.

-decls string

The string that contains the program argument declarations.

Indicates the end of options/keywords.

program-name

The name of the program whose arguments are to be parsed. If desired, the program-name may be specified as a keyword (instead of positionally) using the syntax -name=program-name.

arguments ...

The program-arguments to be parsed

EXIT STATUS

0

Arguments were successfully parsed. No syntax errors were found and the shell-script variable settings have been printed on standard output.

1

Either usage or version information was explicitly requested. The desired information was printed on standard diagnostic output. No arguments were parsed.

2

Some type of command-line syntax error occurred. Any syntax error messages have been printed on standard diagnostic output.

3

An invalid or unknown shell (command-interpreter) was specified on the command-line to cmdparse. See the section entitled SHELLS for a list of the known shells.

4

A syntax error of some type occurred in one or more command-line argument declarations. Any syntax error messages have been printed on standard diagnostic output.

man2html: unable to open or read file ../parsing.man

ARGUMENT DECLARATIONS

<arg-type> <arg-name> <syntax> <description>

Where <arg-type> is one of the following (case-insensitive):

ArgInt

An integer value (or list of values).

ArgFloat

A floating-point value (or list of values).

ArgChar

A character value (or list of values).

ArgStr

A string value (or list of values).

ArgBool

A boolean flag that is initially FALSE and is turned on whenever it is matched.

ArgClear

A boolean flag that is initially TRUE and is turned off whenever it is matched.

ArgToggle

A boolean flag that is initially FALSE and is toggled whenever it is matched.

ArgUsage

Print usage and exit.

ArgDummy

A dummy argument.

If desired, the leading "Arg" portion of the type-name may be omitted.

The field <arg-name> is simply the name of the variable in your script that you wish to contain the resultant value from the command-line. Any default value must be assigned to the variable before invoking cmdparse.

The fields <syntax> and <description> MUST be enclosed in either single or double quotes! If you want the character you are using to quote the field to also appear within the field, then precede the quote character (inside the quotes) with a backslash (`\').

The <description> is simply a textual description of the argument.
  The <syntax> is a little trickier, there are three basic forms of syntax:

"c|keyword"

An option that may be matched by -c or by keyword and takes no value.

"c|keyword  value"

An option that may be matched by -c or by keyword and requires a value.

"value"

A positional parameter.

Note that the option-character MUST precede the keyword-name and that there must be NO spaces surrounding the `|' in ``c|keyword'' (unless either the option-character or the keyword-name is intended to be empty). If you wish a keyword to have no corresponding short-option (or vice versa) than put a blank in the option-character (or keyword) portion of the syntax declaration.

Any optional parts of the argument should appear inside square-brackets (`[' and `]') and a list of values is denoted by an ellipsis (`` ...''). Most options will be inside of square brackets to reflect the fact that they are "optional".

Some example <syntax> strings follow:

"c|keyword"

A required option.

"[c|keyword]"

An option with no value.

"[c|keyword  value]"

An option that takes a value.

"[c|keyword  [value]]"

An option that takes an optional value.

"[c|keyword  value ...]"

An option that takes one or more values.

"[c|keyword  [value ]]"

An option that takes zero or more values.

"value"

A required positional parameter.

"[value]"

An optional positional-parameter.

"[  |keyword]"

An option that may be matched by keyword but has no corresponding single character option.

"[c|  value]"

An option that takes a value but has no corresponding keyword name.

"[c|keyword]  value"

A required argument that may be matched either positionally or by keyword.

SYNTAX FLAGS

Normally, the value to an option may be supplied either in the same command-line token (as in "-cvalue"), or in a separate token (as in "-c  value"). If desired, the <syntax> field may optionally be followed by a colon (`:') and one of "SEPARATE" or "STICKY". The former specifies that the argument value may only occur in a separate command-line token, the latter specifies that the argument value may only occur in the same command-line token.

SHELLS

sh

The Bourne Shell. This shell is the standard Unix shell (designed and written by Stephen R. Bourne).

csh

The C Shell. Bill Joy's answer to sh using C-like syntax.

ksh

The Korn shell. David G. Korn's shell combining all the "best" features of sh and csh in a "clean" fashion.

bash

The Bourne Again Shell. The Free Software Foundation's answer to ksh.

zsh

The Z Shell. Paul Falstad's creation combining all the "best" features of ksh and csh plus some stuff of his own.

rc

The Plan 9 Unix shell designed by Tom Duff. A public domain implementation (with some enhancements) has been released by Byron Rakitzis.

perl

Larry Wall's practical extraction and report-generation language. Perl is not a "shell" in the same sense as the others but it is a (powerful) language in which Unix scripts may be written.

tcl

John K. Ousterhout's Tool Command Language. Karl Lehenbauer and friends have developed a tcl shell based on Ousterhout's command language.

In addition, ash is considered by cmdparse to be equivalent to sh; and tcsh and itcsh are considered to be equivalent to csh.

For each supported shell, cmdparse will output a combination of shell-variable and/or shell-array settings that correspond to the arguments that were supplied on the command-line. In addition, if an argument that takes an optional value was given on the command-line but NO value was supplied, then the shell-variable named name_FLAG is assigned the value TRUE (where name was the name specified in the <arg-name> field of the corresponding argument declaration). If desired, a suffix other than _FLAG may be used by specifying the -suffix option.

Any desired initial values for variables from the argument declaration string should be assigned BEFORE invoking cmdparse. cmdparse will NOT output variable settings for any arguments that were NOT supplied on the command-line. The only exception to this is when a positional argument that corresponds to the positional parameters of the shell-script is NOT supplied on the command-line; In this particular case, the positional parameters of the shell-script are unset (set to an empty list).

The exact syntax used to set variables and arrays for the corresponding shells is the subject of the next several subsections.

BOURNE SHELL

For the Bourne shell, shell variables are assigned using the following syntax:

name='value';

Shell arrays are assigned using the following syntax:

name='value1 value2 ';

If the -arrays option was specified then the following syntax is used to set arrays:

name_count=3; name1='value1'; name2='value2'; name3='value3';

If the <arg-name> field of an argument is one of "-", "", "*", or "@" then the argument corresponds to the positional parameters of the shell-script and the following syntax is used to set its value(s):

set 'value1' 'value2' ;

KORN SHELL

For the Korn shell, shell variables are assigned using the following syntax:

name='value';

Shell arrays are assigned using the following syntax:

set -A name 'value1' 'value2' ;

If the -arrays option was specified then the following syntax is used to set arrays:

set +A name 'value1' 'value2' ;

If the <arg-name> field of an argument is one of "-", "", "*", or "@" then the argument corresponds to the positional parameters of the shell-script and the following syntax is used to set its value(s):

set 'value1' 'value2' ;

C SHELL

For the C shell, shell variables are assigned using the following syntax:

set name='value';

Shell arrays are assigned using the following syntax:

set name=('value1' 'value2' ) ;

If the <arg-name> field of an argument is "argv" then the argument corresponds to the positional parameters of the script and may be unset.

BOURNE AGAIN SHELL

At present, the Bourne Again shell is treated exactly the same as the Bourne Shell.

Z SHELL

For the Z shell, shell variables are assigned using the following syntax:

name='value';

Shell arrays are assigned using the following syntax:

name=('value1' 'value2' ) ;

If the <arg-name> field of an argument is one of "-", "", "*", "@", or "argv" then the argument corresponds to the positional parameters of the shell-script and the following syntax is used to set its value(s):

argv=('value1' 'value2' ) ;

PLAN 9 SHELL

For rc (the Plan 9 Shell), shell variables are assigned using the following syntax:

name='value';

Shell arrays are assigned using the following syntax:

name=('value1' 'value2' ) ;

If the <arg-name> field of an argument is "*" then the argument corresponds to the positional parameters of the script and may be unset.

PERL

For Perl, variables are assigned using the following syntax:

$name = 'value';

arrays are assigned using the following syntax:

@name = ('value1', 'value2', ) ;

If the <arg-name> field of an argument is "ARGV" then the argument corresponds to the positional parameters of the script and may be unset.

A perl interface to cmdparse should have been installed in your standard perl library when cmdparse was installed. It may be used by saying:

require "cmdparse.pl" ;

somewhere in your perl-script. This will give you access to a perl function named "cmdparse" which may be used as follows:

eval &cmdparse("-decls=$ARGDECLS", $0, @ARGV);

Where $ARGDECLS is a variable containing a string of command-line argument declarations for cmdparse(1). The arguments to the perl function should be a vector of arguments to pass to cmdparse(1) on the command-line. The file cmdparse.pl in your perl library directory contains the implementation and documentation for the perl interface to cmdparse.

If a syntax error occurred on the command-line and -noabort was not specified then the cmdparse function will terminate the execution of the perl script and will NOT return to the caller.

TCL

For Tcl, variables are assigned using the following syntax:

set name "value";

arrays are assigned using the following syntax:

set name [ list "value1" "value2" ];

If the <arg-name> field of an argument is "argv" or "args" then the argument corresponds to the positional parameters of the script and may be unset.

A tcl interface to cmdparse should have been installed in your standard tcl library when cmdparse was installed. It may be used by saying:

load "cmdparse.tcl" ;

somewhere in your tcl script. This will give you access to a tcl procedure named "cmdparse" which may be used as follows:

eval [ cmdparse -decls=$argDecls $scriptName $argv ];

Where $argDecls is a variable containing a string of command-line argument declarations for cmdparse(1).

The arguments to the tcl cmdparse procedure are exactly the same as for cmdparse(1). The file cmdparse.tcl in your tcl library directory contains the implementation and documentation for the tcl interface to cmdparse.

If a syntax error occurred on the command-line and -noabort was not specified then the cmdparse procedure will terminate the execution of the tcl script and will NOT return to the caller.

Note:

The tcl cmdparse procedure will only work with tcl scripts that use a version of the tcl shell that contains the execl command!

man2html: unable to open or read file ../environ.man

FILES

/cmdparse

The executable file for cmdparse(1).

/cmdparse.pl

The perl interface (including documentation) to cmdparse(1).

/cmdparse.tcl

The tcl interface (including documentation) to cmdparse(1).

SEE ALSO

man2html: unable to open or read file ../caveats.man

man2html: unable to open or read file ../bugs.man

AUTHOR

Index

NAME

SYNOPSIS

DESCRIPTION

EXAMPLE

OPTIONS

EXIT STATUS

ARGUMENT DECLARATIONS

SYNTAX FLAGS

SHELLS

BOURNE SHELL

KORN SHELL

C SHELL

BOURNE AGAIN SHELL

Z SHELL

PLAN 9 SHELL

PERL

TCL

FILES

SEE ALSO

AUTHOR