shflags.sh File Reference

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

Go to the source code of this file.

Functions
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_SOURCE} || exit 1

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.

Definition in file shflags.sh.

Function Documentation

FLAGS()

function FLAGS

(

)

Parse the flags.

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

Returns

Nothing.

flags_getoptInfo()

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

Returns

Nothing.

flags_getoptIsEnh()

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

Returns

Nothing.

flags_getoptIsStd()

function flags_getoptIsStd

(

)

Returns whether the detected getopt version is the standard version.

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

Returns

Nothing.

flags_help()

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)

Returns

Nothing.

flags_helpflag()

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)

Returns

Nothing.

flags_helpflags()

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)

Returns

Nothing.

flags_helpflagxml()

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)

Returns

Nothing.

flags_helpman()

function flags_helpman

(

)

This function outputs the help in man page format.

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

Returns

Nothing.

flags_helpman_contact()

function flags_helpman_contact

(

)

Prints CONTACT section of man page.

Returns

Nothing.

flags_helpman_copyright()

function flags_helpman_copyright

(

)

Prints COPYRIGHT section of man page.

Returns

Nothing.

flags_helpman_description()

function flags_helpman_description

(

)

Prints DESCRIPTION section of man page.

Returns

Nothing.

flags_helpman_flag()

function flags_helpman_flag

(

)

Prints OPTIONS section entry of man page of named flag.

Returns

Nothing.

flags_helpman_flags()

function flags_helpman_flags

(

)

Prints OPTIONS section of man page.

Returns

Nothing.

flags_helpman_name()

function flags_helpman_name

(

)

Prints NAME section of man page.

Returns

Nothing.

flags_helpman_synopsis()

function flags_helpman_synopsis

(

)

Prints SYNOPSIS section of man page.

Returns

Nothing.

flags_helpshort()

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)

Returns

Nothing.

flags_helpxml()

function flags_helpxml

(

)

This function outputs the help in XML format.

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

Returns

Nothing.

flags_reset()

function flags_reset

(

)

Reset shflags back to an uninitialized state.

Args: none Returns: nothing

Returns

Nothing.

flags_usage()

function flags_usage

(

)

Prints usage as in synopsis section of man pages.

Returns

Nothing.

flags_version()

function flags_version

(

)

This function outputs the version and copyright.

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

Returns

Nothing.