lnet/utils/lnetconfig/cyaml.h

   1 /*
   2  * LGPL HEADER START
   3  *
   4  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU Lesser General Public License as
   8  * published by the Free Software Foundation; either version 2.1 of the
   9  * License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  18  *
  19  * LGPL HEADER END
  20  *
  21  * Copyright (c) 2014, 2017, Intel Corporation.
  22  *
  23  * Author:
  24  *   Amir Shehata <amir.shehata@intel.com>
  25  */
  26
  27 #ifndef CYAML_H
  28 #define CYAML_H
  29
  30 #include <inttypes.h>
  31 #include <stdbool.h>
  32
  33 enum cYAML_object_type {
  34         CYAML_TYPE_FALSE = 0,
  35         CYAML_TYPE_TRUE,
  36         CYAML_TYPE_NULL,
  37         CYAML_TYPE_NUMBER,
  38         CYAML_TYPE_STRING,
  39         CYAML_TYPE_ARRAY,
  40         CYAML_TYPE_OBJECT
  41 };
  42
  43 struct cYAML {
  44         /* next/prev allow you to walk array/object chains. */
  45         struct cYAML *cy_next, *cy_prev;
  46         /* An array or object item will have a child pointer pointing
  47            to a chain of the items in the array/object. */
  48         struct cYAML *cy_child;
  49         /* The type of the item, as above. */
  50         enum cYAML_object_type cy_type;
  51
  52         /* The item's string, if type==CYAML_TYPE_STRING */
  53         char *cy_valuestring;
  54         /* The item's number, if type==CYAML_TYPE_NUMBER */
  55         int64_t cy_valueint;
  56         /* The item's number, if type==CYAML_TYPE_NUMBER */
  57         double cy_valuedouble;
  58         /* The item's name string, if this item is the child of,
  59            or is in the list of subitems of an object. */
  60         char *cy_string;
  61         /* user data which might need to be tracked per object */
  62         void *cy_user_data;
  63 };
  64
  65 typedef void (*cYAML_user_data_free_cb)(void *);
  66
  67 /*
  68  * cYAML_walk_cb
  69  *   Callback called when recursing through the tree
  70  *
  71  *   cYAML* - pointer to the node currently being visitied
  72  *   void* - user data passed to the callback.
  73  *   void** - output value from the callback
  74  *
  75  * Returns true to continue recursing.  false to stop recursing
  76  */
  77 typedef bool (*cYAML_walk_cb)(struct cYAML *, void *, void**);
  78
  79 /*
  80  * cYAML_build_tree
  81  *   Build a tree representation of the YAML formatted text passed in.
  82  *
  83  *   yaml_file - YAML file to parse and build tree representation
  84  *   yaml_blk - blk of YAML.  yaml_file takes precedence if both
  85  *   are defined.
  86  *   yaml_blk_size - length of the yaml block (obtained via strlen)
  87  */
  88 struct cYAML *cYAML_build_tree(char *yaml_file, const char *yaml_blk,
  89                                 size_t yaml_blk_size,
  90                                 struct cYAML **err_str, bool debug);
  91
  92 /*
  93  * cYAML_print_tree
  94  *   Print the textual representation of a YAML tree to stderr
  95  *
  96  *   node - Node where you want to start printing
  97  */
  98 void cYAML_print_tree(struct cYAML *node);
  99
 100 /*
 101  * cYAML_print_tree2file
 102  *   Print the textual representation of a YAML tree to file
 103  *
 104  *   f - file to print to
 105  *   node - Node where you want to start printing
 106  */
 107 void cYAML_print_tree2file(FILE *f, struct cYAML *node);
 108
 109 /*
 110  * cYAML_dump
 111  *   dump YAML to a buffer and return the pointer of the buffer
 112  */
 113 void cYAML_dump(struct cYAML *node, char **buf);
 114
 115 /*
 116  * cYAML_free_tree
 117  *   Free the cYAML tree returned as part of the cYAML_build_tree
 118  *
 119  *   node - root of the tree to be freed
 120  */
 121 void cYAML_free_tree(struct cYAML *node);
 122
 123 /*
 124  * cYAML_get_object_item
 125  *   Returns the cYAML object which key correspods to the name passed in
 126  *   This function searches only through the current level.
 127  *
 128  *   parent - is the parent object on which you want to conduct the search
 129  *   name - key name of the object you want to find.
 130  */
 131 struct cYAML *cYAML_get_object_item(struct cYAML *parent,
 132                                     const char *name);
 133
 134 /*
 135  * cYAML_get_next_seq_item
 136  *   Returns the next item in the YAML sequence.  This function uses the
 137  *   itm parameter to keep track of its position in the sequence.  If the
 138  *   itm parameter is reset to NULL between calls that resets and returns
 139  *   the first item in the sequence.
 140  *   This function returns NULL when there are no more items in the
 141  *   sequence.
 142  *
 143  *   seq - is the head node of the YAML sequence
 144  *   itm - [OUT] next sequence item to continue looking from next time.
 145  *
 146  */
 147 struct cYAML *cYAML_get_next_seq_item(struct cYAML *seq,
 148                                       struct cYAML **itm);
 149
 150 /*
 151  * cYAML_is_seq
 152  *   Returns 1 if the node provided is an ARRAY 0 otherwise
 153  *
 154  *   node - the node to examine
 155  *
 156  */
 157 bool cYAML_is_sequence(struct cYAML *node);
 158
 159 /*
 160  * cYAML_find_object
 161  *   Returns the cYAML object which key correspods to the name passed in
 162  *   this function searches the entire tree.
 163  *
 164  *   root - is the root of the tree on which you want to conduct the search
 165  *   name - key name of the object you want to find.
 166  */
 167 struct cYAML *cYAML_find_object(struct cYAML *root, const char *key);
 168
 169 /*
 170  * cYAML_clean_usr_data
 171  *   walks the tree and for each node with some user data it calls the
 172  *   free_cb with the user data as a parameter.
 173  *
 174  *   node: node to start the walk from
 175  *   free_cb: cb to call to cleanup the user data
 176  */
 177 void cYAML_clean_usr_data(struct cYAML *node,
 178                           cYAML_user_data_free_cb free_cb);
 179
 180 /*
 181  * cYAML_create_object
 182  *  Creates a CYAML of type OBJECT
 183  *
 184  *  parent - parent node
 185  *  key - node key
 186  */
 187 struct cYAML *cYAML_create_object(struct cYAML *parent, char *key);
 188
 189 /*
 190  * cYAML_create_seq
 191  *  Creates a CYAML of type ARRAY
 192  *  Once this is created, more sequence items can be added.
 193  *
 194  *  parent - parent node
 195  *  key - node key
 196  */
 197 struct cYAML *cYAML_create_seq(struct cYAML *parent, char *key);
 198
 199 /*
 200  * cYAML_create_object
 201  *  Create a sequence item, which can have more entites added underneath
 202  *  it
 203  *
 204  *  parent - parent node
 205  */
 206 struct cYAML *cYAML_create_seq_item(struct cYAML *seq);
 207
 208 /*
 209  * cYAML_create_string
 210  *   Creates a cYAML node of type STRING
 211  *
 212  *   parent - parent node
 213  *   key - node key
 214  *   value - value of node
 215  */
 216 struct cYAML *cYAML_create_string(struct cYAML *parent, char *key,
 217                                   char *value);
 218
 219 /*
 220  * cYAML_create_string
 221  *   Creates a cYAML node of type STRING
 222  *
 223  *   parent - parent node
 224  *   key - node key
 225  *   value - value of node
 226  */
 227 struct cYAML *cYAML_create_number(struct cYAML *parent, char *key,
 228                                   double value);
 229
 230 /*
 231  * cYAML_insert_sibling
 232  *   inserts one cYAML object as a sibling to another
 233  *
 234  *   root - root node to have a sibling added to
 235  *   sibling - sibling to be added
 236  */
 237 void cYAML_insert_sibling(struct cYAML *root, struct cYAML *sibling);
 238
 239 /*
 240  * cYAML_insert_child
 241  *   inserts one cYAML object as a child to another
 242  *
 243  *   parent - parent node to have a child added to
 244  *   child - child to be added
 245  */
 246 void cYAML_insert_child(struct cYAML *parent, struct cYAML *node);
 247
 248 /*
 249  * cYAML_build_error
 250  *   Build a YAML error message given:
 251  *
 252  *   rc - return code to add in the error
 253  *   seq_no - a sequence number to add in the error
 254  *   cmd - the command that failed.
 255  *   entity - command entity that failed.
 256  *   err_str - error string to add in the error
 257  *   root - the root to which to add the YAML error
 258  */
 259 void cYAML_build_error(int rc, int seq_no, char *cmd,
 260                         char *entity, char *err_str,
 261                         struct cYAML **root);
 262
 263
 264 #endif /* CYAML_H */