save state in completed objects
[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(void);
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 /* XXX we could use a cache to store possible completions or match: the
84  * cache would be per-node, and would be reset for each call to parse()
85  * or complete() ? ... not sure, since parse result can depend on state
86  */
87 /* a NULL return value is an error, with errno set
88   ENOTSUP: no ->parse() operation
89 */
90 /**
91  *
92  *
93  *
94  */
95 struct ec_parsed *ec_node_parse(struct ec_node *node, const char *str);
96
97 /**
98  *
99  *
100  *
101  */
102 struct ec_parsed *ec_node_parse_strvec(struct ec_node *node,
103                                 const struct ec_strvec *strvec);
104
105 /**
106  *
107  *
108  *
109  */
110 #define EC_PARSED_NOMATCH INT_MAX
111
112 /* internal: used by nodes
113  *
114  * state is the current parse tree, which is built piece by piece while
115  *   parsing the node tree: ec_node_parse_child() creates a new child in
116  *   this state parse tree, and calls the parse() method for the child
117  *   node, with state pointing to this new child. If it does not match,
118  *   the child is removed in the state, else it is kept, with its
119  *   possible descendants.
120  *
121  * return:
122  * EC_PARSED_NOMATCH (positive) if it does not match
123  * any other negative value (-errno) for other errors
124  * the number of matched strings in strvec
125  * XXX state is not freed on error ?
126  */
127 int ec_node_parse_child(struct ec_node *node,
128                         struct ec_parsed *state,
129                         const struct ec_strvec *strvec);
130
131 /**
132  *
133  *
134  *
135  */
136 void ec_parsed_add_child(struct ec_parsed *parsed,
137                         struct ec_parsed *child);
138 /**
139  *
140  *
141  *
142  */
143 void ec_parsed_del_child(struct ec_parsed *parsed,
144                         struct ec_parsed *child);
145
146 /**
147  *
148  *
149  *
150  */
151 struct ec_parsed *ec_parsed_get_root(struct ec_parsed *parsed);
152
153 /**
154  *
155  *
156  *
157  */
158 struct ec_parsed *ec_parsed_get_parent(struct ec_parsed *parsed);
159
160 /**
161  * Get the first child of a tree.
162  *
163  */
164 struct ec_parsed *ec_parsed_get_first_child(const struct ec_parsed *parsed);
165
166 /**
167  *
168  *
169  *
170  */
171 struct ec_parsed *ec_parsed_get_last_child(const struct ec_parsed *parsed);
172
173 /**
174  *
175  *
176  *
177  */
178 struct ec_parsed *ec_parsed_get_next(const struct ec_parsed *parsed);
179
180 /**
181  *
182  *
183  *
184  */
185 #define EC_PARSED_FOREACH_CHILD(child, parsed)                  \
186         for (child = ec_parsed_get_first_child(parsed);         \
187                 child != NULL;                                  \
188                 child = ec_parsed_get_next(child))              \
189
190 /**
191  *
192  *
193  *
194  */
195 bool ec_parsed_has_child(const struct ec_parsed *parsed);
196
197 /**
198  *
199  *
200  *
201  */
202 const struct ec_node *ec_parsed_get_node(const struct ec_parsed *parsed);
203
204 /**
205  *
206  *
207  *
208  */
209 void ec_parsed_set_node(struct ec_parsed *parsed, const struct ec_node *node);
210
211 /**
212  *
213  *
214  *
215  */
216 void ec_parsed_del_last_child(struct ec_parsed *parsed);
217
218 /**
219  *
220  *
221  *
222  */
223 int ec_parsed_get_path(struct ec_parsed *parsed, struct ec_node **path);
224
225 /**
226  *
227  *
228  *
229  */
230 void ec_parsed_dump(FILE *out, const struct ec_parsed *parsed);
231
232 /**
233  *
234  *
235  *
236  */
237 struct ec_parsed *ec_parsed_find_first(struct ec_parsed *parsed,
238         const char *id);
239
240 /**
241  *
242  *
243  *
244  */
245 size_t ec_parsed_len(const struct ec_parsed *parsed);
246
247 /**
248  *
249  *
250  *
251  */
252 size_t ec_parsed_matches(const struct ec_parsed *parsed);
253
254 #endif