Advanced command-line flag library for Unix shell scripts. More...

This graph shows which files directly or indirectly include this file:

Functions
function	_flags_columns ()
function	_flags_currentStr ()
function	_flags_defaultStr ()
function	_flags_define ()
function	_flags_flagusage ()
function	_flags_genOptStr ()
function	_flags_getFlagDefault ()
function	_flags_getFlagInfo ()
function	_flags_getFlagValue ()
function	_flags_getoptEnhanced ()
function	_flags_getoptStandard ()
function	_flags_helpman_flagusage ()
function	_flags_itemInList ()
function	_flags_manText ()
function	_flags_parseGetopt ()
function	_flags_sortList ()
function	_flags_typeStr ()
function	_flags_underscoreName ()
function	_flags_validateBoolean ()
function	_flags_validateFloat ()
function	_flags_validateInteger ()
function	_flags_validateUnsignedInteger ()
function	_flags_xmlText ()
function	FLAGS ()
function	flags_getoptInfo ()
function	flags_getoptIsEnh ()
function	flags_getoptIsStd ()
function	flags_help ()
function	flags_helpflag ()
function	flags_helpflags ()
function	flags_helpflagxml ()
function	flags_helpman ()
function	flags_helpman_contact ()
function	flags_helpman_copyright ()
function	flags_helpman_description ()
function	flags_helpman_flag ()
function	flags_helpman_flags ()
function	flags_helpman_name ()
function	flags_helpman_synopsis ()
function	flags_helpshort ()
function	flags_helpxml ()
function	flags_reset ()
function	flags_usage ()
function	flags_version ()

Detailed Description

Advanced command-line flag library for Unix shell scripts.

Author:: Kate Ward <kate.ward at forestent.com>, Andreas Schuh

See also:: http://code.google.com/p/shflags/

Note:: The shFlags implementation by Kate Ward (revision 147) has been considerably modified by Andreas Schuh as part of the BASIS project to fit the needs of the SBIA Group at The University of Pennsylvania.

This module implements something like the google-gflags library available from http://code.google.com/p/google-gflags/.

FLAG TYPES: This is a list of the DEFINE_*'s that you can do. All flags take a name, default value, help-string, and optional 'short' name (one-letter name). Some flags have other arguments, which are described with the flag.

DEFINE_string: takes any input, and intreprets it as a string.

DEFINE_boolean: typically does not take any argument: say --myflag to set FLAGS_myflag to true, or --nomyflag to set FLAGS_myflag to false. Alternatively, you can say --myflag=true or --myflag=t or --myflag=0 or --myflag=false or --myflag=f or --myflag=1 Passing an option has the same affect as passing the option once.

DEFINE_float: takes an input and intreprets it as a floating point number. As shell does not support floats per-se, the input is merely validated as being a valid floating point value.

DEFINE_integer: takes an input and intreprets it as an integer.

SPECIAL FLAGS: There are a few flags that have special meaning: --help (or -?) prints a list of all the flags in a human-readable fashion --flagfile=foo read flags from foo. (not implemented yet) -- as in getopt(), terminates flag-processing

EXAMPLE USAGE:

Example script hello.sh(.in):

 #! /bin/sh
 @BASIS_BASH_UTILITIES@

 DEFINE_string name 'world' "somebody's name" n

 FLAGS "$@" || exit $?
 eval set -- "${FLAGS_ARGV}"

 echo "Hello, ${FLAGS_name}."

Usage of example script hello.sh:

 $ ./hello.sh -n Kate
 Hello, Kate.

CUSTOMIZABLE BEHAVIOR:

A script can override the default 'getopt' command by providing the path to an alternate implementation by defining the FLAGS_GETOPT_CMD variable.

ATTRIBUTES:

Shared attributes: flags_error: last error message flags_return: last return value

__flags_longNames: list of long names for all flags __flags_shortNames: list of short names for all flags __flags_boolNames: list of boolean flag names

__flags_opts: options parsed by getopt

Per-flag attributes: FLAGS_<flag_name>: contains value of flag named 'flag_name' __flags_<flag_name>_default: the default flag value __flags_<flag_name>_help: the flag help string __flags_<flag_name>_short: the flag short name __flags_<flag_name>_type: the flag type __flags_<flag_name>_category: category of flag, use special category 'required' to denote flags that need to be given on the command line

NOTES:

Not all systems include a getopt version that supports long flags. On these systems, only short flags are recognized.

Lists of strings are space separated, and a null value is the '~' char.

Released under the LGPL (GNU Lesser General Public License)

Definition in file shflags.sh.

Function Documentation

function _flags_columns ( )

Returns the width of the current screen.

Output: integer: width in columns of the current screen.

function _flags_currentStr ( )

Convert current value to string for help output.

function _flags_defaultStr ( )

Convert default value to string for help output.

function _flags_define ( )

Define a flag.

Calling this function will define the following info variables for the specified flag: FLAGS_flagname - the name for this flag (based upon the long flag name) __flags_<flag_name>_default - the default value __flags_<flag_name>_help - the help string __flags_<flag_name>_short - the single letter alias __flags_<flag_name>_type - the type of flag (one of __FLAGS_TYPE_*) __flags_<flag_name>_category - the category of the flag

Args: _flags_type: integer: internal type of flag (__FLAGS_TYPE_*) _flags_name: string: long flag name _flags_default: default flag value _flags_help: string: help string _flags_short: string: (optional) short flag name _flags_category: string: (optional) category name this flags belongs to Returns: integer: success of operation, or error

function _flags_flagusage ( )

Output short usage of named flag.

Args: _flags_name_: string: long flag name Outputs: string: usage of flag, e.g., "--someflag=<int>"

function _flags_genOptStr ( )

Return valid getopt options using currently defined list of long options.

This function builds a proper getopt option string for short (and long) options, using the current list of long options for reference.

Args: _flags_optStr: integer: option string type (__FLAGS_OPTSTR_*) Output: string: generated option string for getopt Returns: boolean: success of operation (always returns True)

function _flags_getFlagDefault ( )

Returns flag default value based on a flag name.

Args: unnamed: string: underscored flag name unnamed: string: name of the output variable Output: sets the variable named by the second argument to the default value, which is an array in case of a multi-flag. Returns: integer: one of FLAGS_{TRUE|FALSE|ERROR}

function _flags_getFlagInfo ( )

Returns flag details based on a flag name and flag info.

Args: string: underscored flag name string: flag info (see the _flags_define function for valid info types) Output: string: value of dereferenced flag variable Returns: integer: one of FLAGS_{TRUE|FALSE|ERROR}

function _flags_getFlagValue ( )

Returns flag value based on a flag name.

Args: unnamed: string: underscored flag name unnamed: string: name of the output variable Output: sets the variable named by the second argument to the current value, which is an array in case of a multi-flag. Returns: integer: one of FLAGS_{TRUE|FALSE|ERROR}

function _flags_getoptEnhanced ( )

Parse command-line options using the enhanced getopt.

Note: the flag options are passed around in the global __flags_opts so that the formatting is not lost due to shell parsing and such.

Args: @: varies: command-line options to parse Returns: integer: a FLAGS success condition

function _flags_getoptStandard ( )

Parse command-line options using the standard getopt.

Note: the flag options are passed around in the global __flags_opts so that the formatting is not lost due to shell parsing and such.

Args: @: varies: command-line options to parse Returns: integer: a FLAGS success condition

function _flags_helpman_flagusage ( )

Output short usage of named flag in man page format.

Args: _flags_name_: string: long flag name Outputs: string: usage of flag, e.g., "--someflag=<int>"

function _flags_itemInList ( )

Check for presense of item in a list.

Passed a string (e.g. 'abc'), this function will determine if the string is present in the list of strings (e.g. ' foo bar abc ').

Args: _flags_str_: string: string to search for in a list of strings unnamed: list: list of strings Returns: boolean: true if item is in the list

function _flags_manText ( )

Escape string for use in man page output.

Args: unnamed: string: some string Output: string: man page-escaped string

function _flags_parseGetopt ( )

Dynamically parse a getopt result and set appropriate variables.

This function does the actual conversion of getopt output and runs it through the standard case structure for parsing. The case structure is actually quite dynamic to support any number of flags.

Args: argc: int: original command-line argument count @: varies: output from getopt parsing Returns: integer: a FLAGS success condition

function _flags_sortList ( )

Sort space separated list.

Args: @: list: space separated list of strings Output: list: sorted space separated list of strings

function _flags_typeStr ( )

Convert type ID to type string.

Args: _flags_type_: integer: type ID Outputs: string: type string

function _flags_underscoreName ( )

Underscore a flag or category name by replacing dashes and whitespaces with underscores.

Args: unnamed: string: long flag or category name Output: string: underscored name

function _flags_validateBoolean ( )

Validate a boolean.

Args: _flags__bool: boolean: value to validate Returns: bool: true if the value is a valid boolean

function _flags_validateFloat ( )

Validate a float.

Args: _flags__float: float: value to validate Returns: bool: true if the value is a valid float

function _flags_validateInteger ( )

Validate an integer.

Args: _flags__int_: interger: value to validate Returns: bool: true if the value is a valid integer

function _flags_validateUnsignedInteger ( )

Validate an unsigned integer.

Args: _flags__uint_: interger: value to validate Returns: bool: true if the value is a valid unsigned integer

function _flags_xmlText ( )

Escape string for use in XML output.

Args: unnamed: string: some string Output: string: xml-escaped string

function FLAGS ( )

Parse the flags.

Args: unnamed: list: command-line flags to parse Returns: integer: success of operation, or error

function flags_getoptInfo ( )

This is a helper function for determining the 'getopt' version for platforms where the detection isn't working. It simply outputs debug information that can be included in a bug report.

Args: none Output: debug info that can be included in a bug report Returns: nothing

function flags_getoptIsEnh ( )

Returns whether the detected getopt version is the enhanced version.

Args: none Output: none Returns: bool: true if getopt is the enhanced version

function flags_getoptIsStd ( )

Returns whether the detected getopt version is the standard version.

Args: none Returns: bool: true if getopt is the standard version

function flags_help ( )

This is effectively a 'help()' function. It prints a program description together with usage information and example command-lines on how to use the program. Note this function can be overridden so other apps can define their own help output, replacing this one, if they want.

Args: none Returns: integer: success of operation (always returns true)

function flags_helpflag ( )

Print help for named flag.

Args: flags_name_: string: long name of flag flags_maxNameLen: integer: (optional) maximum length of long flag names used to align help texts (default: 0) flags_showDefault: boolean: (optional) whether to display default value (default: true) Returns: integer: success of operation (always returns true)

function flags_helpflags ( )

Print help of all flags.

This function is used by flags_help() and flags_helpshort().

Args: flags_helpshort_: bool: display only short help of options, leaving out less important options Returns: integer: success of operation (always returns true)

function flags_helpflagxml ( )

This function outputs the help of named flag in XML format

Args: flags_name_: string: long name of flag indentation: integer: (optional) indentation Returns: integer: success of operation (always returns true)

function flags_helpman ( )

This function outputs the help in man page format.

Args: none Returns: integer: success of operation (always returns true)

function flags_helpman_contact ( )

Prints CONTACT section of man page.

function flags_helpman_copyright ( )

Prints COPYRIGHT section of man page.

function flags_helpman_description ( )

Prints DESCRIPTION section of man page.

function flags_helpman_flag ( )

Prints OPTIONS section entry of man page of named flag.

function flags_helpman_flags ( )

Prints OPTIONS section of man page.

function flags_helpman_name ( )

Prints NAME section of man page.

function flags_helpman_synopsis ( )

Prints SYNOPSIS section of man page.

function flags_helpshort ( )

This is effectively a 'usage()' function. It prints a usage information on how to use the program and the available flags. Note this function can be overridden so other apps can define their own short help output, replacing this one, if they want.

Args: none Returns: integer: success of operation (always returns true)

function flags_helpxml ( )

This function outputs the help in XML format.

Args: none Returns: integer: success of operation (always returns true)

function flags_reset ( )

Reset shflags back to an uninitialized state.

Args: none Returns: nothing

function flags_usage ( )

Prints usage as in synopsis section of man pages.

function flags_version ( )

This function outputs the version and copyright.

Args: none Returns: integer: success of operation (always returns true)

Functions

Detailed Description

Function Documentation