add ec_node_bypass
[protos/libecoli.git] / include / ecoli_node.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
3  */
4
5 /**
6  * Interface to manage the ecoli nodes.
7  *
8  * A node is a main structure of the ecoli library, used to define how
9  * to match and complete the input tokens. A node is a generic object
10  * that implements:
11  * - a parse(node, input) method: check if an input matches
12  * - a complete(node, input) method: return possible completions for
13  *   a given input
14  * - some other methods to initialize, free, ...
15  *
16  * One basic example is the string node (ec_node_str). A node
17  * ec_node_str("foo") will match any token list starting with "foo",
18  * for example:
19  * - ["foo"]
20  * - ["foo", "bar", ...]
21  * But will not match:
22  * - []
23  * - ["bar", ...]
24  *
25  * A node ec_node_str("foo") will complete with "foo" if the input
26  * contains one token, with the same beginning than "foo":
27  * - [""]
28  * - ["f"]
29  * - ["fo"]
30  * - ["foo"]
31  * But it will not complete:
32  * - []
33  * - ["bar"]
34  * - ["f", ""]
35  * - ["", "f"]
36  *
37  * A node can have child nodes. For instance, a sequence node
38  * ec_node_seq(ec_node_str("foo"), ec_node_str("bar")) will match
39  * ["foo", "bar"].
40  */
41
42 #ifndef ECOLI_NODE_
43 #define ECOLI_NODE_
44
45 #include <sys/queue.h>
46 #include <sys/types.h>
47 #include <stdio.h>
48
49 #define EC_NO_ID "no-id"
50
51 #define EC_NODE_ENDLIST ((void *)1)
52
53 struct ec_node;
54 struct ec_parse;
55 struct ec_comp;
56 struct ec_strvec;
57 struct ec_keyval;
58 struct ec_config;
59 struct ec_config_schema;
60
61 #define EC_NODE_TYPE_REGISTER(t)                                        \
62         static void ec_node_init_##t(void);                             \
63         static void __attribute__((constructor, used))                  \
64         ec_node_init_##t(void)                                          \
65         {                                                               \
66                 if (ec_node_type_register(&t) < 0)                      \
67                         fprintf(stderr,                                 \
68                                 "cannot register node type %s\n",       \
69                                 t.name);                                \
70         }
71
72 TAILQ_HEAD(ec_node_type_list, ec_node_type);
73
74 typedef int (*ec_node_set_config_t)(struct ec_node *node,
75                                 const struct ec_config *config);
76 typedef int (*ec_node_parse_t)(const struct ec_node *node,
77                         struct ec_parse *state,
78                         const struct ec_strvec *strvec);
79 typedef int (*ec_node_complete_t)(const struct ec_node *node,
80                                 struct ec_comp *comp_state,
81                                 const struct ec_strvec *strvec);
82 typedef const char * (*ec_node_desc_t)(const struct ec_node *);
83 typedef int (*ec_node_init_priv_t)(struct ec_node *);
84 typedef void (*ec_node_free_priv_t)(struct ec_node *);
85 typedef size_t (*ec_node_get_children_count_t)(const struct ec_node *);
86 typedef int (*ec_node_get_child_t)(const struct ec_node *,
87         size_t i, struct ec_node **child, unsigned int *refs);
88
89 /**
90  * A structure describing a node type.
91  */
92 struct ec_node_type {
93         TAILQ_ENTRY(ec_node_type) next;  /**< Next in list. */
94         const char *name;                /**< Node type name. */
95         /** Configuration schema array, must be terminated by a sentinel
96          *  (.type = EC_CONFIG_TYPE_NONE). */
97         const struct ec_config_schema *schema;
98         ec_node_set_config_t set_config; /* validate/ack a config change */
99         ec_node_parse_t parse;
100         ec_node_complete_t complete;
101         ec_node_desc_t desc;
102         size_t size;
103         ec_node_init_priv_t init_priv;
104         ec_node_free_priv_t free_priv;
105         ec_node_get_children_count_t get_children_count;
106         ec_node_get_child_t get_child;
107 };
108
109 /**
110  * Register a node type.
111  *
112  * @param type
113  *   A pointer to a ec_test structure describing the test
114  *   to be registered.
115  * @return
116  *   0 on success, negative value on error.
117  */
118 int ec_node_type_register(struct ec_node_type *type);
119
120 /**
121  * Lookup node type by name
122  *
123  * @param name
124  *   The name of the node type to search.
125  * @return
126  *   The node type if found, or NULL on error.
127  */
128 const struct ec_node_type *ec_node_type_lookup(const char *name);
129
130 /**
131  * Dump registered log types
132  */
133 void ec_node_type_dump(FILE *out);
134
135 /**
136  * Get the config schema of a node type.
137  */
138 const struct ec_config_schema *
139 ec_node_type_schema(const struct ec_node_type *type);
140
141 /**
142  * Get the name of a node type.
143  */
144 const char *
145 ec_node_type_name(const struct ec_node_type *type);
146
147 enum ec_node_free_state {
148         EC_NODE_FREE_STATE_NONE,
149         EC_NODE_FREE_STATE_TRAVERSED,
150         EC_NODE_FREE_STATE_FREEABLE,
151         EC_NODE_FREE_STATE_NOT_FREEABLE,
152         EC_NODE_FREE_STATE_FREEING,
153 };
154
155 struct ec_node {
156         const struct ec_node_type *type;
157         struct ec_config *config;    /**< Generic configuration. */
158         char *id;
159         char *desc;
160         struct ec_keyval *attrs;
161         unsigned int refcnt;
162         struct {
163                 enum ec_node_free_state state; /**< State of loop detection */
164                 unsigned int refcnt;    /**< Number of reachable references
165                                          *   starting from node beeing freed */
166         } free; /**< Freeing state: used for loop detection */
167 };
168
169 /* create a new node when the type is known, typically called from the node
170  * code */
171 struct ec_node *ec_node_from_type(const struct ec_node_type *type, const char *id);
172
173 /* create a new node */
174 struct ec_node *ec_node(const char *typename, const char *id);
175
176 struct ec_node *ec_node_clone(struct ec_node *node);
177 void ec_node_free(struct ec_node *node);
178
179 /* set configuration of a node
180  * after a call to this function, the config is
181  * owned by the node and must not be used by the caller
182  * on error, the config is freed. */
183 int ec_node_set_config(struct ec_node *node, struct ec_config *config);
184
185 /* get the current node configuration. Return NULL if no configuration. */
186 const struct ec_config *ec_node_get_config(struct ec_node *node);
187
188 size_t ec_node_get_children_count(const struct ec_node *node);
189 int
190 ec_node_get_child(const struct ec_node *node, size_t i,
191         struct ec_node **child, unsigned int *refs);
192
193 /* XXX add more accessors */
194 const struct ec_node_type *ec_node_type(const struct ec_node *node);
195 struct ec_keyval *ec_node_attrs(const struct ec_node *node);
196 const char *ec_node_id(const struct ec_node *node);
197 const char *ec_node_desc(const struct ec_node *node);
198
199 void ec_node_dump(FILE *out, const struct ec_node *node);
200 struct ec_node *ec_node_find(struct ec_node *node, const char *id);
201
202 /* check the type of a node */
203 int ec_node_check_type(const struct ec_node *node,
204                 const struct ec_node_type *type);
205
206 #endif