lib/ecoli_parsed.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  * Node parse API.
  30  *
  31  * The parse operation is to check if an input (a string or vector of
  32  * strings) matches the node tree. On success, the result is stored in a
  33  * tree that describes which part of the input matches which node.
  34  */
  35
  36 #ifndef ECOLI_PARSED_
  37 #define ECOLI_PARSED_
  38
  39 #include <sys/queue.h>
  40 #include <sys/types.h>
  41 #include <limits.h>
  42 #include <stdio.h>
  43
  44 struct ec_node;
  45 struct ec_parsed;
  46
  47 /**
  48  * Create an empty parse tree.
  49  *
  50  * @return
  51  *   The empty parse tree.
  52  */
  53 struct ec_parsed *ec_parsed(const struct ec_node *node);
  54
  55 /**
  56  *
  57  *
  58  *
  59  */
  60 void ec_parsed_free(struct ec_parsed *parsed);
  61
  62 /**
  63  *
  64  *
  65  *
  66  */
  67 void ec_parsed_free_children(struct ec_parsed *parsed);
  68
  69 /**
  70  *
  71  *
  72  *
  73  */
  74 struct ec_parsed *ec_parsed_dup(struct ec_parsed *parsed);
  75
  76 /**
  77  *
  78  *
  79  *
  80  */
  81 const struct ec_strvec *ec_parsed_strvec(const struct ec_parsed *parsed);
  82
  83 /* a NULL return value is an error, with errno set
  84   ENOTSUP: no ->parse() operation
  85 */
  86 /**
  87  *
  88  *
  89  *
  90  */
  91 struct ec_parsed *ec_node_parse(const struct ec_node *node, const char *str);
  92
  93 /**
  94  *
  95  *
  96  *
  97  */
  98 struct ec_parsed *ec_node_parse_strvec(const struct ec_node *node,
  99                                 const struct ec_strvec *strvec);
 100
 101 /**
 102  *
 103  *
 104  *
 105  */
 106 #define EC_PARSED_NOMATCH INT_MAX
 107
 108 /* internal: used by nodes
 109  *
 110  * state is the current parse tree, which is built piece by piece while
 111  *   parsing the node tree: ec_node_parse_child() creates a new child in
 112  *   this state parse tree, and calls the parse() method for the child
 113  *   node, with state pointing to this new child. If it does not match,
 114  *   the child is removed in the state, else it is kept, with its
 115  *   possible descendants.
 116  *
 117  * return:
 118  * EC_PARSED_NOMATCH (positive) if it does not match
 119  * any other negative value (-errno) for other errors
 120  * the number of matched strings in strvec
 121  */
 122 int ec_node_parse_child(const struct ec_node *node,
 123                         struct ec_parsed *state,
 124                         const struct ec_strvec *strvec);
 125
 126 /**
 127  *
 128  *
 129  *
 130  */
 131 void ec_parsed_add_child(struct ec_parsed *parsed,
 132                         struct ec_parsed *child);
 133 /**
 134  *
 135  *
 136  *
 137  */
 138 void ec_parsed_del_child(struct ec_parsed *parsed,
 139                         struct ec_parsed *child);
 140
 141 /**
 142  *
 143  *
 144  *
 145  */
 146 struct ec_parsed *ec_parsed_get_root(struct ec_parsed *parsed);
 147
 148 /**
 149  *
 150  *
 151  *
 152  */
 153 struct ec_parsed *ec_parsed_get_parent(struct ec_parsed *parsed);
 154
 155 /**
 156  * Get the first child of a tree.
 157  *
 158  */
 159 struct ec_parsed *ec_parsed_get_first_child(const struct ec_parsed *parsed);
 160
 161 /**
 162  *
 163  *
 164  *
 165  */
 166 struct ec_parsed *ec_parsed_get_last_child(const struct ec_parsed *parsed);
 167
 168 /**
 169  *
 170  *
 171  *
 172  */
 173 struct ec_parsed *ec_parsed_get_next(const struct ec_parsed *parsed);
 174
 175 /**
 176  *
 177  *
 178  *
 179  */
 180 #define EC_PARSED_FOREACH_CHILD(child, parsed)                  \
 181         for (child = ec_parsed_get_first_child(parsed);         \
 182                 child != NULL;                                  \
 183                 child = ec_parsed_get_next(child))              \
 184
 185 /**
 186  *
 187  *
 188  *
 189  */
 190 bool ec_parsed_has_child(const struct ec_parsed *parsed);
 191
 192 /**
 193  *
 194  *
 195  *
 196  */
 197 const struct ec_node *ec_parsed_get_node(const struct ec_parsed *parsed);
 198
 199 /**
 200  *
 201  *
 202  *
 203  */
 204 void ec_parsed_del_last_child(struct ec_parsed *parsed);
 205
 206 /**
 207  *
 208  *
 209  *
 210  */
 211 struct ec_keyval *ec_parsed_get_attrs(struct ec_parsed *parsed);
 212
 213 /**
 214  *
 215  *
 216  *
 217  */
 218 void ec_parsed_dump(FILE *out, const struct ec_parsed *parsed);
 219
 220 /**
 221  *
 222  *
 223  *
 224  */
 225 struct ec_parsed *ec_parsed_find_first(struct ec_parsed *parsed,
 226         const char *id);
 227
 228 /**
 229  * Iterate among parsed tree
 230  *
 231  * Use it with:
 232  * for (iter = state; iter != NULL; iter = ec_parsed_iter_next(iter))
 233  */
 234 struct ec_parsed *ec_parsed_iter_next(struct ec_parsed *parsed);
 235
 236 /**
 237  *
 238  *
 239  *
 240  */
 241 size_t ec_parsed_len(const struct ec_parsed *parsed);
 242
 243 /**
 244  *
 245  *
 246  *
 247  */
 248 size_t ec_parsed_matches(const struct ec_parsed *parsed);
 249
 250 #endif