parsed -> parse
[protos/libecoli.git] / lib / ecoli_parse.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
3  */
4
5 /**
6  * Node parse API.
7  *
8  * The parse operation is to check if an input (a string or vector of
9  * strings) matches the node tree. On success, the result is stored in a
10  * tree that describes which part of the input matches which node.
11  */
12
13 #ifndef ECOLI_PARSE_
14 #define ECOLI_PARSE_
15
16 #include <sys/queue.h>
17 #include <sys/types.h>
18 #include <limits.h>
19 #include <stdio.h>
20
21 struct ec_node;
22 struct ec_parse;
23
24 /**
25  * Create an empty parse tree.
26  *
27  * @return
28  *   The empty parse tree.
29  */
30 struct ec_parse *ec_parse(const struct ec_node *node);
31
32 /**
33  *
34  *
35  *
36  */
37 void ec_parse_free(struct ec_parse *parse);
38
39 /**
40  *
41  *
42  *
43  */
44 void ec_parse_free_children(struct ec_parse *parse);
45
46 /**
47  *
48  *
49  *
50  */
51 struct ec_parse *ec_parse_dup(const struct ec_parse *parse);
52
53 /**
54  *
55  *
56  *
57  */
58 const struct ec_strvec *ec_parse_strvec(const struct ec_parse *parse);
59
60 /* a NULL return value is an error, with errno set
61   ENOTSUP: no ->parse() operation
62 */
63 /**
64  *
65  *
66  *
67  */
68 struct ec_parse *ec_node_parse(const struct ec_node *node, const char *str);
69
70 /**
71  *
72  *
73  *
74  */
75 struct ec_parse *ec_node_parse_strvec(const struct ec_node *node,
76                                 const struct ec_strvec *strvec);
77
78 /**
79  *
80  *
81  *
82  */
83 #define EC_PARSE_NOMATCH INT_MAX
84
85 /* internal: used by nodes
86  *
87  * state is the current parse tree, which is built piece by piece while
88  *   parsing the node tree: ec_node_parse_child() creates a new child in
89  *   this state parse tree, and calls the parse() method for the child
90  *   node, with state pointing to this new child. If it does not match,
91  *   the child is removed in the state, else it is kept, with its
92  *   possible descendants.
93  *
94  * return:
95  * EC_PARSE_NOMATCH (positive) if it does not match
96  * any other negative value (-errno) for other errors
97  * the number of matched strings in strvec
98  */
99 int ec_node_parse_child(const struct ec_node *node,
100                         struct ec_parse *state,
101                         const struct ec_strvec *strvec);
102
103 /**
104  *
105  *
106  *
107  */
108 void ec_parse_link_child(struct ec_parse *parse,
109                         struct ec_parse *child);
110 /**
111  *
112  *
113  *
114  */
115 void ec_parse_unlink_child(struct ec_parse *parse,
116                         struct ec_parse *child);
117
118 /* keep the const */
119 #define ec_parse_get_root(parse) ({                             \
120         const struct ec_parse *p_ = parse; /* check type */     \
121         struct ec_parse *parse_ = (struct ec_parse *)parse;     \
122         typeof(parse) res_;                                     \
123         (void)p_;                                               \
124         res_ = __ec_parse_get_root(parse_);                     \
125         res_;                                                   \
126 })
127
128 /**
129  *
130  *
131  *
132  */
133 struct ec_parse *__ec_parse_get_root(struct ec_parse *parse);
134
135 /**
136  *
137  *
138  *
139  */
140 struct ec_parse *ec_parse_get_parent(const struct ec_parse *parse);
141
142 /**
143  * Get the first child of a tree.
144  *
145  */
146 struct ec_parse *ec_parse_get_first_child(const struct ec_parse *parse);
147
148 /**
149  *
150  *
151  *
152  */
153 struct ec_parse *ec_parse_get_last_child(const struct ec_parse *parse);
154
155 /**
156  *
157  *
158  *
159  */
160 struct ec_parse *ec_parse_get_next(const struct ec_parse *parse);
161
162 /**
163  *
164  *
165  *
166  */
167 #define EC_PARSE_FOREACH_CHILD(child, parse)                    \
168         for (child = ec_parse_get_first_child(parse);           \
169                 child != NULL;                                  \
170                 child = ec_parse_get_next(child))               \
171
172 /**
173  *
174  *
175  *
176  */
177 bool ec_parse_has_child(const struct ec_parse *parse);
178
179 /**
180  *
181  *
182  *
183  */
184 const struct ec_node *ec_parse_get_node(const struct ec_parse *parse);
185
186 /**
187  *
188  *
189  *
190  */
191 void ec_parse_del_last_child(struct ec_parse *parse);
192
193 /**
194  *
195  *
196  *
197  */
198 struct ec_keyval *ec_parse_get_attrs(struct ec_parse *parse);
199
200 /**
201  *
202  *
203  *
204  */
205 void ec_parse_dump(FILE *out, const struct ec_parse *parse);
206
207 /**
208  *
209  *
210  *
211  */
212 struct ec_parse *ec_parse_find_first(struct ec_parse *parse,
213         const char *id);
214
215 /**
216  * Iterate among parse tree
217  *
218  * Use it with:
219  * for (iter = state; iter != NULL; iter = ec_parse_iter_next(iter))
220  */
221 struct ec_parse *ec_parse_iter_next(struct ec_parse *parse);
222
223 /**
224  *
225  *
226  *
227  */
228 size_t ec_parse_len(const struct ec_parse *parse);
229
230 /**
231  *
232  *
233  *
234  */
235 size_t ec_parse_matches(const struct ec_parse *parse);
236
237 #endif