include/ecoli_node.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
   3  */
   4
   5 /**
   6  * @defgroup grammar_tree Grammar Tree
   7  * @{
   8  *
   9  * @brief Libecoli grammar nodes.
  10  *
  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
  13  * that implements:
  14  * - a parse(node, input) method: check if an input matches
  15  * - a complete(node, input) method: return possible completions for
  16  *   a given input
  17  * - some other methods to initialize, free, ...
  18  *
  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",
  21  * for example:
  22  * - ["foo"]
  23  * - ["foo", "bar", ...]
  24  * But will not match:
  25  * - []
  26  * - ["bar", ...]
  27  *
  28  * A node ec_node_str("foo") will complete with "foo" if the input
  29  * contains one token, with the same beginning than "foo":
  30  * - [""]
  31  * - ["f"]
  32  * - ["fo"]
  33  * - ["foo"]
  34  * But it will not complete:
  35  * - []
  36  * - ["bar"]
  37  * - ["f", ""]
  38  * - ["", "f"]
  39  *
  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
  42  * ["foo", "bar"].
  43  */
  44
  45 #ifndef ECOLI_NODE_
  46 #define ECOLI_NODE_
  47
  48 #include <sys/queue.h>
  49 #include <sys/types.h>
  50 #include <stdio.h>
  51
  52 /**
  53  * Node has no identifier.
  54  */
  55 #define EC_NO_ID "no-id"
  56
  57 #define EC_NODE_ENDLIST ((void *)1)
  58
  59 struct ec_node;
  60 struct ec_parse;
  61 struct ec_comp;
  62 struct ec_strvec;
  63 struct ec_dict;
  64 struct ec_config;
  65 struct ec_config_schema;
  66
  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)                                          \
  71         {                                                               \
  72                 if (ec_node_type_register(&t) < 0)                      \
  73                         fprintf(stderr,                                 \
  74                                 "cannot register node type %s\n",       \
  75                                 t.name);                                \
  76         }
  77
  78 TAILQ_HEAD(ec_node_type_list, ec_node_type);
  79
  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);
  94
  95 /**
  96  * A structure describing a node type.
  97  */
  98 struct ec_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;
 107         ec_node_desc_t desc;
 108         size_t size;
 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;
 113 };
 114
 115 /**
 116  * Register a node type.
 117  *
 118  * @param type
 119  *   A pointer to a ec_test structure describing the test
 120  *   to be registered.
 121  * @return
 122  *   0 on success, negative value on error.
 123  */
 124 int ec_node_type_register(struct ec_node_type *type);
 125
 126 /**
 127  * Lookup node type by name
 128  *
 129  * @param name
 130  *   The name of the node type to search.
 131  * @return
 132  *   The node type if found, or NULL on error.
 133  */
 134 const struct ec_node_type *ec_node_type_lookup(const char *name);
 135
 136 /**
 137  * Dump registered log types
 138  */
 139 void ec_node_type_dump(FILE *out);
 140
 141 /**
 142  * Get the config schema of a node type.
 143  */
 144 const struct ec_config_schema *
 145 ec_node_type_schema(const struct ec_node_type *type);
 146
 147 /**
 148  * Get the name of a node type.
 149  */
 150 const char *
 151 ec_node_type_name(const struct ec_node_type *type);
 152
 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,
 159 };
 160
 161 /* create a new node when the type is known, typically called from the node
 162  * code */
 163 struct ec_node *ec_node_from_type(const struct ec_node_type *type, const char *id);
 164
 165 /* create a new node */
 166 struct ec_node *ec_node(const char *typename, const char *id);
 167
 168 struct ec_node *ec_node_clone(struct ec_node *node);
 169 void ec_node_free(struct ec_node *node);
 170
 171 /* set configuration of a node
 172  * after a call to this function, the config is
 173  * owned by the node and must not be used by the caller
 174  * on error, the config is freed. */
 175 int ec_node_set_config(struct ec_node *node, struct ec_config *config);
 176
 177 /* get the current node configuration. Return NULL if no configuration. */
 178 const struct ec_config *ec_node_get_config(struct ec_node *node);
 179
 180 size_t ec_node_get_children_count(const struct ec_node *node);
 181 int
 182 ec_node_get_child(const struct ec_node *node, size_t i,
 183         struct ec_node **child, unsigned int *refs);
 184
 185 /* XXX add more accessors */
 186 const struct ec_node_type *ec_node_type(const struct ec_node *node);
 187 struct ec_dict *ec_node_attrs(const struct ec_node *node);
 188 const char *ec_node_id(const struct ec_node *node);
 189 const char *ec_node_desc(const struct ec_node *node);
 190
 191 void ec_node_dump(FILE *out, const struct ec_node *node);
 192 struct ec_node *ec_node_find(struct ec_node *node, const char *id);
 193
 194 /* check the type of a node */
 195 int ec_node_check_type(const struct ec_node *node,
 196                 const struct ec_node_type *type);
 197
 198 const char *ec_node_get_type_name(const struct ec_node *node);
 199
 200 /**
 201  * Get the pointer to the node private area.
 202  *
 203  * @param node
 204  *   The grammar node.
 205  * @return
 206  *   The pointer to the node private area.
 207  */
 208 void *ec_node_priv(const struct ec_node *node);
 209
 210 #endif
 211
 212  /** @} */