[ prev :: next :: up ] libgg-current (3)

Generic configuration file/registry extraction routines

Name

ggParseOptions, ggSystemOptions : Generic configuration file/registry extraction routines

Synopsis

#include <ggi/gg.h>

int ggSystemOpts(char **rls, gg_option *optlist, int count);

char *ggParseOpts(const char *str, gg_option *optlist, int count, int flag);

Description

ggSystemOpts is a front-end for various utilities to retrieve configuration information from configuration files/registries/etc present in the operating system environment. What utility is used is determined by the first part of each of the strings in :p:'rls', which use a URL-like syntax. Currently the only supported utility "basicfile://" is one that extracts an option value from some of the more basic UNIX configuration file formats. Each string in :p:'rls' corresponds to the respective name/result pair in the aray :p:'optlist' (:p:`count` indicates how many options are being looked for.) The general form of the strings in :p:`rls` is "method://[rname]/[section]/[subsection]/config_optname", which looks for a variable named :p:`config_optname` in the subsection named :p:`subsection` of the section named :p:`section` of the resource (usually a file name) named :p:`rname` using the utility that corresponds to the :p:`method`.

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 616); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 616); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 616); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 616); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 616); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 616); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 616); backlink

Unknown interpreted text role "p".

In the above any character (other than '0') may be substituted for the slashes, to avoid conflict with resource, section, or variable names The section/subsection parts may be omitted or more subsections added as needed. If a blank section is given before the :p:`config_optname` then all sections on the most specific level will be searched (For example, to search for an option named "useaccel" without respect to section globally in a file, one would specify "basicfile:||/path/to/file||useaccel" in the :p:'rls' string.)

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 632); backlink

Unknown interpreted text role "p".

ggParseOpts parses a string :p:`str` of options in LibGG's option format and places the results in the ".name" members of the :p:`optlist`. The parameter :p:`count` specifies the length of optlist. The parameter :p:`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 ggParseOpts 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).

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 642); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 642); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 642); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 642); backlink

Unknown interpreted text role "p".

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 :p:`optlist` and the GG_PARSEOPTS_ALLOW_UNKNOWN flag is not used.

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 670); backlink

Unknown interpreted text role "p".

Unnamed options do not (duh) have a name field and are positionally mapped to entries in :p:`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.

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 678); backlink

Unknown interpreted text role "p".

Options that are eligible to be used in an unnamed fashion must have a colon or dash prefixed to their optname in the :p:`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 :p:`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.

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 686); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 686); backlink

Unknown interpreted text role "p".

Options that appear in boolen 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 :p:`optlist`.

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 700); backlink

Unknown interpreted text role "p".

Option names and values in :p:`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.

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 702); backlink

Unknown interpreted text role "p".

Return value

ggSystemOpts returns 0 on success and a negative error code on failure.

ggParseOpts returns the position in :p:`str` after the last character of a valid option string, or NULL if :p:`str` was determined not to be a valid option string. Even on failure, the contents of :p:`optlist` may have been altered.

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 712); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 712); backlink

Unknown interpreted text role "p".

System Message: ERROR/3 (../ggi-core/libgii/doc/libgg.txt, line 712); backlink

Unknown interpreted text role "p".
 
[ prev :: next :: up ] libgg-current (3)
2008/05/04 23:14:55