libecoli/ecoli_parse.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2016, Olivier MATZ <zer0@droids-corp.org>
   3  */
   4
   5 /**
   6  * Node parse API.
   7  *
   8  * The parse operation is to check if an input (a string or vector of
   9  * strings) matches the node tree. On success, the result is stored in a
  10  * tree that describes which part of the input matches which node.
  11  */
  12
  13 #ifndef ECOLI_PARSE_
  14 #define ECOLI_PARSE_
  15
  16 #include <sys/queue.h>
  17 #include <sys/types.h>
  18 #include <limits.h>
  19 #include <stdio.h>
  20
  21 struct ec_node;
  22 struct ec_parse;
  23
  24 /**
  25  * Create an empty parse tree.
  26  *
  27  * @return
  28  *   The empty parse tree.
  29  */
  30 struct ec_parse *ec_parse(const struct ec_node *node);
  31
  32 /**
  33  *
  34  *
  35  *
  36  */
  37 void ec_parse_free(struct ec_parse *parse);
  38
  39 /**
  40  *
  41  *
  42  *
  43  */
  44 void ec_parse_free_children(struct ec_parse *parse);
  45
  46 /**
  47  *
  48  *
  49  *
  50  */
  51 struct ec_parse *ec_parse_dup(const struct ec_parse *parse);
  52
  53 /**
  54  *
  55  *
  56  *
  57  */
  58 const struct ec_strvec *ec_parse_strvec(const struct ec_parse *parse);
  59
  60 /* a NULL return value is an error, with errno set
  61   ENOTSUP: no ->parse() operation
  62 */
  63 /**
  64  *
  65  *
  66  *
  67  */
  68 struct ec_parse *ec_node_parse(const struct ec_node *node, const char *str);
  69
  70 /**
  71  *
  72  *
  73  *
  74  */
  75 struct ec_parse *ec_node_parse_strvec(const struct ec_node *node,
  76                                 const struct ec_strvec *strvec);
  77
  78 /**
  79  *
  80  *
  81  *
  82  */
  83 #define EC_PARSE_NOMATCH INT_MAX
  84
  85 /* internal: used by nodes
  86  *
  87  * state is the current parse tree, which is built piece by piece while
  88  *   parsing the node tree: ec_node_parse_child() creates a new child in
  89  *   this state parse tree, and calls the parse() method for the child
  90  *   node, with state pointing to this new child. If it does not match,
  91  *   the child is removed in the state, else it is kept, with its
  92  *   possible descendants.
  93  *
  94  * return:
  95  * the number of matched strings in strvec on success
  96  * EC_PARSE_NOMATCH (positive) if it does not match
  97  * -1 on error, and errno is set
  98  */
  99 int ec_node_parse_child(const struct ec_node *node,
 100                         struct ec_parse *state,
 101                         const struct ec_strvec *strvec);
 102
 103 /**
 104  *
 105  *
 106  *
 107  */
 108 void ec_parse_link_child(struct ec_parse *parse,
 109                         struct ec_parse *child);
 110 /**
 111  *
 112  *
 113  *
 114  */
 115 void ec_parse_unlink_child(struct ec_parse *parse,
 116                         struct ec_parse *child);
 117
 118 /* keep the const */
 119 #define ec_parse_get_root(parse) ({                             \
 120         const struct ec_parse *p_ = parse; /* check type */     \
 121         struct ec_parse *parse_ = (struct ec_parse *)parse;     \
 122         typeof(parse) res_;                                     \
 123         (void)p_;                                               \
 124         res_ = __ec_parse_get_root(parse_);                     \
 125         res_;                                                   \
 126 })
 127
 128 /**
 129  *
 130  *
 131  *
 132  */
 133 struct ec_parse *__ec_parse_get_root(struct ec_parse *parse);
 134
 135 /**
 136  *
 137  *
 138  *
 139  */
 140 struct ec_parse *ec_parse_get_parent(const struct ec_parse *parse);
 141
 142 /**
 143  * Get the first child of a tree.
 144  *
 145  */
 146 struct ec_parse *ec_parse_get_first_child(const struct ec_parse *parse);
 147
 148 /**
 149  *
 150  *
 151  *
 152  */
 153 struct ec_parse *ec_parse_get_last_child(const struct ec_parse *parse);
 154
 155 /**
 156  *
 157  *
 158  *
 159  */
 160 struct ec_parse *ec_parse_get_next(const struct ec_parse *parse);
 161
 162 /**
 163  *
 164  *
 165  *
 166  */
 167 #define EC_PARSE_FOREACH_CHILD(child, parse)                    \
 168         for (child = ec_parse_get_first_child(parse);           \
 169                 child != NULL;                                  \
 170                 child = ec_parse_get_next(child))               \
 171
 172 /**
 173  *
 174  *
 175  *
 176  */
 177 bool ec_parse_has_child(const struct ec_parse *parse);
 178
 179 /**
 180  *
 181  *
 182  *
 183  */
 184 const struct ec_node *ec_parse_get_node(const struct ec_parse *parse);
 185
 186 /**
 187  *
 188  *
 189  *
 190  */
 191 void ec_parse_del_last_child(struct ec_parse *parse);
 192
 193 /**
 194  *
 195  *
 196  *
 197  */
 198 struct ec_keyval *ec_parse_get_attrs(struct ec_parse *parse);
 199
 200 /**
 201  *
 202  *
 203  *
 204  */
 205 void ec_parse_dump(FILE *out, const struct ec_parse *parse);
 206
 207 /**
 208  *
 209  *
 210  *
 211  */
 212 struct ec_parse *ec_parse_find_first(struct ec_parse *parse,
 213         const char *id);
 214
 215 /**
 216  * Iterate among parse tree
 217  *
 218  * Use it with:
 219  * for (iter = state; iter != NULL; iter = ec_parse_iter_next(iter))
 220  */
 221 struct ec_parse *ec_parse_iter_next(struct ec_parse *parse);
 222
 223 /**
 224  *
 225  *
 226  *
 227  */
 228 size_t ec_parse_len(const struct ec_parse *parse);
 229
 230 /**
 231  *
 232  *
 233  *
 234  */
 235 size_t ec_parse_matches(const struct ec_parse *parse);
 236
 237 #endif