diff options
author | Florian Forster <octo@leeloo.lan.home.verplant.org> | 2010-08-11 14:30:05 +0200 |
---|---|---|
committer | Florian Forster <octo@leeloo.lan.home.verplant.org> | 2010-08-11 14:30:05 +0200 |
commit | d1c57f65d722eef41a9e10f29ce7983d64620c7a (patch) | |
tree | 481b85053eacf7f8be0c2fa427010507dd103f58 | |
parent | 3240f2ec584657c41a12d464f96834af12270031 (diff) | |
download | yajl-d1c57f65d722eef41a9e10f29ce7983d64620c7a.tar.gz |
src/api/yajl_tree.h: Add Doxygen documentation.
-rw-r--r-- | src/api/yajl_tree.h | 141 |
1 files changed, 139 insertions, 2 deletions
diff --git a/src/api/yajl_tree.h b/src/api/yajl_tree.h index 748edf1..5a6d3b3 100644 --- a/src/api/yajl_tree.h +++ b/src/api/yajl_tree.h @@ -30,6 +30,15 @@ * POSSIBILITY OF SUCH DAMAGE. */ +/** + * \file yajl_tree.h + * + * Parses JSON data and returns the data in tree form. + * + * \author Florian Forster + * \date August 2010 + */ + #ifndef YAJL_TREE_H #define YAJL_TREE_H 1 @@ -38,37 +47,62 @@ #include <yajl/yajl_common.h> +/* Forward declaration, because "yajl_value_object_t" and "yajl_value_array_t" + * contain "yajl_value_t" and "yajl_value_t" can be an object or an array. */ struct yajl_value_s; typedef struct yajl_value_s yajl_value_t; +/** Structure describing a JSON string. */ struct yajl_value_string_s { + /** Null terminated string. */ char *value; }; typedef struct yajl_value_string_s yajl_value_string_t; -#define YAJL_NUMBER_INT_VALID 1 -#define YAJL_NUMBER_DOUBLE_VALID 2 +#define YAJL_NUMBER_INT_VALID 0x01 +#define YAJL_NUMBER_DOUBLE_VALID 0x02 +/** Structure describing a JSON number. */ struct yajl_value_number_s { + /** Holds the raw value of the number, in string form. */ char *value_raw; + /** Holds the integer value of the number, if possible. */ int64_t value_int; + /** Holds the double value of the number, if possible. */ double value_double; + /** Signals whether the \em value_int and \em value_double members are + * valid. See \c YAJL_NUMBER_INT_VALID and \c YAJL_NUMBER_DOUBLE_VALID. */ unsigned int flags; }; typedef struct yajl_value_number_s yajl_value_number_t; +/** + * Structure describing a JSON object. + * + * \sa yajl_value_array_s + */ struct yajl_value_object_s { + /** Array of keys in the JSON object. */ yajl_value_t **keys; + /** Array of values in the JSON object. */ yajl_value_t **values; + /** Number of key-value-pairs in the JSON object. */ size_t children_num; }; typedef struct yajl_value_object_s yajl_value_object_t; +/** + * Structure describing a JSON array. + * + * \sa yajl_value_object_s + */ struct yajl_value_array_s { + /** Array of elements in the JSON array. */ yajl_value_t **children; + /** Number of elements in the JSON array. */ size_t children_num; }; typedef struct yajl_value_array_s yajl_value_array_t; @@ -81,9 +115,24 @@ typedef struct yajl_value_array_s yajl_value_array_t; #define YAJL_TYPE_FALSE 6 #define YAJL_TYPE_NULL 7 +/** + * Struct describing a general JSON value. + * + * Each value is one of the seven types above. For "string", "number", + * "object", and "array" additional data is available in the "data" union. Use + * the "YAJL_IS_*" and "YAJL_TO_*" macros below to check for the correct type + * and cast the struct. + * + * \sa yajl_value_string_t, yajl_value_number_t, yajl_value_object_t, + * yajl_value_array_t + */ struct yajl_value_s { + /** Type of the value contained. Use the "YAJL_IS_*" macors to check for a + * specific type. */ uint8_t type; + /** Type-specific data. Use the "YAJL_TO_*" macros to access these + * members. */ union { yajl_value_string_t string; @@ -93,20 +142,108 @@ struct yajl_value_s } data; }; +/** + * Parse a string. + * + * Parses an null-terminated string containing JSON data and returns a pointer + * to the top-level value (root of the parse tree). + * + * \param input Pointer to a null-terminated string containing JSON data. + * + * \returns Pointer to the top-level value or NULL on error. The memory pointed + * to must be freed using "yajl_tree_free". + */ YAJL_API yajl_value_t *yajl_tree_parse (const char *input); + +/** + * Free a parse tree. + * + * Recursively frees a pointer returned by "yajl_tree_parse". + * + * \param v Pointer to a JSON value returned by "yajl_tree_parse". Passing NULL + * is valid and results in a no-op. + */ YAJL_API void yajl_tree_free (yajl_value_t *v); +/** + * Checks if value is a string. + * + * Returns true if the value is a string, false otherwise. + */ #define YAJL_IS_STRING(v) (((v) != NULL) && ((v)->type == YAJL_TYPE_STRING)) + +/** + * Checks if value is a number. + * + * Returns true if the value is a number, false otherwise. + */ #define YAJL_IS_NUMBER(v) (((v) != NULL) && ((v)->type == YAJL_TYPE_NUMBER)) + +/** + * Checks if value is an object. + * + * Returns true if the value is a object, false otherwise. + */ #define YAJL_IS_OBJECT(v) (((v) != NULL) && ((v)->type == YAJL_TYPE_OBJECT)) + +/** + * Checks if value is an array. + * + * Returns true if the value is a array, false otherwise. + */ #define YAJL_IS_ARRAY(v) (((v) != NULL) && ((v)->type == YAJL_TYPE_ARRAY )) + +/** + * Checks if value is true. + * + * Returns true if the value is a boolean and true, false otherwise. + */ #define YAJL_IS_TRUE(v) (((v) != NULL) && ((v)->type == YAJL_TYPE_TRUE )) + +/** + * Checks if value is false. + * + * Returns true if the value is a boolean and false, false otherwise. + */ #define YAJL_IS_FALSE(v) (((v) != NULL) && ((v)->type == YAJL_TYPE_FALSE )) + +/** + * Checks if value is null. + * + * Returns true if the value is null, false otherwise. + */ #define YAJL_IS_NULL(v) (((v) != NULL) && ((v)->type == YAJL_TYPE_NULL )) +/** + * Convert value to string. + * + * Returns a pointer to a yajl_value_string_t or NULL if the value is not a + * string. + */ #define YAJL_TO_STRING(v) (YAJL_IS_STRING(v) ? &(v)->data.string : NULL) + +/** + * Convert value to number. + * + * Returns a pointer to a yajl_value_number_t or NULL if the value is not a + * number. + */ #define YAJL_TO_NUMBER(v) (YAJL_IS_NUMBER(v) ? &(v)->data.number : NULL) + +/** + * Convert value to object. + * + * Returns a pointer to a yajl_value_object_t or NULL if the value is not an + * object. + */ #define YAJL_TO_OBJECT(v) (YAJL_IS_OBJECT(v) ? &(v)->data.object : NULL) + +/** + * Convert value to array. + * + * Returns a pointer to a yajl_value_array_t or NULL if the value is not an + * array. + */ #define YAJL_TO_ARRAY(v) (YAJL_IS_ARRAY(v) ? &(v)->data.array : NULL) #endif /* YAJL_TREE_H */ |