Whamcloud - gitweb
LU-9091 procfs: remove old string parsing routines
[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 <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 */