Whamcloud - gitweb
1537dbd19ed0c0133837c058ff9c4b954142cf52
[fs/lustre-release.git] / 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 */