"Fossies" - the Fresh Open Source Software Archive

Member "yajl-2.1.0/src/api/yajl_tree.h" (19 Mar 2014, 7171 Bytes) of package /linux/www/yajl-2.1.0.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "yajl_tree.h" see the Fossies "Dox" file reference documentation.

    1 /*
    2  * Copyright (c) 2010-2011  Florian Forster  <ff at octo.it>
    3  *
    4  * Permission to use, copy, modify, and/or distribute this software for any
    5  * purpose with or without fee is hereby granted, provided that the above
    6  * copyright notice and this permission notice appear in all copies.
    7  *
    8  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    9  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   10  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
   11  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
   12  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
   13  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
   14  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
   15  */
   16 
   17 /**
   18  * \file yajl_tree.h
   19  *
   20  * Parses JSON data and returns the data in tree form.
   21  *
   22  * \author Florian Forster
   23  * \date August 2010
   24  *
   25  * This interface makes quick parsing and extraction of
   26  * smallish JSON docs trivial:
   27  *
   28  * \include example/parse_config.c
   29  */
   30 
   31 #ifndef YAJL_TREE_H
   32 #define YAJL_TREE_H 1
   33 
   34 #include <yajl/yajl_common.h>
   35 
   36 #ifdef __cplusplus
   37 extern "C" {
   38 #endif
   39 
   40 /** possible data types that a yajl_val_s can hold */
   41 typedef enum {
   42     yajl_t_string = 1,
   43     yajl_t_number = 2,
   44     yajl_t_object = 3,
   45     yajl_t_array = 4,
   46     yajl_t_true = 5,
   47     yajl_t_false = 6,
   48     yajl_t_null = 7,
   49     /** The any type isn't valid for yajl_val_s.type, but can be
   50      *  used as an argument to routines like yajl_tree_get().
   51      */
   52     yajl_t_any = 8
   53 } yajl_type;
   54 
   55 #define YAJL_NUMBER_INT_VALID    0x01
   56 #define YAJL_NUMBER_DOUBLE_VALID 0x02
   57 
   58 /** A pointer to a node in the parse tree */
   59 typedef struct yajl_val_s * yajl_val;
   60 
   61 /**
   62  * A JSON value representation capable of holding one of the seven
   63  * types above. For "string", "number", "object", and "array"
   64  * additional data is available in the union.  The "YAJL_IS_*"
   65  * and "YAJL_GET_*" macros below allow type checking and convenient
   66  * value extraction.
   67  */
   68 struct yajl_val_s
   69 {
   70     /** Type of the value contained. Use the "YAJL_IS_*" macros to check for a
   71      * specific type. */
   72     yajl_type type;
   73     /** Type-specific data. You may use the "YAJL_GET_*" macros to access these
   74      * members. */
   75     union
   76     {
   77         char * string;
   78         struct {
   79             long long i; /*< integer value, if representable. */
   80             double  d;   /*< double value, if representable. */
   81             char   *r;   /*< unparsed number in string form. */
   82             /** Signals whether the \em i and \em d members are
   83              * valid. See \c YAJL_NUMBER_INT_VALID and
   84              * \c YAJL_NUMBER_DOUBLE_VALID. */
   85             unsigned int flags;
   86         } number;
   87         struct {
   88             const char **keys; /*< Array of keys */
   89             yajl_val *values; /*< Array of values. */
   90             size_t len; /*< Number of key-value-pairs. */
   91         } object;
   92         struct {
   93             yajl_val *values; /*< Array of elements. */
   94             size_t len; /*< Number of elements. */
   95         } array;
   96     } u;
   97 };
   98 
   99 /**
  100  * Parse a string.
  101  *
  102  * Parses an null-terminated string containing JSON data and returns a pointer
  103  * to the top-level value (root of the parse tree).
  104  *
  105  * \param input              Pointer to a null-terminated utf8 string containing
  106  *                           JSON data.
  107  * \param error_buffer       Pointer to a buffer in which an error message will
  108  *                           be stored if \em yajl_tree_parse fails, or
  109  *                           \c NULL. The buffer will be initialized before
  110  *                           parsing, so its content will be destroyed even if
  111  *                           \em yajl_tree_parse succeeds.
  112  * \param error_buffer_size  Size of the memory area pointed to by
  113  *                           \em error_buffer_size. If \em error_buffer_size is
  114  *                           \c NULL, this argument is ignored.
  115  *
  116  * \returns Pointer to the top-level value or \c NULL on error. The memory
  117  * pointed to must be freed using \em yajl_tree_free. In case of an error, a
  118  * null terminated message describing the error in more detail is stored in
  119  * \em error_buffer if it is not \c NULL.
  120  */
  121 YAJL_API yajl_val yajl_tree_parse (const char *input,
  122                                    char *error_buffer, size_t error_buffer_size);
  123 
  124 
  125 /**
  126  * Free a parse tree returned by "yajl_tree_parse".
  127  *
  128  * \param v Pointer to a JSON value returned by "yajl_tree_parse". Passing NULL
  129  * is valid and results in a no-op.
  130  */
  131 YAJL_API void yajl_tree_free (yajl_val v);
  132 
  133 /**
  134  * Access a nested value inside a tree.
  135  *
  136  * \param parent the node under which you'd like to extract values.
  137  * \param path A null terminated array of strings, each the name of an object key
  138  * \param type the yajl_type of the object you seek, or yajl_t_any if any will do.
  139  *
  140  * \returns a pointer to the found value, or NULL if we came up empty.
  141  *
  142  * Future Ideas:  it'd be nice to move path to a string and implement support for
  143  * a teeny tiny micro language here, so you can extract array elements, do things
  144  * like .first and .last, even .length.  Inspiration from JSONPath and css selectors?
  145  * No it wouldn't be fast, but that's not what this API is about.
  146  */
  147 YAJL_API yajl_val yajl_tree_get(yajl_val parent, const char ** path, yajl_type type);
  148 
  149 /* Various convenience macros to check the type of a `yajl_val` */
  150 #define YAJL_IS_STRING(v) (((v) != NULL) && ((v)->type == yajl_t_string))
  151 #define YAJL_IS_NUMBER(v) (((v) != NULL) && ((v)->type == yajl_t_number))
  152 #define YAJL_IS_INTEGER(v) (YAJL_IS_NUMBER(v) && ((v)->u.number.flags & YAJL_NUMBER_INT_VALID))
  153 #define YAJL_IS_DOUBLE(v) (YAJL_IS_NUMBER(v) && ((v)->u.number.flags & YAJL_NUMBER_DOUBLE_VALID))
  154 #define YAJL_IS_OBJECT(v) (((v) != NULL) && ((v)->type == yajl_t_object))
  155 #define YAJL_IS_ARRAY(v)  (((v) != NULL) && ((v)->type == yajl_t_array ))
  156 #define YAJL_IS_TRUE(v)   (((v) != NULL) && ((v)->type == yajl_t_true  ))
  157 #define YAJL_IS_FALSE(v)  (((v) != NULL) && ((v)->type == yajl_t_false ))
  158 #define YAJL_IS_NULL(v)   (((v) != NULL) && ((v)->type == yajl_t_null  ))
  159 
  160 /** Given a yajl_val_string return a ptr to the bare string it contains,
  161  *  or NULL if the value is not a string. */
  162 #define YAJL_GET_STRING(v) (YAJL_IS_STRING(v) ? (v)->u.string : NULL)
  163 
  164 /** Get the string representation of a number.  You should check type first,
  165  *  perhaps using YAJL_IS_NUMBER */
  166 #define YAJL_GET_NUMBER(v) ((v)->u.number.r)
  167 
  168 /** Get the double representation of a number.  You should check type first,
  169  *  perhaps using YAJL_IS_DOUBLE */
  170 #define YAJL_GET_DOUBLE(v) ((v)->u.number.d)
  171 
  172 /** Get the 64bit (long long) integer representation of a number.  You should
  173  *  check type first, perhaps using YAJL_IS_INTEGER */
  174 #define YAJL_GET_INTEGER(v) ((v)->u.number.i)
  175 
  176 /** Get a pointer to a yajl_val_object or NULL if the value is not an object. */
  177 #define YAJL_GET_OBJECT(v) (YAJL_IS_OBJECT(v) ? &(v)->u.object : NULL)
  178 
  179 /** Get a pointer to a yajl_val_array or NULL if the value is not an object. */
  180 #define YAJL_GET_ARRAY(v)  (YAJL_IS_ARRAY(v)  ? &(v)->u.array  : NULL)
  181 
  182 #ifdef __cplusplus
  183 }
  184 #endif
  185 
  186 #endif /* YAJL_TREE_H */