1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
6 * @defgroup grammar_tree Grammar Tree
9 * @brief Libecoli grammar nodes.
11 * The grammar node is a main structure of the ecoli library, used to define
12 * how to match and complete the input tokens. A node is a generic object
14 * - a parse(node, input) method: check if an input matches
15 * - a complete(node, input) method: return possible completions for
17 * - some other methods to initialize, free, ...
19 * One basic example is the string node (ec_node_str). A node
20 * ec_node_str("foo") will match any token list starting with "foo",
23 * - ["foo", "bar", ...]
28 * A node ec_node_str("foo") will complete with "foo" if the input
29 * contains one token, with the same beginning than "foo":
34 * But it will not complete:
40 * A node can have child nodes. For instance, a sequence node
41 * ec_node_seq(ec_node_str("foo"), ec_node_str("bar")) will match
48 #include <sys/queue.h>
49 #include <sys/types.h>
53 * Node has no identifier.
55 #define EC_NO_ID "no-id"
57 #define EC_NODE_ENDLIST ((void *)1)
65 struct ec_config_schema;
67 #define EC_NODE_TYPE_REGISTER(t) \
68 static void ec_node_init_##t(void); \
69 static void __attribute__((constructor, used)) \
70 ec_node_init_##t(void) \
72 if (ec_node_type_register(&t) < 0) \
74 "cannot register node type %s\n", \
78 TAILQ_HEAD(ec_node_type_list, ec_node_type);
80 typedef int (*ec_node_set_config_t)(struct ec_node *node,
81 const struct ec_config *config);
82 typedef int (*ec_node_parse_t)(const struct ec_node *node,
83 struct ec_parse *state,
84 const struct ec_strvec *strvec);
85 typedef int (*ec_node_complete_t)(const struct ec_node *node,
86 struct ec_comp *comp_state,
87 const struct ec_strvec *strvec);
88 typedef const char * (*ec_node_desc_t)(const struct ec_node *);
89 typedef int (*ec_node_init_priv_t)(struct ec_node *);
90 typedef void (*ec_node_free_priv_t)(struct ec_node *);
91 typedef size_t (*ec_node_get_children_count_t)(const struct ec_node *);
92 typedef int (*ec_node_get_child_t)(const struct ec_node *,
93 size_t i, struct ec_node **child, unsigned int *refs);
96 * A structure describing a node type.
99 TAILQ_ENTRY(ec_node_type) next; /**< Next in list. */
100 const char *name; /**< Node type name. */
101 /** Configuration schema array, must be terminated by a sentinel
102 * (.type = EC_CONFIG_TYPE_NONE). */
103 const struct ec_config_schema *schema;
104 ec_node_set_config_t set_config; /* validate/ack a config change */
105 ec_node_parse_t parse;
106 ec_node_complete_t complete;
109 ec_node_init_priv_t init_priv;
110 ec_node_free_priv_t free_priv;
111 ec_node_get_children_count_t get_children_count;
112 ec_node_get_child_t get_child;
116 * Register a node type.
119 * A pointer to a ec_test structure describing the test
122 * 0 on success, negative value on error.
124 int ec_node_type_register(struct ec_node_type *type);
127 * Lookup node type by name
130 * The name of the node type to search.
132 * The node type if found, or NULL on error.
134 const struct ec_node_type *ec_node_type_lookup(const char *name);
137 * Dump registered log types
139 void ec_node_type_dump(FILE *out);
142 * Get the config schema of a node type.
144 const struct ec_config_schema *
145 ec_node_type_schema(const struct ec_node_type *type);
148 * Get the name of a node type.
151 ec_node_type_name(const struct ec_node_type *type);
153 enum ec_node_free_state {
154 EC_NODE_FREE_STATE_NONE,
155 EC_NODE_FREE_STATE_TRAVERSED,
156 EC_NODE_FREE_STATE_FREEABLE,
157 EC_NODE_FREE_STATE_NOT_FREEABLE,
158 EC_NODE_FREE_STATE_FREEING,
162 const struct ec_node_type *type;
163 struct ec_config *config; /**< Generic configuration. */
166 struct ec_dict *attrs;
169 enum ec_node_free_state state; /**< State of loop detection */
170 unsigned int refcnt; /**< Number of reachable references
171 * starting from node beeing freed */
172 } free; /**< Freeing state: used for loop detection */
175 /* create a new node when the type is known, typically called from the node
177 struct ec_node *ec_node_from_type(const struct ec_node_type *type, const char *id);
179 /* create a new node */
180 struct ec_node *ec_node(const char *typename, const char *id);
182 struct ec_node *ec_node_clone(struct ec_node *node);
183 void ec_node_free(struct ec_node *node);
185 /* set configuration of a node
186 * after a call to this function, the config is
187 * owned by the node and must not be used by the caller
188 * on error, the config is freed. */
189 int ec_node_set_config(struct ec_node *node, struct ec_config *config);
191 /* get the current node configuration. Return NULL if no configuration. */
192 const struct ec_config *ec_node_get_config(struct ec_node *node);
194 size_t ec_node_get_children_count(const struct ec_node *node);
196 ec_node_get_child(const struct ec_node *node, size_t i,
197 struct ec_node **child, unsigned int *refs);
199 /* XXX add more accessors */
200 const struct ec_node_type *ec_node_type(const struct ec_node *node);
201 struct ec_dict *ec_node_attrs(const struct ec_node *node);
202 const char *ec_node_id(const struct ec_node *node);
203 const char *ec_node_desc(const struct ec_node *node);
205 void ec_node_dump(FILE *out, const struct ec_node *node);
206 struct ec_node *ec_node_find(struct ec_node *node, const char *id);
208 /* check the type of a node */
209 int ec_node_check_type(const struct ec_node *node,
210 const struct ec_node_type *type);