4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
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.
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.
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/>.
21 * Copyright (c) 2014, Intel Corporation.
24 * Amir Shehata <amir.shehata@intel.com>
32 enum cYAML_object_type {
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;
51 /* The item's string, if type==CYAML_TYPE_STRING */
53 /* The item's number, if type==CYAML_TYPE_NUMBER */
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. */
60 /* user data which might need to be tracked per object */
64 typedef void (*cYAML_user_data_free_cb)(void *);
68 * Callback called when recursing through the tree
70 * cYAML* - pointer to the node currently being visitied
71 * void* - user data passed to the callback.
72 * void** - output value from the callback
74 * Returns true to continue recursing. false to stop recursing
76 typedef bool (*cYAML_walk_cb)(struct cYAML *, void *, void**);
80 * Build a tree representation of the YAML formatted text passed in.
82 * yaml_file - YAML file to parse and build tree representation
83 * yaml_blk - blk of YAML. yaml_file takes precedence if both
85 * yaml_blk_size - length of the yaml block (obtained via strlen)
87 struct cYAML *cYAML_build_tree(char *yaml_file, const char *yaml_blk,
89 struct cYAML **err_str, bool debug);
93 * Print the textual representation of a YAML tree to stderr
95 * node - Node where you want to start printing
97 void cYAML_print_tree(struct cYAML *node);
100 * cYAML_print_tree2file
101 * Print the textual representation of a YAML tree to file
103 * f - file to print to
104 * node - Node where you want to start printing
106 void cYAML_print_tree2file(FILE *f, struct cYAML *node);
110 * Free the cYAML tree returned as part of the cYAML_build_tree
112 * node - root of the tree to be freed
114 void cYAML_free_tree(struct cYAML *node);
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.
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.
124 struct cYAML *cYAML_get_object_item(struct cYAML *parent,
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
136 * seq - is the head node of the YAML sequence
137 * itm - [OUT] next sequence item to continue looking from next time.
140 struct cYAML *cYAML_get_next_seq_item(struct cYAML *seq,
145 * Returns 1 if the node provided is an ARRAY 0 otherwise
147 * node - the node to examine
150 bool cYAML_is_sequence(struct cYAML *node);
154 * Returns the cYAML object which key correspods to the name passed in
155 * this function searches the entire tree.
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.
160 struct cYAML *cYAML_find_object(struct cYAML *root, const char *key);
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.
167 * node: node to start the walk from
168 * free_cb: cb to call to cleanup the user data
170 void cYAML_clean_usr_data(struct cYAML *node,
171 cYAML_user_data_free_cb free_cb);
174 * cYAML_create_object
175 * Creates a CYAML of type OBJECT
177 * parent - parent node
180 struct cYAML *cYAML_create_object(struct cYAML *parent, char *key);
184 * Creates a CYAML of type ARRAY
185 * Once this is created, more sequence items can be added.
187 * parent - parent node
190 struct cYAML *cYAML_create_seq(struct cYAML *parent, char *key);
193 * cYAML_create_object
194 * Create a sequence item, which can have more entites added underneath
197 * parent - parent node
199 struct cYAML *cYAML_create_seq_item(struct cYAML *seq);
202 * cYAML_create_string
203 * Creates a cYAML node of type STRING
205 * parent - parent node
207 * value - value of node
209 struct cYAML *cYAML_create_string(struct cYAML *parent, char *key,
213 * cYAML_create_string
214 * Creates a cYAML node of type STRING
216 * parent - parent node
218 * value - value of node
220 struct cYAML *cYAML_create_number(struct cYAML *parent, char *key,
224 * cYAML_insert_sibling
225 * inserts one cYAML object as a sibling to another
227 * root - root node to have a sibling added to
228 * sibling - sibling to be added
230 void cYAML_insert_sibling(struct cYAML *root, struct cYAML *sibling);
234 * inserts one cYAML object as a child to another
236 * parent - parent node to have a child added to
237 * child - child to be added
239 void cYAML_insert_child(struct cYAML *parent, struct cYAML *node);
243 * Build a YAML error message given:
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
252 void cYAML_build_error(int rc, int seq_no, char *cmd,
253 char *entity, char *err_str,
254 struct cYAML **root);