NAME
getopts - libbash library for command line parameters parsing
SYNOPSIS
$retval getopt_long 〈Instructions〉 〈Parameters〉
DESCRIPTION
This is a documentation for libbash getopts library, that implements
getopt_long function for bash(1). For documentation of bash getopts
function, please see getopts(1) ( getopts(1posix) on some systems).
Here is a table for reference:
getopts(1) (or 1posix on some systems) implemented by bash
getopts(3) implemented by libbash.
getopt(1) implemented by getopt utils (part of util-linux)
getopt_long(1) implemented by libbash and installed to section 1
instead of 3 to prevent collision with C man pages.
getopt(3) implemented by GNU C library.
getopt_long(3) implemented by GNU C library.
I have also seen separate getopt utility which part of util-linux
package.
The getopt_long function parses the command line arguments. It uses
Instructions as the rules for parsing the Parameters.
The Instructions
A string that specifies rules for parameters parsing. The instructions
string is built of a group of independent instructions, separated by a
white space. Each instruction must have the following structure:
-<SingleLetter>|--<MultiLetter>-><VariableName>[:]
This structure contains three parts:
-<SingleLetter>
This is the parameter single-letter sign. For example -h.
--<MultiLetter>
This is the parameter’s corresponding multi-letter sign. For
example --help.
<VariableName>[:]
This is the name of the variable that will contain the parameter
value. For example: HELP.
The Variable name can represent one of two variables types:
Flag variable (not followed by ‘:’)
In this case, it will hold the value 1 if ‘on’ (i.e. was
specified on command line) and will not be defined if ‘off’.
Value variable (followed by ‘:’)
In this case, the value it will hold is the string that was
given as the next parameter in the Parameters string
(Separated by white-space or ‘=’ ). If input contains more
then one instance of the considered command line option, an
array of the given parameters will be set as the value of the
variable.
The Parameters
The Parameters are simply the parameters you wish to parse.
RETURN VALUE
This function returns a string that contains a set of variables
definitions. In order to define the variables, this string should be
given as a parameter to eval function. This value is returned in the
variable $retval.
EXAMPLES
Parse command line parameters looking for the flags -h | --help and -v |
--version and for the value -p | --path :
getopt_long ’-h|--help->HELP
-v|--version->VERSION
-p|--path->PATH:’ $*
eval $retval
In this example, for the parameters --help --path=/usr/ the variables
that will be created are:
HELP=1
PATH=/usr/
for the parameters --help --path=/usr --path=/bin the variables that will
be created are:
HELP=1
PATH=(/usr /bin)
BUGS
Values must not contain the string ‘__getopts__’. This string will be
parsed as a single white-space.
A value should not start with an already defined multi-letter sign. If
such a value exists, it will be treated as the equivalent singe-letter
sign. This bug only accures when using a single-letter sign, or a multi-
letter sign that are not followed by a ‘=’.
For example: If we have a script named ‘foo’, and we parse the parameters
‘-d|--dir:’ and ‘-f|--file:’, then
foo -d --file
and
foo --dir --file
will not work
foo --dir=--file
will work.
AUTHORS
Hai Zaar 〈haizaar@haizaar.com〉
Gil Ran 〈gil@ran4.net〉
SEE ALSO
ldbash(1), getopt_long(1), getopts(1), getopt(1), libbash(1), getopt(3),
getopt_long(3)