1ggParseOptions(3) GGI ggParseOptions(3)
2
6 ggParseOptions : Option parsing
7
9 #include <ggi/gg.h>
10 char *ggParseOptions(const char *str, gg_option *optlist, int count, int flag);
12
15 ggParseOptions parses a string str of options in LibGG's option format
16 and places the results in the ".name" members of the optlist. The
17 parameter count specifies the length of optlist. The parameter flags
18 is a bitwise or of values that alter behavior, the only one defined at
19 this time being GG_PARSEOPTS_ALLOW_UNKNOWN, which, if present, will
20 cause ggParseOptions to ignore options found in the string for which
21 there are no matching entries in optlist (normally this generates a
22 failure and a warning message).
23 The normal LibGG option format is defined as follows:
25 A colon or whitespace is the separator between options.
27 Option names consist of any character except parenthesis, colons,
29 whitespace characters, the equals sign ('=') and the NULL ('0') charac‐
30 ter.
31 Option values may consist of any character except the NULL character,
33 however in order to include colons, whitespace characters, or parenthe‐
34 sis, the option must be quoted. Option values that begin with a single
35 or double quote are considered to be quoted, and must end with the same
36 quote character with which they began. The quotes are not considered
37 to be part of the option value. In order to include the quote charac‐
38 ter in use in a quoted option value it must be escaped by a backslash
39 ('') character. Backslashes always escape, even in unquoted values,
40 and so must always be escaped with a backslash in order to be included.
41 Named options begin with a dash (-) character followed by an option
43 name and may be boolean (present or not) or may contain an equal sign
44 to assign the option a string value (everything following the equal
45 sign up to the next forbidden character as described above.) Matching
46 is case sensitive, but options can be abbreviated right down to a sin‐
47 gle letter as long as the name remains unique among the entries in
48 optlist and the GG_PARSEOPTS_ALLOW_UNKNOWN flag is not used.
49 Unnamed options do not (duh) have a name field and are positionally
51 mapped to entries in optlist. Unnamed options are processed after the
52 first option field not starting with a dash is encountered, and occupy
53 the rest of the option string. They are assigned to any unnamed-eligi‐
54 ble options (see below) in the order they appear in optlist, but if any
55 were previously discovered in named form they forfeit their position in
56 that order.
57 Options that are eligible to be used in an unnamed fashion must have a
59 colon or dash prefixed to their optname in the optlist when ggParseOp‐
60 tions is invoked. Unnamed options may appear as named options as well.
61 ggParseOptions will alter the first character in the corresponding opt‐
62 name entry in optlist to a colon or to a dash depending on whether the
63 option was present in unnamed or named form, respectively. Thus the
64 caller can determine whether the option was presented in named or
65 unnamed form.
66 Options that appear in boolean form will have the first character in
68 their result changed to "y". This can be distinguished from an
69 explicit value of "y" because no NULL terminator is appended to the
70 "y".
71 Options that are not found are left unaltered in optlist.
73 Option names and values in str are limited in length to
75 GG_MAX_OPTION_NAME and GG_MAX_OPTION_RESULT bytes, respectively,
76 including one byte for a terminating NULL character.
77
79 ggParseOptions returns the position in str after the last character of
80 a valid option string, or NULL if str was determined not to be a valid
81 option string. Even on failure, the contents of optlist may have been
82 altered.
83libgg-1.0.x 2005-08-26 ggParseOptions(3)