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 <stdbool.h>
  31
  32 enum cYAML_object_type {
  33         CYAML_TYPE_FALSE = 0,
  34         CYAML_TYPE_TRUE,
  35         CYAML_TYPE_NULL,
  36         CYAML_TYPE_NUMBER,
  37         CYAML_TYPE_STRING,
  38         CYAML_TYPE_ARRAY,
  39         CYAML_TYPE_OBJECT
  40 };
  41
  42 struct cYAML {
  43         /* next/prev allow you to walk array/object chains. */
  44         struct cYAML *cy_next, *cy_prev;
  45         /* An array or object item will have a child pointer pointing
  46            to a chain of the items in the array/object. */
  47         struct cYAML *cy_child;
  48         /* The type of the item, as above. */
  49         enum cYAML_object_type cy_type;
  50
  51         /* The item's string, if type==CYAML_TYPE_STRING */
  52         char *cy_valuestring;
  53         /* The item's number, if type==CYAML_TYPE_NUMBER */
  54         int cy_valueint;
  55         /* The item's number, if type==CYAML_TYPE_NUMBER */
  56         double cy_valuedouble;
  57         /* The item's name string, if this item is the child of,
  58            or is in the list of subitems of an object. */
  59         char *cy_string;
  60         /* user data which might need to be tracked per object */
  61         void *cy_user_data;
  62 };
  63
  64 typedef void (*cYAML_user_data_free_cb)(void *);
  65
  66 /*
  67  * cYAML_walk_cb
  68  *   Callback called when recursing through the tree
  69  *
  70  *   cYAML* - pointer to the node currently being visitied
  71  *   void* - user data passed to the callback.
  72  *   void** - output value from the callback
  73  *
  74  * Returns true to continue recursing.  false to stop recursing
  75  */
  76 typedef bool (*cYAML_walk_cb)(struct cYAML *, void *, void**);
  77
  78 /*
  79  * cYAML_build_tree
  80  *   Build a tree representation of the YAML formatted text passed in.
  81  *
  82  *   yaml_file - YAML file to parse and build tree representation
  83  *   yaml_blk - blk of YAML.  yaml_file takes precedence if both
  84  *   are defined.
  85  *   yaml_blk_size - length of the yaml block (obtained via strlen)
  86  */
  87 struct cYAML *cYAML_build_tree(char *yaml_file, const char *yaml_blk,
  88                                 size_t yaml_blk_size,
  89                                 struct cYAML **err_str, bool debug);
  90
  91 /*
  92  * cYAML_print_tree
  93  *   Print the textual representation of a YAML tree to stderr
  94  *
  95  *   node - Node where you want to start printing
  96  */
  97 void cYAML_print_tree(struct cYAML *node);
  98
  99 /*
 100  * cYAML_print_tree2file
 101  *   Print the textual representation of a YAML tree to file
 102  *
 103  *   f - file to print to
 104  *   node - Node where you want to start printing
 105  */
 106 void cYAML_print_tree2file(FILE *f, struct cYAML *node);
 107
 108 /*
 109  * cYAML_free_tree
 110  *   Free the cYAML tree returned as part of the cYAML_build_tree
 111  *
 112  *   node - root of the tree to be freed
 113  */
 114 void cYAML_free_tree(struct cYAML *node);
 115
 116 /*
 117  * cYAML_get_object_item
 118  *   Returns the cYAML object which key correspods to the name passed in
 119  *   This function searches only through the current level.
 120  *
 121  *   parent - is the parent object on which you want to conduct the search
 122  *   name - key name of the object you want to find.
 123  */
 124 struct cYAML *cYAML_get_object_item(struct cYAML *parent,
 125                                     const char *name);
 126
 127 /*
 128  * cYAML_get_next_seq_item
 129  *   Returns the next item in the YAML sequence.  This function uses the
 130  *   itm parameter to keep track of its position in the sequence.  If the
 131  *   itm parameter is reset to NULL between calls that resets and returns
 132  *   the first item in the sequence.
 133  *   This function returns NULL when there are no more items in the
 134  *   sequence.
 135  *
 136  *   seq - is the head node of the YAML sequence
 137  *   itm - [OUT] next sequence item to continue looking from next time.
 138  *
 139  */
 140 struct cYAML *cYAML_get_next_seq_item(struct cYAML *seq,
 141                                       struct cYAML **itm);
 142
 143 /*
 144  * cYAML_is_seq
 145  *   Returns 1 if the node provided is an ARRAY 0 otherwise
 146  *
 147  *   node - the node to examine
 148  *
 149  */
 150 bool cYAML_is_sequence(struct cYAML *node);
 151
 152 /*
 153  * cYAML_find_object
 154  *   Returns the cYAML object which key correspods to the name passed in
 155  *   this function searches the entire tree.
 156  *
 157  *   root - is the root of the tree on which you want to conduct the search
 158  *   name - key name of the object you want to find.
 159  */
 160 struct cYAML *cYAML_find_object(struct cYAML *root, const char *key);
 161
 162 /*
 163  * cYAML_clean_usr_data
 164  *   walks the tree and for each node with some user data it calls the
 165  *   free_cb with the user data as a parameter.
 166  *
 167  *   node: node to start the walk from
 168  *   free_cb: cb to call to cleanup the user data
 169  */
 170 void cYAML_clean_usr_data(struct cYAML *node,
 171                           cYAML_user_data_free_cb free_cb);
 172
 173 /*
 174  * cYAML_create_object
 175  *  Creates a CYAML of type OBJECT
 176  *
 177  *  parent - parent node
 178  *  key - node key
 179  */
 180 struct cYAML *cYAML_create_object(struct cYAML *parent, char *key);
 181
 182 /*
 183  * cYAML_create_seq
 184  *  Creates a CYAML of type ARRAY
 185  *  Once this is created, more sequence items can be added.
 186  *
 187  *  parent - parent node
 188  *  key - node key
 189  */
 190 struct cYAML *cYAML_create_seq(struct cYAML *parent, char *key);
 191
 192 /*
 193  * cYAML_create_object
 194  *  Create a sequence item, which can have more entites added underneath
 195  *  it
 196  *
 197  *  parent - parent node
 198  */
 199 struct cYAML *cYAML_create_seq_item(struct cYAML *seq);
 200
 201 /*
 202  * cYAML_create_string
 203  *   Creates a cYAML node of type STRING
 204  *
 205  *   parent - parent node
 206  *   key - node key
 207  *   value - value of node
 208  */
 209 struct cYAML *cYAML_create_string(struct cYAML *parent, char *key,
 210                                   char *value);
 211
 212 /*
 213  * cYAML_create_string
 214  *   Creates a cYAML node of type STRING
 215  *
 216  *   parent - parent node
 217  *   key - node key
 218  *   value - value of node
 219  */
 220 struct cYAML *cYAML_create_number(struct cYAML *parent, char *key,
 221                                   double value);
 222
 223 /*
 224  * cYAML_insert_sibling
 225  *   inserts one cYAML object as a sibling to another
 226  *
 227  *   root - root node to have a sibling added to
 228  *   sibling - sibling to be added
 229  */
 230 void cYAML_insert_sibling(struct cYAML *root, struct cYAML *sibling);
 231
 232 /*
 233  * cYAML_insert_child
 234  *   inserts one cYAML object as a child to another
 235  *
 236  *   parent - parent node to have a child added to
 237  *   child - child to be added
 238  */
 239 void cYAML_insert_child(struct cYAML *parent, struct cYAML *node);
 240
 241 /*
 242  * cYAML_build_error
 243  *   Build a YAML error message given:
 244  *
 245  *   rc - return code to add in the error
 246  *   seq_no - a sequence number to add in the error
 247  *   cmd - the command that failed.
 248  *   entity - command entity that failed.
 249  *   err_str - error string to add in the error
 250  *   root - the root to which to add the YAML error
 251  */
 252 void cYAML_build_error(int rc, int seq_no, char *cmd,
 253                         char *entity, char *err_str,
 254                         struct cYAML **root);
 255
 256
 257 #endif /* CYAML_H */