lib/ecoli_parsed.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_PARSED_
  14 #define ECOLI_PARSED_
  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_parsed;
  23
  24 /**
  25  * Create an empty parse tree.
  26  *
  27  * @return
  28  *   The empty parse tree.
  29  */
  30 struct ec_parsed *ec_parsed(const struct ec_node *node);
  31
  32 /**
  33  *
  34  *
  35  *
  36  */
  37 void ec_parsed_free(struct ec_parsed *parsed);
  38
  39 /**
  40  *
  41  *
  42  *
  43  */
  44 void ec_parsed_free_children(struct ec_parsed *parsed);
  45
  46 /**
  47  *
  48  *
  49  *
  50  */
  51 struct ec_parsed *ec_parsed_dup(struct ec_parsed *parsed);
  52
  53 /**
  54  *
  55  *
  56  *
  57  */
  58 const struct ec_strvec *ec_parsed_strvec(const struct ec_parsed *parsed);
  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_parsed *ec_node_parse(const struct ec_node *node, const char *str);
  69
  70 /**
  71  *
  72  *
  73  *
  74  */
  75 struct ec_parsed *ec_node_parse_strvec(const struct ec_node *node,
  76                                 const struct ec_strvec *strvec);
  77
  78 /**
  79  *
  80  *
  81  *
  82  */
  83 #define EC_PARSED_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  * EC_PARSED_NOMATCH (positive) if it does not match
  96  * any other negative value (-errno) for other errors
  97  * the number of matched strings in strvec
  98  */
  99 int ec_node_parse_child(const struct ec_node *node,
 100                         struct ec_parsed *state,
 101                         const struct ec_strvec *strvec);
 102
 103 /**
 104  *
 105  *
 106  *
 107  */
 108 void ec_parsed_add_child(struct ec_parsed *parsed,
 109                         struct ec_parsed *child);
 110 /**
 111  *
 112  *
 113  *
 114  */
 115 void ec_parsed_del_child(struct ec_parsed *parsed,
 116                         struct ec_parsed *child);
 117
 118 /**
 119  *
 120  *
 121  *
 122  */
 123 struct ec_parsed *ec_parsed_get_root(struct ec_parsed *parsed);
 124
 125 /**
 126  *
 127  *
 128  *
 129  */
 130 struct ec_parsed *ec_parsed_get_parent(struct ec_parsed *parsed);
 131
 132 /**
 133  * Get the first child of a tree.
 134  *
 135  */
 136 struct ec_parsed *ec_parsed_get_first_child(const struct ec_parsed *parsed);
 137
 138 /**
 139  *
 140  *
 141  *
 142  */
 143 struct ec_parsed *ec_parsed_get_last_child(const struct ec_parsed *parsed);
 144
 145 /**
 146  *
 147  *
 148  *
 149  */
 150 struct ec_parsed *ec_parsed_get_next(const struct ec_parsed *parsed);
 151
 152 /**
 153  *
 154  *
 155  *
 156  */
 157 #define EC_PARSED_FOREACH_CHILD(child, parsed)                  \
 158         for (child = ec_parsed_get_first_child(parsed);         \
 159                 child != NULL;                                  \
 160                 child = ec_parsed_get_next(child))              \
 161
 162 /**
 163  *
 164  *
 165  *
 166  */
 167 bool ec_parsed_has_child(const struct ec_parsed *parsed);
 168
 169 /**
 170  *
 171  *
 172  *
 173  */
 174 const struct ec_node *ec_parsed_get_node(const struct ec_parsed *parsed);
 175
 176 /**
 177  *
 178  *
 179  *
 180  */
 181 void ec_parsed_del_last_child(struct ec_parsed *parsed);
 182
 183 /**
 184  *
 185  *
 186  *
 187  */
 188 struct ec_keyval *ec_parsed_get_attrs(struct ec_parsed *parsed);
 189
 190 /**
 191  *
 192  *
 193  *
 194  */
 195 void ec_parsed_dump(FILE *out, const struct ec_parsed *parsed);
 196
 197 /**
 198  *
 199  *
 200  *
 201  */
 202 struct ec_parsed *ec_parsed_find_first(struct ec_parsed *parsed,
 203         const char *id);
 204
 205 /**
 206  * Iterate among parsed tree
 207  *
 208  * Use it with:
 209  * for (iter = state; iter != NULL; iter = ec_parsed_iter_next(iter))
 210  */
 211 struct ec_parsed *ec_parsed_iter_next(struct ec_parsed *parsed);
 212
 213 /**
 214  *
 215  *
 216  *
 217  */
 218 size_t ec_parsed_len(const struct ec_parsed *parsed);
 219
 220 /**
 221  *
 222  *
 223  *
 224  */
 225 size_t ec_parsed_matches(const struct ec_parsed *parsed);
 226
 227 #endif