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 /* XXX we could use a cache to store possible completions or match: the
  84  * cache would be per-node, and would be reset for each call to parse()
  85  * or complete() ? ... not sure, since parse result can depend on state
  86  */
  87 /* a NULL return value is an error, with errno set
  88   ENOTSUP: no ->parse() operation
  89 */
  90 /**
  91  *
  92  *
  93  *
  94  */
  95 struct ec_parsed *ec_node_parse(struct ec_node *node, const char *str);
  96
  97 /**
  98  *
  99  *
 100  *
 101  */
 102 struct ec_parsed *ec_node_parse_strvec(struct ec_node *node,
 103                                 const struct ec_strvec *strvec);
 104
 105 /**
 106  *
 107  *
 108  *
 109  */
 110 #define EC_PARSED_NOMATCH INT_MAX
 111
 112 /* internal: used by nodes
 113  *
 114  * state is the current parse tree, which is built piece by piece while
 115  *   parsing the node tree: ec_node_parse_child() creates a new child in
 116  *   this state parse tree, and calls the parse() method for the child
 117  *   node, with state pointing to this new child. If it does not match,
 118  *   the child is removed in the state, else it is kept, with its
 119  *   possible descendants.
 120  *
 121  * return:
 122  * EC_PARSED_NOMATCH (positive) if it does not match
 123  * any other negative value (-errno) for other errors
 124  * the number of matched strings in strvec
 125  * XXX state is not freed on error ?
 126  */
 127 int ec_node_parse_child(struct ec_node *node,
 128                         struct ec_parsed *state,
 129                         const struct ec_strvec *strvec);
 130
 131 /**
 132  *
 133  *
 134  *
 135  */
 136 void ec_parsed_add_child(struct ec_parsed *parsed,
 137                         struct ec_parsed *child);
 138 /**
 139  *
 140  *
 141  *
 142  */
 143 void ec_parsed_del_child(struct ec_parsed *parsed,
 144                         struct ec_parsed *child);
 145
 146 /**
 147  *
 148  *
 149  *
 150  */
 151 struct ec_parsed *ec_parsed_get_root(struct ec_parsed *parsed);
 152
 153 /**
 154  *
 155  *
 156  *
 157  */
 158 struct ec_parsed *ec_parsed_get_parent(struct ec_parsed *parsed);
 159
 160 /**
 161  * Get the first child of a tree.
 162  *
 163  */
 164 struct ec_parsed *ec_parsed_get_first_child(const struct ec_parsed *parsed);
 165
 166 /**
 167  *
 168  *
 169  *
 170  */
 171 struct ec_parsed *ec_parsed_get_last_child(const struct ec_parsed *parsed);
 172
 173 /**
 174  *
 175  *
 176  *
 177  */
 178 struct ec_parsed *ec_parsed_get_next(const struct ec_parsed *parsed);
 179
 180 /**
 181  *
 182  *
 183  *
 184  */
 185 #define EC_PARSED_FOREACH_CHILD(child, parsed)                  \
 186         for (child = ec_parsed_get_first_child(parsed);         \
 187                 child != NULL;                                  \
 188                 child = ec_parsed_get_next(child))              \
 189
 190 /**
 191  *
 192  *
 193  *
 194  */
 195 bool ec_parsed_has_child(const struct ec_parsed *parsed);
 196
 197 /**
 198  *
 199  *
 200  *
 201  */
 202 const struct ec_node *ec_parsed_get_node(const struct ec_parsed *parsed);
 203
 204 /**
 205  *
 206  *
 207  *
 208  */
 209 void ec_parsed_del_last_child(struct ec_parsed *parsed);
 210
 211 /**
 212  *
 213  *
 214  *
 215  */
 216 struct ec_keyval *ec_parsed_get_attrs(struct ec_parsed *parsed);
 217
 218 /**
 219  *
 220  *
 221  *
 222  */
 223 void ec_parsed_dump(FILE *out, const struct ec_parsed *parsed);
 224
 225 /**
 226  *
 227  *
 228  *
 229  */
 230 struct ec_parsed *ec_parsed_find_first(struct ec_parsed *parsed,
 231         const char *id);
 232
 233 /**
 234  * Iterate among parsed tree
 235  *
 236  * Use it with:
 237  * for (iter = state; iter != NULL; iter = ec_parsed_iter_next(iter))
 238  */
 239 struct ec_parsed *ec_parsed_iter_next(struct ec_parsed *parsed);
 240
 241 /**
 242  *
 243  *
 244  *
 245  */
 246 size_t ec_parsed_len(const struct ec_parsed *parsed);
 247
 248 /**
 249  *
 250  *
 251  *
 252  */
 253 size_t ec_parsed_matches(const struct ec_parsed *parsed);
 254
 255 #endif