lib/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 struct ec_node * (*ec_node_get_child_t)(const struct ec_node *,
  87                                                 size_t i);
  88 typedef unsigned int (*ec_node_get_child_refs_t)(const struct ec_node *,
  89                                                 size_t i);
  90
  91 /**
  92  * A structure describing a node type.
  93  */
  94 struct ec_node_type {
  95         TAILQ_ENTRY(ec_node_type) next;  /**< Next in list. */
  96         const char *name;                /**< Node type name. */
  97         /** Generic configuration schema. */
  98         const struct ec_config_schema *schema;
  99         size_t schema_len;               /**< Number of elts in schema array. */
 100         ec_node_set_config_t set_config; /* validate/ack a config change */
 101         ec_node_parse_t parse;
 102         ec_node_complete_t complete;
 103         ec_node_desc_t desc;
 104         size_t size;
 105         ec_node_init_priv_t init_priv;
 106         ec_node_free_priv_t free_priv;
 107         ec_node_get_children_count_t get_children_count;
 108         ec_node_get_child_t get_child;
 109         ec_node_get_child_refs_t get_child_refs;
 110 };
 111
 112 /**
 113  * Register a node type.
 114  *
 115  * @param type
 116  *   A pointer to a ec_test structure describing the test
 117  *   to be registered.
 118  * @return
 119  *   0 on success, negative value on error.
 120  */
 121 int ec_node_type_register(struct ec_node_type *type);
 122
 123 /**
 124  * Lookup node type by name
 125  *
 126  * @param name
 127  *   The name of the node type to search.
 128  * @return
 129  *   The node type if found, or NULL on error.
 130  */
 131 const struct ec_node_type *ec_node_type_lookup(const char *name);
 132
 133 /**
 134  * Dump registered log types
 135  */
 136 void ec_node_type_dump(FILE *out);
 137
 138 enum ec_node_free_state {
 139         EC_NODE_FREE_STATE_NONE,
 140         EC_NODE_FREE_STATE_TRAVERSED,
 141         EC_NODE_FREE_STATE_FREEABLE,
 142         EC_NODE_FREE_STATE_NOT_FREEABLE,
 143         EC_NODE_FREE_STATE_FREEING,
 144 };
 145
 146 struct ec_node {
 147         const struct ec_node_type *type;
 148         struct ec_config *config;    /**< Generic configuration. */
 149         char *id;
 150         char *desc;
 151         struct ec_keyval *attrs;
 152         unsigned int refcnt;
 153         struct {
 154                 enum ec_node_free_state state; /**< State of loop detection */
 155                 unsigned int refcnt;    /**< Number of reachable references
 156                                          *   starting from node beeing freed */
 157         } free; /**< Freeing state: used for loop detection */
 158 };
 159
 160 /* create a new node when the type is known, typically called from the node
 161  * code */
 162 struct ec_node *__ec_node(const struct ec_node_type *type, const char *id);
 163
 164 /* create a new node */
 165 struct ec_node *ec_node(const char *typename, const char *id);
 166
 167 struct ec_node *ec_node_clone(struct ec_node *node);
 168 void ec_node_free(struct ec_node *node);
 169
 170 /* set configuration of a node
 171  * after a call to this function, the config is
 172  * owned by the node and must not be used by the caller
 173  * on error, the config is freed. */
 174 int ec_node_set_config(struct ec_node *node, struct ec_config *config);
 175
 176 /* get the current node configuration. Return NULL if no configuration. */
 177 const struct ec_config *ec_node_get_config(struct ec_node *node);
 178
 179 size_t ec_node_get_children_count(const struct ec_node *node);
 180 struct ec_node *
 181 ec_node_get_child(const struct ec_node *node, size_t i);
 182 unsigned int
 183 ec_node_get_child_refs(const struct ec_node *node, size_t i);
 184
 185 /* XXX add more accessors */
 186 const struct ec_node_type *ec_node_type(const struct ec_node *node);
 187 struct ec_keyval *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 #endif