include/yaz/json.h

   1 /* This file is part of the YAZ toolkit.
   2  * Copyright (C) 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 /** \brief writes JSON tree with indentation (pretty print)
 191     \param node JSON tree
 192     \param result resulting JSON string buffer
 193 */
 194 YAZ_EXPORT
 195 void json_write_wrbuf_pretty(struct json_node *node, WRBUF result);
 196
 197 YAZ_END_CDECL
 198
 199 #endif
 200
 201 /*
 202  * Local variables:
 203  * c-basic-offset: 4
 204  * c-file-style: "Stroustrup"
 205  * indent-tabs-mode: nil
 206  * End:
 207  * vim: shiftwidth=4 tabstop=8 expandtab
 208  */
 209