1ggLoadConfig(3) GGI ggLoadConfig(3)
2
6 ggLoadConfig, ggFreeConfig, ggConfigIterTarget, ggConfigIterLocation :
7 Configuration helpers
8
10 int ggLoadConfig(const char *file, gg_config *config);
11 void ggFreeConfig(gg_config config);
13 struct gg_location_iter {
15 struct gg_iter iter;
16 const void * config;
17 const char * name;
18 char * location;
19 const char * symbol;
20 void * _state;
21 };
22 int ggConfigIterLocation(struct gg_location_iter * iter);
24 struct gg_target_iter {
26 struct gg_iter iter;
27 void * config;
28 const char * input;
29 char * target;
30 char * options;
31 void * nested;
32 };
33 int ggConfigIterTarget(struct gg_target_iter *iter);
35
38 These functions provides a simple way of handling configuration files.
39 ggLoadConfig tries to load the configuration file given as parameter.
41 It adds the content to the config handle found at *config. If the han‐
42 dle is NULL, a new one is created.
43 ggFreeConfig deletes the internal structure for the configuration han‐
45 dle config. This handle becomes invalid and should not be used anymore.
46 ggConfigIterLocation allows to retreive the location and symbol associ‐
48 ated to canonical names. This function is mainly used together with the
49 scope abstraction to query application modules at runtime. This func‐
50 tion will prepare the iter structure to be used as an iterator that
51 will generate correct matches. iter is a pointer to a gg_location_iter
52 structure owned by the caller. This user part of the structure must be
53 set by the caller before calling ggConfigIterLocation. The config field
54 must be filled with the config handle which contains target informa‐
55 tion; the name field must be filled with the canonical name that is
56 being looked for. location and symbol are placeholders in which the
57 results will be found along the iteration. The resulting strings Bdo*
58 belong to libgg and Bmust not* be freed or altered, and they may be
59 invalidated if not used during the iteration process. They must be
60 copied if needed later. _state is an internal opaque pointer that
61 keeps track of the iterator state. Its value must never be touched by
62 the caller.
63 ggConfigIterTarget allows to iterate over canonical target names and
65 options strings found in a target spec string. This function also work
66 as a generator. iter is a pointer to a gg_target_iter structure owned
67 by the caller. This user part of the structure must be set by the call‐
68 er before calling ggConfigIterTarget. The config field must be filled
69 with the config handle which contains target information; the input
70 field must be filled with the initial input spec string. target and
71 options are placeholders in which the results will be found along the
72 iteration. Here again, the resulting strings Bdo* belong to libgg and
73 Bmust not* be freed or altered, and they may be invalidated if not used
74 during the iteration process. They must be copied if needed later.
75 nested is an internal opaque pointer that keeps track of the iterator
76 state. Its value must never be touched by the caller.
77
79 ggLoadConfig returns GGI_OK on success, or:
80 · GGI_ENOMEM if it can not allocate a new configuration handle. Note
82 that if subsequent memory allocations fail (when feeding the han‐
83 dle), those will not be reported as an error. The handle will be
84 incomplete with regard to the config file contents;
85 · GGI_ENOTFOUND if the file does not exists. Note that missing files
87 in include directives will not be reported an error. Also, other
88 parse error in the file will simply cause the incriminated lines to
89 be ignored.
90 ggConfigIterLocation returns GGI_OK on success or GGI_ENOMEM.
92 ggConfigIterTarget always return GGI_OK and will never fail.
94
96 The configuration file is line oriented. Each line may define a mapping
97 between a canonical name and a location. The generic format is:
98 <pattern> <location>[:<symbol>]
100 alias <name> <expansion>
102 On the first line pattern is a canonical name that may contain one * as
104 a wildcard, location is a string that corresponds to a scope location,
105 and symbol is an optional string that gives the name of the symbol to
106 retreive from the scope. If not given, NULL will be reported. The sec‐
107 ond line defines an alias. When a target called name is found while
108 iterating over target spec strings, the iterator parse expansion as a
109 sub-input spec, and aggregate all option strings that where found on
110 upstream aliases.
111 In addition, the configuration file loader knowns the following direc‐
113 tives:
114 When locations following the .root directive are given as relative
118 path, path will be prepended. .include will parse the given file recur‐
119 sively, before continuing with the current one.
120
122 This code demonstrates how to get the first module init function acces‐
123 sible from a scope for a given name. It also shows how to use the libgg
124 iterator scheme:
125 int openModule(gg_config cfg, const char * moduleName,
127 const char * defaultSymbol) {
128 struct gg_location_iter match;
129 gg_scope scope;
130 module_init_func *init;
131 /* prepare the iterator */
133 match.name = name;
135 match.config = cfg;
136 ggConfigMatchIter(&match);
137 /* iterate over the matches */
139 GG_ITER_FOREACH(&match) {
141 /* try to retreive the collection at suggested location */
143 if((scope = ggGetScope(match.location)) == NULL)
144 continue;
145 /* use default symbol if none suggested */
147 if (match.symbol == NULL) match.symbol = defaultSymbol;
148 /* try to retreive the symbol from that scope */
150 if((init = ggFromScope(scope, match.symbol)) == NULL) {
151 ggDelScope(scope);
152 continue;
153 }
154 /* try to initialize the module */
155 if(init() != GGI_OK) {
156 ggDelScope(scope);
157 continue;
158 }
159 /* the module is up, abort iteration and return */
160 GG_ITER_DONE(&match);
161 return GGI_OK;
162 }
163 /* module not found */
165 GG_ITER_DONE(&match);
166 return GGI_ENOTFOUND;
167 Note that this code is not completely correct, because the scope cannot
169 be deleted later if it is not remembered somewhere. This next example
170 shows how to list all targets and options specified by a string:
171 static void showAllTargets(void * cfg, const char * input)
173 {
174 struct gg_target_iter match;
175 match.config = cfg;
177 match.input = input;
178 ggConfigIterTarget(&match);
179 GG_ITER_FOREACH(&match) {
180 printf("Target \"%s\" with options \"%s\".\n",
181 match.target, match.options);
182 }
183 GG_ITER_DONE(&match);
184 }
185
188 ggGetScope(3)
189libgg-1.0.x 2005-08-26 ggLoadConfig(3)