lib/ecoli_node.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  * Interface to manage the ecoli nodes.
  30  *
  31  * A node is a main structure of the ecoli library, used to define how
  32  * to match and complete the input tokens. A node is a generic object
  33  * that implements:
  34  * - a parse(node, input) method: check if an input matches
  35  * - a complete(node, input) method: return possible completions for
  36  *   a given input
  37  * - some other methods to initialize, free, ...
  38  *
  39  * One basic example is the string node (ec_node_str). A node
  40  * ec_node_str("foo") will match any token list starting with "foo",
  41  * for example:
  42  * - ["foo"]
  43  * - ["foo", "bar", ...]
  44  * But will not match:
  45  * - []
  46  * - ["bar", ...]
  47  *
  48  * A node ec_node_str("foo") will complete with "foo" if the input
  49  * contains one token, with the same beginning than "foo":
  50  * - [""]
  51  * - ["f"]
  52  * - ["fo"]
  53  * - ["foo"]
  54  * But it will not complete:
  55  * - []
  56  * - ["bar"]
  57  * - ["f", ""]
  58  * - ["", "f"]
  59  *
  60  * A node can have child nodes. For instance, a sequence node
  61  * ec_node_seq(ec_node_str("foo"), ec_node_str("bar")) will match
  62  * ["foo", "bar"].
  63  */
  64
  65 #ifndef ECOLI_NODE_
  66 #define ECOLI_NODE_
  67
  68 #include <sys/queue.h>
  69 #include <sys/types.h>
  70 #include <stdio.h>
  71
  72 #define EC_NO_ID "no-id"
  73
  74 #define EC_NODE_ENDLIST ((void *)1)
  75
  76 struct ec_node;
  77 struct ec_parsed;
  78 struct ec_completed;
  79 struct ec_strvec;
  80 struct ec_keyval;
  81
  82 #define EC_NODE_TYPE_REGISTER(t)                                                \
  83         static void ec_node_init_##t(void);                             \
  84         static void __attribute__((constructor, used))                  \
  85         ec_node_init_##t(void)                                          \
  86         {                                                               \
  87                 if (ec_node_type_register(&t) < 0)                      \
  88                         fprintf(stderr, "cannot register %s\n", t.name); \
  89         }
  90
  91 TAILQ_HEAD(ec_node_type_list, ec_node_type);
  92
  93 /* return 0 on success, else -errno. */
  94 typedef int (*ec_node_build_t)(struct ec_node *node);
  95
  96 typedef int (*ec_node_parse_t)(const struct ec_node *node,
  97                         struct ec_parsed *state,
  98                         const struct ec_strvec *strvec);
  99 typedef int (*ec_node_complete_t)(const struct ec_node *node,
 100                                 struct ec_completed *completed_state,
 101                                 const struct ec_strvec *strvec);
 102 typedef size_t (*ec_node_get_max_parse_len_t)(const struct ec_node *node);
 103 typedef const char * (*ec_node_desc_t)(const struct ec_node *);
 104 typedef int (*ec_node_init_priv_t)(struct ec_node *);
 105 typedef void (*ec_node_free_priv_t)(struct ec_node *);
 106
 107 /**
 108  * A structure describing a node type.
 109  */
 110 struct ec_node_type {
 111         TAILQ_ENTRY(ec_node_type) next;  /**< Next in list. */
 112         const char *name;                /**< Node type name. */
 113         ec_node_build_t build;           /**< (Re)build the node */
 114         ec_node_parse_t parse;
 115         ec_node_complete_t complete;
 116         ec_node_get_max_parse_len_t get_max_parse_len;
 117         ec_node_desc_t desc;
 118         size_t size;
 119         ec_node_init_priv_t init_priv;
 120         ec_node_free_priv_t free_priv;
 121 };
 122
 123 /**
 124  * Register a node type.
 125  *
 126  * @param type
 127  *   A pointer to a ec_test structure describing the test
 128  *   to be registered.
 129  * @return
 130  *   0 on success, negative value on error.
 131  */
 132 int ec_node_type_register(struct ec_node_type *type);
 133
 134 /**
 135  * Lookup node type by name
 136  *
 137  * @param name
 138  *   The name of the node type to search.
 139  * @return
 140  *   The node type if found, or NULL on error.
 141  */
 142 struct ec_node_type *ec_node_type_lookup(const char *name);
 143
 144 /**
 145  * Dump registered log types
 146  */
 147 void ec_node_type_dump(FILE *out);
 148
 149 TAILQ_HEAD(ec_node_list, ec_node);
 150
 151 struct ec_node {
 152         const struct ec_node_type *type;
 153         char *id;
 154         char *desc;
 155         struct ec_keyval *attrs;
 156         /* XXX ensure parent and child are properly set in all nodes */
 157         struct ec_node *parent;
 158         unsigned int refcnt;
 159 #define EC_NODE_F_BUILT 0x0001 /** set if configuration is built */
 160         unsigned int flags;
 161
 162         TAILQ_ENTRY(ec_node) next;
 163         struct ec_node_list children;
 164 };
 165
 166 /* create a new node when the type is known, typically called from the node
 167  * code */
 168 struct ec_node *__ec_node(const struct ec_node_type *type, const char *id);
 169
 170 /* create a_new node node */
 171 struct ec_node *ec_node(const char *typename, const char *id);
 172
 173 struct ec_node *ec_node_clone(struct ec_node *node);
 174 void ec_node_free(struct ec_node *node);
 175
 176 /**
 177  * Get the max len of strvec that can be parsed by this node
 178  *
 179  * If there is no maximum, return SIZE_MAX.
 180  */
 181 size_t ec_node_get_max_parse_len(const struct ec_node *node);
 182
 183 /* XXX add more accessors */
 184 struct ec_keyval *ec_node_attrs(const struct ec_node *node);
 185 struct ec_node *ec_node_parent(const struct ec_node *node);
 186 const char *ec_node_id(const struct ec_node *node);
 187 const char *ec_node_desc(const struct ec_node *node);
 188
 189 void ec_node_dump(FILE *out, const struct ec_node *node);
 190 struct ec_node *ec_node_find(struct ec_node *node, const char *id);
 191
 192 /* check the type of a node */
 193 int ec_node_check_type(const struct ec_node *node,
 194                 const struct ec_node_type *type);
 195
 196 #endif