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_load()
  81  *   Build a tree representation of the YAML formatted text in file.
  82  *
  83  *   file - YAML file to parse and build tree representation
  84  */
  85 struct cYAML *cYAML_load(FILE *file, struct cYAML **err_rc, bool debug);
  86
  87 /*
  88  * cYAML_build_tree
  89  *   Build a tree representation of the YAML formatted text passed in.
  90  *
  91  *   path - YAML file to parse and build tree representation
  92  *   yaml_blk - blk of YAML.  yaml_file takes precedence if both
  93  *   are defined.
  94  *   yaml_blk_size - length of the yaml block (obtained via strlen)
  95  */
  96 struct cYAML *cYAML_build_tree(char *path, const char *yaml_blk,
  97                                 size_t yaml_blk_size,
  98                                 struct cYAML **err_str, bool debug);
  99
 100 /*
 101  * cYAML_print_tree
 102  *   Print the textual representation of a YAML tree to stderr
 103  *
 104  *   node - Node where you want to start printing
 105  */
 106 void cYAML_print_tree(struct cYAML *node);
 107
 108 /*
 109  * cYAML_print_tree2file
 110  *   Print the textual representation of a YAML tree to file
 111  *
 112  *   f - file to print to
 113  *   node - Node where you want to start printing
 114  */
 115 void cYAML_print_tree2file(FILE *f, struct cYAML *node);
 116
 117 /*
 118  * cYAML_dump
 119  *   dump YAML to a buffer and return the pointer of the buffer
 120  */
 121 void cYAML_dump(struct cYAML *node, char **buf);
 122
 123 /*
 124  * cYAML_free_tree
 125  *   Free the cYAML tree returned as part of the cYAML_build_tree
 126  *
 127  *   node - root of the tree to be freed
 128  */
 129 void cYAML_free_tree(struct cYAML *node);
 130
 131 /*
 132  * cYAML_get_object_item
 133  *   Returns the cYAML object which key correspods to the name passed in
 134  *   This function searches only through the current level.
 135  *
 136  *   parent - is the parent object on which you want to conduct the search
 137  *   name - key name of the object you want to find.
 138  */
 139 struct cYAML *cYAML_get_object_item(struct cYAML *parent,
 140                                     const char *name);
 141
 142 /*
 143  * cYAML_get_next_seq_item
 144  *   Returns the next item in the YAML sequence.  This function uses the
 145  *   itm parameter to keep track of its position in the sequence.  If the
 146  *   itm parameter is reset to NULL between calls that resets and returns
 147  *   the first item in the sequence.
 148  *   This function returns NULL when there are no more items in the
 149  *   sequence.
 150  *
 151  *   seq - is the head node of the YAML sequence
 152  *   itm - [OUT] next sequence item to continue looking from next time.
 153  *
 154  */
 155 struct cYAML *cYAML_get_next_seq_item(struct cYAML *seq,
 156                                       struct cYAML **itm);
 157
 158 /*
 159  * cYAML_is_seq
 160  *   Returns 1 if the node provided is an ARRAY 0 otherwise
 161  *
 162  *   node - the node to examine
 163  *
 164  */
 165 bool cYAML_is_sequence(struct cYAML *node);
 166
 167 /*
 168  * cYAML_find_object
 169  *   Returns the cYAML object which key correspods to the name passed in
 170  *   this function searches the entire tree.
 171  *
 172  *   root - is the root of the tree on which you want to conduct the search
 173  *   name - key name of the object you want to find.
 174  */
 175 struct cYAML *cYAML_find_object(struct cYAML *root, const char *key);
 176
 177 /*
 178  * cYAML_clean_usr_data
 179  *   walks the tree and for each node with some user data it calls the
 180  *   free_cb with the user data as a parameter.
 181  *
 182  *   node: node to start the walk from
 183  *   free_cb: cb to call to cleanup the user data
 184  */
 185 void cYAML_clean_usr_data(struct cYAML *node,
 186                           cYAML_user_data_free_cb free_cb);
 187
 188 /*
 189  * cYAML_create_object
 190  *  Creates a CYAML of type OBJECT
 191  *
 192  *  parent - parent node
 193  *  key - node key
 194  */
 195 struct cYAML *cYAML_create_object(struct cYAML *parent, char *key);
 196
 197 /*
 198  * cYAML_create_seq
 199  *  Creates a CYAML of type ARRAY
 200  *  Once this is created, more sequence items can be added.
 201  *
 202  *  parent - parent node
 203  *  key - node key
 204  */
 205 struct cYAML *cYAML_create_seq(struct cYAML *parent, char *key);
 206
 207 /*
 208  * cYAML_create_object
 209  *  Create a sequence item, which can have more entites added underneath
 210  *  it
 211  *
 212  *  parent - parent node
 213  */
 214 struct cYAML *cYAML_create_seq_item(struct cYAML *seq);
 215
 216 /*
 217  * cYAML_create_string
 218  *   Creates a cYAML node of type STRING
 219  *
 220  *   parent - parent node
 221  *   key - node key
 222  *   value - value of node
 223  */
 224 struct cYAML *cYAML_create_string(struct cYAML *parent, char *key,
 225                                   char *value);
 226
 227 /*
 228  * cYAML_create_string
 229  *   Creates a cYAML node of type STRING
 230  *
 231  *   parent - parent node
 232  *   key - node key
 233  *   value - value of node
 234  */
 235 struct cYAML *cYAML_create_number(struct cYAML *parent, char *key,
 236                                   double value);
 237
 238 /*
 239  * cYAML_insert_sibling
 240  *   inserts one cYAML object as a sibling to another
 241  *
 242  *   root - root node to have a sibling added to
 243  *   sibling - sibling to be added
 244  */
 245 void cYAML_insert_sibling(struct cYAML *root, struct cYAML *sibling);
 246
 247 /*
 248  * cYAML_insert_child
 249  *   inserts one cYAML object as a child to another
 250  *
 251  *   parent - parent node to have a child added to
 252  *   child - child to be added
 253  */
 254 void cYAML_insert_child(struct cYAML *parent, struct cYAML *node);
 255
 256 /*
 257  * cYAML_build_error
 258  *   Build a YAML error message given:
 259  *
 260  *   rc - return code to add in the error
 261  *   seq_no - a sequence number to add in the error
 262  *   cmd - the command that failed.
 263  *   entity - command entity that failed.
 264  *   err_str - error string to add in the error
 265  *   root - the root to which to add the YAML error
 266  */
 267 void cYAML_build_error(int rc, int seq_no, char *cmd,
 268                         char *entity, char *err_str,
 269                         struct cYAML **root);
 270
 271
 272 #endif /* CYAML_H */