list children in a table, not in a list
[protos/libecoli.git] / lib / ecoli_parsed.h
1 /*
2  * Copyright (c) 2016, Olivier MATZ <zer0@droids-corp.org>
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *
7  *     * Redistributions of source code must retain the above copyright
8  *       notice, this list of conditions and the following disclaimer.
9  *     * Redistributions in binary form must reproduce the above copyright
10  *       notice, this list of conditions and the following disclaimer in the
11  *       documentation and/or other materials provided with the distribution.
12  *     * Neither the name of the University of California, Berkeley nor the
13  *       names of its contributors may be used to endorse or promote products
14  *       derived from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27
28 /**
29  * Node parse API.
30  *
31  * The parse operation is to check if an input (a string or vector of
32  * strings) matches the node tree. On success, the result is stored in a
33  * tree that describes which part of the input matches which node.
34  */
35
36 #ifndef ECOLI_PARSED_
37 #define ECOLI_PARSED_
38
39 #include <sys/queue.h>
40 #include <sys/types.h>
41 #include <limits.h>
42 #include <stdio.h>
43
44 struct ec_node;
45 struct ec_parsed;
46
47 /**
48  * Create an empty parse tree.
49  *
50  * @return
51  *   The empty parse tree.
52  */
53 struct ec_parsed *ec_parsed(const struct ec_node *node);
54
55 /**
56  *
57  *
58  *
59  */
60 void ec_parsed_free(struct ec_parsed *parsed);
61
62 /**
63  *
64  *
65  *
66  */
67 void ec_parsed_free_children(struct ec_parsed *parsed);
68
69 /**
70  *
71  *
72  *
73  */
74 struct ec_parsed *ec_parsed_dup(struct ec_parsed *parsed);
75
76 /**
77  *
78  *
79  *
80  */
81 const struct ec_strvec *ec_parsed_strvec(const struct ec_parsed *parsed);
82
83 /* a NULL return value is an error, with errno set
84   ENOTSUP: no ->parse() operation
85 */
86 /**
87  *
88  *
89  *
90  */
91 struct ec_parsed *ec_node_parse(const struct ec_node *node, const char *str);
92
93 /**
94  *
95  *
96  *
97  */
98 struct ec_parsed *ec_node_parse_strvec(const struct ec_node *node,
99                                 const struct ec_strvec *strvec);
100
101 /**
102  *
103  *
104  *
105  */
106 #define EC_PARSED_NOMATCH INT_MAX
107
108 /* internal: used by nodes
109  *
110  * state is the current parse tree, which is built piece by piece while
111  *   parsing the node tree: ec_node_parse_child() creates a new child in
112  *   this state parse tree, and calls the parse() method for the child
113  *   node, with state pointing to this new child. If it does not match,
114  *   the child is removed in the state, else it is kept, with its
115  *   possible descendants.
116  *
117  * return:
118  * EC_PARSED_NOMATCH (positive) if it does not match
119  * any other negative value (-errno) for other errors
120  * the number of matched strings in strvec
121  */
122 int ec_node_parse_child(const struct ec_node *node,
123                         struct ec_parsed *state,
124                         const struct ec_strvec *strvec);
125
126 /**
127  *
128  *
129  *
130  */
131 void ec_parsed_add_child(struct ec_parsed *parsed,
132                         struct ec_parsed *child);
133 /**
134  *
135  *
136  *
137  */
138 void ec_parsed_del_child(struct ec_parsed *parsed,
139                         struct ec_parsed *child);
140
141 /**
142  *
143  *
144  *
145  */
146 struct ec_parsed *ec_parsed_get_root(struct ec_parsed *parsed);
147
148 /**
149  *
150  *
151  *
152  */
153 struct ec_parsed *ec_parsed_get_parent(struct ec_parsed *parsed);
154
155 /**
156  * Get the first child of a tree.
157  *
158  */
159 struct ec_parsed *ec_parsed_get_first_child(const struct ec_parsed *parsed);
160
161 /**
162  *
163  *
164  *
165  */
166 struct ec_parsed *ec_parsed_get_last_child(const struct ec_parsed *parsed);
167
168 /**
169  *
170  *
171  *
172  */
173 struct ec_parsed *ec_parsed_get_next(const struct ec_parsed *parsed);
174
175 /**
176  *
177  *
178  *
179  */
180 #define EC_PARSED_FOREACH_CHILD(child, parsed)                  \
181         for (child = ec_parsed_get_first_child(parsed);         \
182                 child != NULL;                                  \
183                 child = ec_parsed_get_next(child))              \
184
185 /**
186  *
187  *
188  *
189  */
190 bool ec_parsed_has_child(const struct ec_parsed *parsed);
191
192 /**
193  *
194  *
195  *
196  */
197 const struct ec_node *ec_parsed_get_node(const struct ec_parsed *parsed);
198
199 /**
200  *
201  *
202  *
203  */
204 void ec_parsed_del_last_child(struct ec_parsed *parsed);
205
206 /**
207  *
208  *
209  *
210  */
211 struct ec_keyval *ec_parsed_get_attrs(struct ec_parsed *parsed);
212
213 /**
214  *
215  *
216  *
217  */
218 void ec_parsed_dump(FILE *out, const struct ec_parsed *parsed);
219
220 /**
221  *
222  *
223  *
224  */
225 struct ec_parsed *ec_parsed_find_first(struct ec_parsed *parsed,
226         const char *id);
227
228 /**
229  * Iterate among parsed tree
230  *
231  * Use it with:
232  * for (iter = state; iter != NULL; iter = ec_parsed_iter_next(iter))
233  */
234 struct ec_parsed *ec_parsed_iter_next(struct ec_parsed *parsed);
235
236 /**
237  *
238  *
239  *
240  */
241 size_t ec_parsed_len(const struct ec_parsed *parsed);
242
243 /**
244  *
245  *
246  *
247  */
248 size_t ec_parsed_matches(const struct ec_parsed *parsed);
249
250 #endif