lnet/include/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_free_tree
 111  *   Free the cYAML tree returned as part of the cYAML_build_tree
 112  *
 113  *   node - root of the tree to be freed
 114  */
 115 void cYAML_free_tree(struct cYAML *node);
 116
 117 /*
 118  * cYAML_get_object_item
 119  *   Returns the cYAML object which key correspods to the name passed in
 120  *   This function searches only through the current level.
 121  *
 122  *   parent - is the parent object on which you want to conduct the search
 123  *   name - key name of the object you want to find.
 124  */
 125 struct cYAML *cYAML_get_object_item(struct cYAML *parent,
 126                                     const char *name);
 127
 128 /*
 129  * cYAML_get_next_seq_item
 130  *   Returns the next item in the YAML sequence.  This function uses the
 131  *   itm parameter to keep track of its position in the sequence.  If the
 132  *   itm parameter is reset to NULL between calls that resets and returns
 133  *   the first item in the sequence.
 134  *   This function returns NULL when there are no more items in the
 135  *   sequence.
 136  *
 137  *   seq - is the head node of the YAML sequence
 138  *   itm - [OUT] next sequence item to continue looking from next time.
 139  *
 140  */
 141 struct cYAML *cYAML_get_next_seq_item(struct cYAML *seq,
 142                                       struct cYAML **itm);
 143
 144 /*
 145  * cYAML_is_seq
 146  *   Returns 1 if the node provided is an ARRAY 0 otherwise
 147  *
 148  *   node - the node to examine
 149  *
 150  */
 151 bool cYAML_is_sequence(struct cYAML *node);
 152
 153 /*
 154  * cYAML_find_object
 155  *   Returns the cYAML object which key correspods to the name passed in
 156  *   this function searches the entire tree.
 157  *
 158  *   root - is the root of the tree on which you want to conduct the search
 159  *   name - key name of the object you want to find.
 160  */
 161 struct cYAML *cYAML_find_object(struct cYAML *root, const char *key);
 162
 163 /*
 164  * cYAML_clean_usr_data
 165  *   walks the tree and for each node with some user data it calls the
 166  *   free_cb with the user data as a parameter.
 167  *
 168  *   node: node to start the walk from
 169  *   free_cb: cb to call to cleanup the user data
 170  */
 171 void cYAML_clean_usr_data(struct cYAML *node,
 172                           cYAML_user_data_free_cb free_cb);
 173
 174 /*
 175  * cYAML_create_object
 176  *  Creates a CYAML of type OBJECT
 177  *
 178  *  parent - parent node
 179  *  key - node key
 180  */
 181 struct cYAML *cYAML_create_object(struct cYAML *parent, char *key);
 182
 183 /*
 184  * cYAML_create_seq
 185  *  Creates a CYAML of type ARRAY
 186  *  Once this is created, more sequence items can be added.
 187  *
 188  *  parent - parent node
 189  *  key - node key
 190  */
 191 struct cYAML *cYAML_create_seq(struct cYAML *parent, char *key);
 192
 193 /*
 194  * cYAML_create_object
 195  *  Create a sequence item, which can have more entites added underneath
 196  *  it
 197  *
 198  *  parent - parent node
 199  */
 200 struct cYAML *cYAML_create_seq_item(struct cYAML *seq);
 201
 202 /*
 203  * cYAML_create_string
 204  *   Creates a cYAML node of type STRING
 205  *
 206  *   parent - parent node
 207  *   key - node key
 208  *   value - value of node
 209  */
 210 struct cYAML *cYAML_create_string(struct cYAML *parent, char *key,
 211                                   char *value);
 212
 213 /*
 214  * cYAML_create_string
 215  *   Creates a cYAML node of type STRING
 216  *
 217  *   parent - parent node
 218  *   key - node key
 219  *   value - value of node
 220  */
 221 struct cYAML *cYAML_create_number(struct cYAML *parent, char *key,
 222                                   double value);
 223
 224 /*
 225  * cYAML_insert_sibling
 226  *   inserts one cYAML object as a sibling to another
 227  *
 228  *   root - root node to have a sibling added to
 229  *   sibling - sibling to be added
 230  */
 231 void cYAML_insert_sibling(struct cYAML *root, struct cYAML *sibling);
 232
 233 /*
 234  * cYAML_insert_child
 235  *   inserts one cYAML object as a child to another
 236  *
 237  *   parent - parent node to have a child added to
 238  *   child - child to be added
 239  */
 240 void cYAML_insert_child(struct cYAML *parent, struct cYAML *node);
 241
 242 /*
 243  * cYAML_build_error
 244  *   Build a YAML error message given:
 245  *
 246  *   rc - return code to add in the error
 247  *   seq_no - a sequence number to add in the error
 248  *   cmd - the command that failed.
 249  *   entity - command entity that failed.
 250  *   err_str - error string to add in the error
 251  *   root - the root to which to add the YAML error
 252  */
 253 void cYAML_build_error(int rc, int seq_no, char *cmd,
 254                         char *entity, char *err_str,
 255                         struct cYAML **root);
 256
 257
 258 #endif /* CYAML_H */