The getopts module interprets UNIX command line syntax. It allows
both standard POSIX one-character options and GNU-style long options,
in addition to command line arguments. The implementation shares
similarities with POSIX getopt() and GNU's getopt_long(). It has
additional abilities, at the cost of enforcing a specific style.
In addition to setting options from the command line, options may also be configured so they can be set by environment variables, or by one or more configuration files.
Option arguments can be automatically checked for valid type
(integers, real numbers, characters, or strings). Numeric arguments
can also be checked for valid range (for instance, ensuring that a
probability is in the range
Options can be linked into "toggle groups", such that setting one option automatically unsets others.
You can specify that an option isn't legal unless other required options are also set, or conversely that an option is incompatible with one or more other options.
A standardized usage/help display for command line options can be printed directly from the internal information, including default values and range restrictions when line length allows.
This is all configured by defining an array of ESL_OPTIONS
structures that provide the necessary information. This array is
turned into a ESL_GETOPTS object, which is used to determine
and store the configuration state of your application according to the
command line, environment variables, and configuration files.
The ESL_GETOPTS object can be queried directly when your program
executes configuration-dependent steps. There is often no need to
store configuration information in other variables in your
program. This simplifies code structure, by allowing you to pass the
complete configuration state of your application in one capsule to
functions other than main(). This is especially useful in
applications where main() is a dispatch wrapper, such as the masters
and workers in a parallelized MPI program, for example.
The module implements a ESL_GETOPTS object that holds the
configuration state of the application, and an ESL_OPTIONS structure
that contains information about one configurable option. An
application defines an array of ESL_OPTIONS to declare what options
it will allow.
#include <stdio.h>
#include "easel.h"
#include "esl_getopts.h"
static ESL_OPTIONS options[] = {
/* name type def env range toggles reqs incomp help docgroup*/
{ "-h", eslARG_NONE, FALSE, NULL, NULL, NULL, NULL, NULL, "show help and usage", 0},
{ "-a", eslARG_NONE, FALSE, NULL, NULL, NULL, NULL, NULL, "a boolean switch", 0},
{ "-b", eslARG_NONE,"default", NULL, NULL, NULL, NULL, NULL, "another boolean switch", 0},
{ "-n", eslARG_INT, "0", NULL, NULL, NULL, NULL, NULL, "an integer argument", 0},
{ "-s", eslARG_STRING, "hi!", NULL, NULL, NULL, NULL, NULL, "a string argument", 0},
{ "-x", eslARG_REAL, "1.0", NULL, NULL, NULL, NULL, NULL, "a real-valued argument", 0},
{ "--file", eslARG_STRING, NULL, NULL, NULL, NULL, NULL, NULL, "long option, filename arg", 0},
{ "--char", eslARG_CHAR, "", NULL, NULL, NULL, NULL, NULL, "long option, char arg", 0},
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
};
static char usage[] = "Usage: ./example [-options] <arg>";
int
main(int argc, char **argv)
{
ESL_GETOPTS *go;
char *arg;
if ((go = esl_getopts_Create(options)) == NULL) esl_fatal("Bad options structure\n");
if (esl_opt_ProcessCmdline(go, argc, argv) != eslOK) esl_fatal("Failed to parse command line: %s\n", go->errbuf);
if (esl_opt_VerifyConfig(go) != eslOK) esl_fatal("Failed to parse command line: %s\n", go->errbuf);
if (esl_opt_GetBoolean(go, "-h") == TRUE) {
printf("%s\n where options are:", usage);
esl_opt_DisplayHelp(stdout, go, 0, 2, 80); /* 0=all docgroups; 2=indentation; 80=width */
return 0;
}
if (esl_opt_ArgNumber(go) != 1) esl_fatal("Incorrect number of command line arguments.\n%s\n", usage);
arg = esl_opt_GetArg(go, 1);
printf("Option -a: %s\n", esl_opt_GetBoolean(go, "-a") ? "on" : "off");
printf("Option -b: %s\n", esl_opt_GetBoolean(go, "-b") ? "on" : "off");
printf("Option -n: %d\n", esl_opt_GetInteger(go, "-n"));
printf("Option -s: %s\n", esl_opt_GetString( go, "-s"));
printf("Option -x: %f\n", esl_opt_GetReal( go, "-x"));
if (esl_opt_IsUsed(go, "--file")) printf("Option --file: %s\n", esl_opt_GetString(go, "--file"));
else printf("Option --file: (not set)\n");
printf("Option --char: %c\n", esl_opt_GetChar(go, "--char"));
printf("Cmdline arg: %s\n", arg);
esl_getopts_Destroy(go);
return 0;
}
The code above shows an example of using five short options (including
help) and two long options, without any of getopts' optional
validation or configuration mechanisms (hence all the NULL in the
env through incomp fields of the ESL_OPTIONS array). The steps
are:
-
The application defines an array of
ESL_OPTIONSstructures, one per option. Name, type, and default value fields are required. The other fields are optional (though the help string shouldn't be leftNULLunless you're being lazy). The array is terminated by an entry of all 0's. -
An application typically defines a helpful "usage" string, which it prints out as part of help messages or error messages. The
getoptsmodule doesn't need this, though, so you're free to format your messages however you like. -
A
ESL_GETOPTSobject is created, using the options array. At this point, all options are initialized to default values inside the object. -
The application now processes option settings from the command line, environment variables, and one or more configuration files. The application can do this in any precedence order it chooses. In the example, only the command line is processed.
-
The call to
esl_opt_VerifyConfig(go)validates the configuration, before you attempt to retrieve any information from it. -
Many of my applications (including Easel applications) typically look for a
-hoption immediately, to print a short help page. This isn't required bygetopts. -
The application will typically retrieve, validate, and store its non-optional command line arguments in order and one at a time using
esl_opt_GetArg()calls early in the program. -
The application may then go off and do its thing, using
_Get*()calls (and_IsUsed()and_IsDefault()calls) to retrieve option information when needed. -
On exit, the
ESL\_GETOPTSobject is destroyed (free'd). This object is the only place where memory is allocated. Any string retrieved as an option or argument, for example, is only a pointer to internal memory maintained by the object. This makes it dangerous to free the object until you know you're not accessing any pointers it's returned to you, unless you've made copies.
An example of running this program:
% ./getopts_example -ax 0.3 -n 42 --file foo --char x baz
Option -a: on
Option -b: on
Option -n: 42
Option -s: hi!
Option -x: 0.300000
Option --file: foo
Option --char: x
Cmdline arg: baz
Note that because we set the default value of -b to TRUE in
this example, it is always on whether we use the -b option or
not.
Since you define your options in a static array of
ESL_OPTIONS structures, you need to know what an
ESL_OPTIONS structure contains. The ESL_OPTIONS
structure is declared in getopts.h as:
typedef struct {
char *name; /* either short "-a" or long "--foo" style */
int type; /* arg type, for type checking: (eslARG_INT, etc.) */
char *defval; /* default setting, or NULL ("default" is a C keyword) */
char *envvar; /* associated environ var ("BLASTDB"), or NULL */
char *range; /* for range checking arg: ("0<=x<=1", etc.) */
char *toggle_opts; /* comma-sep'd optlist: turn these off if this opt is on */
char *required_opts; /* comma-sep'd optlist: these must also be set */
char *incompat_opts; /* comma-sep'd optlist: these must not be set */
char *help; /* help/usage string */
int docgrouptag; /* integer tag for documentation groups */
} ESL_OPTIONS;
Each of these fields in the options array is described in detail below:
All options must start with -. Options that start with one - are
short options. Options that start with -- are
long options.
Short option names must be a single alphanumeric character: -n
or -1, for example. Short options can be concatenated on the
command line: -abc is the same as -a -b -c.
Long option names should contain only alphanumeric characters, -, or
_: --foo or --foo-tastic, for example. They must not contain
space, tab, newline, =, or , characters, because these will
definitely confuse the option argument parsers. Other characters might
happen to work, but nonetheless should not be used.
Long options can be abbreviated (unambiguously) on the command line:
if --foobar is an option, --f works too, so long as no other long
option starts with the same prefix --f.
You should avoid using option names that look like negative numbers if
any of your other options would accept that value as a valid argument,
so that Easel can robustly detect when a user forgets an option
argument on the command line. For example, if -n takes an integer
argument and -1 is an option, and a user types -n -1 on a
commandline, the -1 will be parsed as -n's option, even if the
user meant the -1 as an option and had forgotten to add an argument
for -n.
Seven argument types are recognized:
| flag | description | arg abbrv | type checking |
|---|---|---|---|
eslARG_NONE |
Boolean switch (on/off) | n/a | n/a |
eslARG_INT |
integer | <n> |
convertible by atoi() |
eslARG_REAL |
float or double | <x> |
convertible by atof() |
eslARG_CHAR |
one character | <c> |
single ASCII char |
eslARG_STRING |
any string | <s> |
not checked |
eslARG_INFILE |
an input filename | <f> |
not checked |
eslARG_OUTFILE |
an output filename | <f> |
not checked |
All arguments are declared, configured, and stored internally as
strings in a ESL_GETOPTS object. For arguments that are declared to
be of types eslARG_INT, eslARG_REAL, or eslARG_CHAR, the string
is checked to be sure it can be completely converted to the declared
type.
Strings are of type eslARG_STRING, and since any string is valid
(including a NULL pointer), this type is not checked. An application
can also declare an argument to be of type eslARG_STRING if for some
reason it wants to bypass type checking. The application would recover
the option argument with esl_opt_GetString() and then deal with any
type conversion itself.
Input and output filenames can be declared as eslARG_INFILE and
eslARG_OUTFILE, respectively. Currently both are unchecked types
that are treated the same as a eslARG_STRING, except that their
arguments are indicated as <f> instead of <s> in help output. In
the future, it might be useful to automatically check that input files
exist and can be read, and that output files can be written.
Since the ESL_GETOPTS object stores all values internally as
strings, default settings in the options array are also all provided
as strings.
For any type of option, NULL, FALSE, or 0 are all
interpreted as the option being unset (OFF). Any non-NULL string value
is interpreted as the option being set (ON).
For boolean defaults, any non-NULL string is interpreted as TRUE,
and the option is ON. For a boolean option that is ON by default, the
only place where the string value matters is in formatting option
help, where this string will be displayed as the default
setting. Therefore, strings like "default", "on", or "true"
would be typical, to make the help string look right.
Note that the syntax here is a little weird. The quotes around
"true" and the absence of quotes around FALSE are
important. FALSE, NULL, and 0 are all identical in the internal
representation (they evaluate to a null pointer).
Integer, real-valued, and character arguments must be provided as
strings: "42" not 42, "1.0" not 1.0, and "x" not 'x'. String
arguments can be set to any string.
Sometimes it's natural to define your default parameter values as
macros; for example #define eslFOO_DEFAULT 42. The problem is that
your macro value is a number, but getopts needs a string constant. To
use eslFOO_DEFAULT in an ESL_OPTIONS array, use
ESL_STR(eslFOO_DEFAULT). The ESL_STR() macro uses a C preprocessor
trick that evaluates to a string constant containing the value of the
macro constant. The ESL_STR() trick only works for integer- and
real-valued option arguments, not for booleans; we don't currently
have a good way to define boolean defaults with macros that get
automatically used in the OPTIONS array.
Sometimes you want to have an option that is off by default, but can
be optionally set to a value. That is, you may want to combine a
boolean switch and a integer-, real-, char-, or string-valued
option. To do this, make the default value NULL, which means
"unset", and when your code checks for the value of such an option,
first use esl_opt_IsOn() to check if it's been set, and if so,
esl_opt_Get*() the value.
There is no way to turn a boolean option off by a command line option,
environment variable, or configuration file if its default setting is
ON. Booleans (and strings, for that matter) can only be turned on when
their option is selected. Booleans can be set to off by default, or
toggled off indirectly by another option is turned on (see the section
on toggle groups further below). If you need to turn a boolean off,
say -b, you can provide a counteroption (--no-b), and toggle-tie
them together (see below).
When an option is connected to an environment variable, setting the environment variable has the same result as setting the option on the command line.
To check and process environment variables, your application needs to
call esl_opt_ProcessEnvironment().
Boolean options are set by setting the environment variable with any argument, for instance (in a bash shell),
% export FOO_DEBUGGING=1
and other options are set by setting the environment variable to the appropriate argument, for instance (in a bash shell),
% export FOO_DEBUG_LEVEL=5
For example, if we connected the option name --debug to
environment variable "FOO_DEBUGGING" and option
--debuglevel to environment variable "FOO_DEBUG_LEVEL"
in an application myapp, then
% myapp --debug --debuglevel 5
is the same as
% export FOO_DEBUGGING=1
% export FOO_DEBUG_LEVEL=5
% myapp
An advantage of using environment variables is that if you want to
configure some optional behavior more or less permanently, you can
save yourself a lot of command line typing by setting that
configuration in the environment (in your .cshrc or
.bashrc, for example).
If a non-NULL range is provided, a configured argument (including the specified default setting) will be checked to be sure it satisfies a lower bound, upper bound, or both. Range checking only applies to integer, real, and char arguments. Boolean and string arguments should set their range fields to NULL.
In a range string, a character n, x, or c is used to represent
an integer, real, or char argument, respectively. Bounds may either be
exclusive ("n>=0", "x>1.0", and
"c>=A". Examples of range strings specifying upper bounds are
"n<0", "x<=100.0", and "c<=Z". Examples of range strings
specifying both lower and upper bounds are "0<n<=100", "0<=x<=1",
and "a<=c<=z".
Char ranges are determined using ASCII coding.
Range checking occurs before any option is set.
If a non-NULL string toggle_opts of "toggle-tied" options is set for
option X, this is a comma-delimited list of options that are turned
off when option X is turned on. This allows the application to define
a group of options for which only one may be on. The application would
set an appropriate one to be on by default, and the others to be off
by default.
For example, if you configure an option -a to have a
toggle_opts of "-b,-c", then whenever -a is
turned on, both -b and -c are automatically turned
off.
But this only defines the behavior when -a is selected. To
get all three options to behave as a toggle group, you'd also want to
set toggle_opts for -b to "-a,-c", and
toggle_opts for -c to "-a,-b". This is a
little redundant and messy; it's the result of the line-oriented,
one-option-at-a-time definition of the ESL_OPTIONS. These
lists can get quite long, too.
An option has no effect on itself when it appears in its own
toggle-tied list. This lets you reduce the mess a bit. You can
#define a toggle group string:
#define OPTGROUP1 "--option1,--option2,--option3,--option4"
and use that #define macro in the ESL_OPTIONS.
Although booleans may only be turned ON when their option is present,
you can easily get the semantics of an on/off switch by defining
another option that works as the off switch when it is selected. For
example, you could define (GNU-ish) boolean options --foo and
--no-foo, and set toggle_opts for --foo to be
"--no-foo" and vice versa.
Toggle-tying should only be used for boolean options, but it will also work for string options (where turning a string option off means setting it to NULL). Toggle-tying an integer, real-valued, or char option will result in undefined behavior, because these options can't be turned off once set.
Toggling behavior occurs immediately, whenever an option with a
non-NULL toggle_opts field is set.
If a non-NULL string required_opts is provided for option X,
this specifies a comma-delimited list of additional options that must
also be on if option X is set.
One case where this behavior is useful is when one (primary) option
turns on a mode of application behavior, and other (secondary) options
configure that mode. If a user tried to set the secondary options
without turning on the mode in the first place, the application should
issue a warning. So, if a mode was turned on by --foomode and
configured by --foolevel <x>, one could set
required_opts to "--foomode" for the option
--foolevel.
Required options are validated when the application calls `esl_opt_VerifyConfig()}, (presumably) after all configuration information has been processed. This delayed verification allows the primary options to be set anywhere and in any order, before or after secondary options are set.
The incompat_opts field is the converse of
required_opts.It specifies a comma-delimited list of options
that may not also be on if option X is on.
The test driver in getopts.c uses an options array that
exercises all the optional features at least once:
#define BGROUP "-b,--no-b"
static ESL_OPTIONS options[] = {
/* name type default env_var range toggles req incompat help docgroup */
{ "-a", eslARG_NONE, FALSE,"FOOTEST",NULL, NULL, NULL, NULL, "toggle a on", 1 },
{ "-b", eslARG_NONE, FALSE, NULL, NULL, BGROUP, NULL, NULL, "toggle b on", 1 },
{ "--no-b", eslARG_NONE,"TRUE", NULL, NULL, BGROUP, NULL, NULL, "toggle b off", 1 },
{ "-c", eslARG_CHAR, "x", NULL,"a<=c<=z",NULL, NULL, NULL, "character arg", 2 },
{ "--d1", eslARG_NONE,"TRUE", NULL, NULL, "--d2", NULL, NULL, "toggle d1 on, d2 off", 2 },
{ "--d2", eslARG_NONE, FALSE, NULL, NULL, "--d1", NULL, NULL, "toggle d2 on, d1 off", 2 },
{ "-n", eslARG_INT, "0", NULL,"0<=n<10",NULL, NULL, NULL, "integer arg", 2 },
{ "-x", eslARG_REAL, "0.8", NULL, "0<x<1", NULL, NULL, NULL, "real-value arg", 2 },
{ "--lowx", eslARG_REAL, "1.0", NULL, "x>0", NULL, NULL, NULL, "real arg with lower bound", 2 },
{ "--hix", eslARG_REAL, "0.9", NULL, "x<1", NULL, NULL, NULL, "real arg with upper bound", 2 },
{ "--lown", eslARG_INT, "42", NULL, "n>0", NULL,"-a,-b", NULL, "int arg with lower bound", 2 },
{ "--hin", eslARG_INT, "-1", NULL, "n<0", NULL, NULL,"--no-b","int arg with upper bound", 2 },
{ "--host", eslARG_STRING, "","HOSTTEST",NULL, NULL, NULL, NULL, "string arg with env var", 3 },
{ "--multi",eslARG_STRING,NULL, NULL, NULL, NULL, NULL, NULL, "test quoted configfile arg",3 },
{ "--mul", eslARG_NONE, FALSE, NULL, NULL, NULL, NULL, NULL, "test long opt abbreviation",3 }, /* xref bug #e4 */
{ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
};
The esl_opt_DisplayHelp() function streamlines the job of printing a
brief help message, reminding the user of the command line options. It
uses the help string to produce output like (from the example code
above):
% ./example -h
Usage: ./example [-options] <arg>
where options are:
-h : show help and usage
-a : a boolean switch
-b : another boolean switch [default]
-n <n> : an integer argument [0]
-x <x> : a real-valued argument [1.0]
--file <s> : long option, with filename arg
--char <c> : long option, with character arg
One line is printed for each option, in the same order that they
appear in the ESL_OPTIONS array. The line is constructed from
the mandatory option name, the mandatory argument type, and the
optional help string.
If there is room on the lines, default values are shown in brackets
(when they are on or non-NULL). This display is all or none;
if any line is too long, no default values are displayed.
If there is still room on the lines, range restrictions are shown in parentheses. Like the default values, this display is also all or none.
The amount of space on the line (in characters) is specified by the
textwidth argument to esl_opt_DisplayHelp(), which
might typically be 80. If any line is too long even without printing a
default value and range restriction, an error is thrown; you need to
either shorten the help string or increase the specified
textwidth. (This is not a memory allocation
issue. textwidth is provided as a tool to help you keep all
your text within the bounds of a user's terminal window, and warn you
when you're going to wrap or truncate lines.)
You can indent all the lines by some number of spaces using the
indent argument, which was set to 2 in the example above.
The base behavior of esl_opt_DisplayHelp() is to show all
the options in one list. You might want to have separate lists. For
example, you might want to consider some options as "expert"
options, and only show help for those when a user really asks for it.
Or you might simply want to group your options into sections, with
different headers. This is what the docgrouptag field is for
in the ESL_OPTIONS structure. If you pass
esl_opt_DisplayHelp() a nonzero value for docgroup,
it will only show help lines for options that have a matching
docgrouptag. If you had some options with a
docgrouptag of 1, and some more options with a
docgrouptag of 2, you could format them into two help sections
with this:
if (show_help) {
puts(usage);
puts("\n where some options are:");
esl_opt_DisplayHelp(stdout, go, 1, 2, 80); /* 1=docgroup 1; 2=indentation; 80=width */
puts("\n and some more options are:");
esl_opt_DisplayHelp(stdout, go, 2, 2, 80); /* 1=docgroup 2; 2=indentation; 80=width */
return 0;
}
which, if you modified the above example in this way (setting the
first three options to have a docgrouptag of 1 and the other
four to be 2) would give you:
./example -h
Usage: ./example [-options] <arg>
where some options are:
-h : show help and usage
-a : a boolean switch
-b : another boolean switch [default]
and some more options are:
-n <n> : an integer argument [0]
-x <x> : a real-valued argument [1.0]
--file <s> : long option, with filename arg
--char <c> : long option, with character arg
Once a ESL_GETOPTS object has been loaded with an options
array and initialized to default state by
esl_getopts_Create(), a esl_opt_ProcessCmdline()
call then processes all the options on the command line, updating the
configuration.
Internally, the object keeps track of where the options end and
command line arguments begin. The macro esl_opt_ArgNumber()
returns the number of arguments remaining after the options. Calls to
esl_opt_GetArg() recover the command line arguments by
number.
The getopts module can configure options not only via the command
line, but via environment and/or config files. Connections to the
environment -- the env_var field of the options array -- are
processed by a esl_opt_ProcessEnvironment() call. An open
config file is processed by a esl_opt_ProcessConfigfile()
call. (The format of a config file is described below.) The
application may process any number of config files -- for instance,
there may be a master configuration installed in a system directory,
and a personalized configuration in a user's home directory.
The order of the different Process*() calls defines the
precedence of who overrides who. For example, in the following code
fragment:
ESL_GETOPTS *g; /* a created, initialized getopts config */
FILE *masterfp; /* a master config file, open for reading */
FILE *userfp; /* a user's config file, open for reading */
esl_opt_ProcessConfigfile(g, "/usr/share/myapp/master.cfg", masterfp);
esl_opt_ProcessConfigfile(g, "~/.myapp.cfg", userfp);
esl_opt_ProcessEnvironment(g);
esl_opt_ProcessCmdline(g, argc, argv);
the precedence is defined as: defaults, master config file, local config file, environment, command line arguments.
(This section might usefully by cut and pasted into the documentation for a specific application, with modifications as appropriate.)
Command line syntax is essentially identical to the syntax used by GNU programs. Options must precede the mandatory arguments.
Options are either short or long. Short options are a single character
preceded by a single -; for example, -a. Long options
are preceded by two dashes, and can have any wordlength; for example,
--option1.
If a short option takes an argument, the argument may either be
attached (immediately follows the option character) or unattached (a
space between the optchar and the argument. For example, -n5
and -n 5 both specify an argument 5 to option
-n.
Short options can be concatenated into a string of characters;
-abc is equivalent to -a -b -c. (Concatenation may
only be used on the command line, not in configuration files or in
fields of the ESL_OPTIONS structure array.) Only the last
option in such a string can take an argument, and the other options in
the optstring must be simple on/off booleans. For example, if
-a and -b are boolean switches, and -W takes a
<string> argument, either -abW foo or -abWfoo
is correct, but -aWb foo is not.
For a long option that takes an argument, the argument can be provided
either by --foo arg or --foo=arg.
Long options may be abbreviated, if the abbreviation is unambiguous;
for instance, --foo or --foob suffice to active an
option --foobar. Like concatenation of short options,
abbreviation of long options is a shorthand that may only be used on
the command line.
Multi-word arguments may be quoted: for example, --hostname "my host" or -s="my string".
Nonnumeric arguments may not start with '-' unless you use an
argument-attached syntax: -W=-myarg and --foo=-myarg
are accepted, but -W -myarg or --foo -myarg will result
in an error message. This is so if you forget a required argument on
the command line, we don't silently parse the following option as that
argument. Numeric arguments aren't checked this way, but forgotten
numeric argument errors would still usually be caught in typechecking
(if -n takes an integer argument, -n -a would be an
invalid argument error); stylistically, we want -n -1 and
--param -1 to be a valid way of passing negative-valued
arguments. However, this does mean that some forgotten numeric
argument cases will be undetectable by Easel: in the case where
-n takes an integer argument, -1 is a valid option,
and the user types -n -1, the -1 is parsed as
-n's option.
Each line of a configuration file contains an option and an argument
(if the option takes an argument). Blank lines are ignored. Anything
following a # character on a line is a comment and is
ignored. The syntax of options and arguments is stricter than on
command lines. Concatenation of short options is not allowed,
abbreviation of long options is not allowed, and arguments must always
be separated from options by whitespace (not by =). For
example:
# Customized configuration file for my application.
#
-a # Turn -a on.
-b # Turn -b on.
-W arg # Set -W to "arg"
--multi "one two three" # Multiword args can be quoted.
| Function | Synopsis |
|---|---|
| esl_getopts_Create() | Create a new ESL_GETOPTS object. |
| esl_getopts_CreateDefaultApp() | Initialize a standard Easel application. |
| esl_getopts_Reuse() | Reset application state to default. |
| esl_getopts_Destroy() | Destroys an ESL_GETOPTS object. |
| esl_getopts_Dump() | Dumps a summary of a ESL_GETOPTS configuration. |
| esl_opt_ProcessConfigfile() | Parses options in a config file. |
| esl_opt_ProcessEnvironment() | Parses options in the environment. |
| esl_opt_ProcessCmdline() | Parses options from the command line. |
| esl_opt_ProcessSpoof() | Parses a string as if it were a command line. |
| esl_opt_VerifyConfig() | Validates configuration after options are set. |
| esl_opt_ArgNumber() | Returns number of command line arguments. |
| esl_opt_SpoofCmdline() | Create faux command line from current option configuration. |
| esl_opt_IsDefault() | Returns TRUE if option remained at default setting. |
| esl_opt_IsOn() | Returns TRUE if option is set to a non-NULL value. |
| esl_opt_IsUsed() | Returns TRUE if option is on, and this is not the default. |
| esl_opt_GetSetter() | Returns code for who set this option. |
| esl_opt_GetBoolean() | Retrieve TRUE/FALSE for a boolean option. |
| esl_opt_GetInteger() | Retrieve value of an integer option. |
| esl_opt_GetChar() | Retrieve value of a character option. |
| esl_opt_GetString() | Retrieve value of a string option. |
| esl_opt_GetArg() | Retrieve numbered command line argument. |
| esl_opt_DisplayHelp() | Formats one-line help for each option. |