NAME¶
ggParseOptions - Option parsing
SYNOPSIS¶
#include <ggi/gg.h>
char *ggParseOptions(const char *str, gg_option *optlist, int count, int flag);
DESCRIPTION¶
ggParseOptions parses a string
str of options in LibGG's option
format and places the results in the ".name" members of the
optlist. The parameter
count specifies the length of optlist.
The parameter
flags is a bitwise or of values that alter behavior, the
only one defined at this time being GG_PARSEOPTS_ALLOW_UNKNOWN, which, if
present, will cause ggParseOptions to ignore options found in the string for
which there are no matching entries in optlist (normally this generates a
failure and a warning message).
The normal LibGG option format is defined as follows:
A colon or whitespace is the separator between options.
Option names consist of any character except parenthesis, colons, whitespace
characters, the equals sign ('=') and the NULL ('0') character.
Option values may consist of any character except the NULL character, however in
order to include colons, whitespace characters, or parenthesis, the option
must be quoted. Option values that begin with a single or double quote are
considered to be quoted, and must end with the same quote character with which
they began. The quotes are not considered to be part of the option value. In
order to include the quote character in use in a quoted option value it must
be escaped by a backslash ('') character. Backslashes always escape, even in
unquoted values, and so must always be escaped with a backslash in order to be
included.
Named options begin with a dash (
-) character followed by an option name
and may be boolean (present or not) or may contain an equal sign to assign the
option a string value (everything following the equal sign up to the next
forbidden character as described above.) Matching is case sensitive, but
options can be abbreviated right down to a single letter as long as the name
remains unique among the entries in
optlist and the
GG_PARSEOPTS_ALLOW_UNKNOWN flag is not used.
Unnamed options do not (duh) have a name field and are positionally mapped to
entries in
optlist. Unnamed options are processed after the first
option field not starting with a dash is encountered, and occupy the rest of
the option string. They are assigned to any unnamed-eligible options (see
below) in the order they appear in optlist, but if any were previously
discovered in named form they forfeit their position in that order.
Options that are eligible to be used in an unnamed fashion must have a colon or
dash prefixed to their optname in the
optlist when
ggParseOptions is invoked. Unnamed options may appear as named options
as well.
ggParseOptions will alter the first character in the
corresponding optname entry in
optlist to a colon or to a dash
depending on whether the option was present in unnamed or named form,
respectively. Thus the caller can determine whether the option was presented
in named or unnamed form.
Options that appear in boolean form will have the first character in their
result changed to "y". This can be distinguished from an explicit
value of "y" because no NULL terminator is appended to the
"y".
Options that are not found are left unaltered in
optlist.
Option names and values in
str are limited in length to
GG_MAX_OPTION_NAME and GG_MAX_OPTION_RESULT bytes, respectively, including one
byte for a terminating NULL character.
RETURN VALUE¶
ggParseOptions returns the position in
str after the last
character of a valid option string, or
NULL if
str was
determined not to be a valid option string. Even on failure, the contents of
optlist may have been altered.