Fix yaz URL
[yaz-moved-to-github.git] / include / yaz / json.h
1 /* This file is part of the YAZ toolkit.
2  * Copyright (C) 1995-2010 Index Data.
3  * All rights reserved.
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *
7  *     * Redistributions of source code must retain the above copyright
8  *       notice, this list of conditions and the following disclaimer.
9  *     * Redistributions in binary form must reproduce the above copyright
10  *       notice, this list of conditions and the following disclaimer in the
11  *       documentation and/or other materials provided with the distribution.
12  *     * Neither the name of Index Data nor the names of its contributors
13  *       may be used to endorse or promote products derived from this
14  *       software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27
28 /** \file json.h
29     \brief Header for JSON functions
30 */
31
32 #ifndef YAZ_JSON_H
33 #define YAZ_JSON_H
34 #include <yaz/wrbuf.h>
35
36 YAZ_BEGIN_CDECL
37
38 /** \brief JSON node type for json_node */
39 enum json_node_type {
40     json_node_object, /**< JSON object, u.link[0] is object content */
41     json_node_array,  /**< JSON array, u.link[0] is array content */
42     json_node_list,   /**< JSON elements or JSON members,
43                          u.link[0] is value, u.link[1] is next elemen in list */
44     json_node_pair,   /**< JSON pair, u.link[0] is name, u.link[1] is value */
45     json_node_string, /**< JSON string, u.string is content */
46     json_node_number, /**< JSON number (floating point), u.number is content */
47     json_node_true,   /**< JSON true */
48     json_node_false,  /**< JSON false */
49     json_node_null    /**< JSON null */
50 };
51
52 /** \brief JSON node */
53 struct json_node {
54     enum json_node_type type;
55     union {
56         char *string; 
57         double number; 
58         struct json_node *link[2];
59     } u;
60 };
61
62 /** \brief JSON parser (opaque) */
63 typedef struct json_parser_s *json_parser_t;
64
65 /** \brief create JSON parser
66     \returns JSON parser handle
67 */
68 YAZ_EXPORT
69 json_parser_t json_parser_create(void);
70
71 /** \brief destroys JSON parser
72     \param p JSON parser handle
73 */
74 YAZ_EXPORT
75 void json_parser_destroy(json_parser_t p);
76
77 /** \brief parses JSON string
78     \param p JSON parser handle
79     \param json_str JSON string
80     \returns JSON tree or NULL if parse error occurred.
81
82     The resulting tree should be removed with a call to json_remove_node.
83 */
84 YAZ_EXPORT
85 struct json_node *json_parser_parse(json_parser_t p, const char *json_str);
86
87 /** \brief returns parser error
88     \param p JSON parser handle
89     \returns parse error msg 
90
91     This function should be called if json_parser_parse returns NULL .
92 */
93 YAZ_EXPORT
94 const char *json_parser_get_errmsg(json_parser_t p);
95
96 /** \brief returns parser position
97     \param p JSON parser handle
98     \returns number of bytes read from parser
99
100     This function should be called if json_parser_parse returns NULL .
101 */
102 YAZ_EXPORT
103 size_t json_parser_get_position(json_parser_t p);
104
105 /** \brief parses JSON string
106     \param json_str JSON string
107     \param errmsg pointer to error message string
108     \returns JSON tree or NULL if parse error occurred.
109
110     The resulting tree should be removed with a call to json_remove_node.
111     The errmsg may be NULL in which case the error message is not returned.
112 */
113 YAZ_EXPORT
114 struct json_node *json_parse(const char *json_str, const char **errmsg);
115
116 /** \brief parses JSON string
117     \param json_str JSON string
118     \param errmsg pointer to error message string
119     \param pos position of parser stop (probably error)
120     \returns JSON tree or NULL if parse error occurred.
121
122     The resulting tree should be removed with a call to json_remove_node.
123     The errmsg may be NULL in which case the error message is not returned.
124 */
125 YAZ_EXPORT
126 struct json_node *json_parse2(const char *json_str, const char **errmsg,
127                               size_t *pos);
128
129 /** \brief destroys JSON tree node and its children
130     \param n JSON node
131 */
132 YAZ_EXPORT
133 void json_remove_node(struct json_node *n);
134
135 /** \brief gets object pair value for some name
136     \param n JSON node (presumably object node)
137     \param name name to match
138     \returns node or NULL if not found
139 */
140 YAZ_EXPORT
141 struct json_node *json_get_object(struct json_node *n, const char *name);
142
143 /** \brief gets object value and detaches from existing tree
144     \param n JSON node (presumably object node)
145     \param name name to match
146     \returns node or NULL if not found
147 */
148 YAZ_EXPORT
149 struct json_node *json_detach_object(struct json_node *n, const char *name);
150
151 /** \brief gets array element
152     \param n JSON node (presumably array node)
153     \param idx (0=first, 1=second, ..)
154     \returns node or NULL if not found
155 */
156 YAZ_EXPORT
157 struct json_node *json_get_elem(struct json_node *n, int idx);
158
159 /** \brief returns number of children (array or object)
160     \param n JSON node (presumably array node or object node)
161     \returns number of children
162 */
163 YAZ_EXPORT
164 int json_count_children(struct json_node *n);
165
166 /** \brief appends array to another
167     \param dst original array and resulting array
168     \param src array to be appended to dst
169     \retval -1 not arrays
170     \retval 0 array appended OK
171 */
172 YAZ_EXPORT
173 int json_append_array(struct json_node *dst, struct json_node *src);
174
175 /** \brief configure subst rule
176     \param p JSON parser
177     \param idx (%id)
178     \param n node to be substituted for idx (%idx)
179 */
180 YAZ_EXPORT
181 void json_parser_subst(json_parser_t p, int idx, struct json_node *n);
182
183 /** \brief converts JSON tree to JSON string
184     \param node JSON tree
185     \param result resulting JSON string buffer
186 */
187 YAZ_EXPORT
188 void json_write_wrbuf(struct json_node *node, WRBUF result);
189
190 YAZ_END_CDECL
191
192 #endif
193
194 /*
195  * Local variables:
196  * c-basic-offset: 4
197  * c-file-style: "Stroustrup"
198  * indent-tabs-mode: nil
199  * End:
200  * vim: shiftwidth=4 tabstop=8 expandtab
201  */
202