Eina: JSON parserdevs/jackdanielz/json_parser

1 files changed, 899 insertions, 0 deletions

diff --git a/src/lib/eina/eina_json.h b/src/lib/eina/eina_json.h
new file mode 100644
index 0000000000..aa9fe2a250
--- /dev/null
+++ b/src/lib/eina/eina_json.h
@@ -0,0 +1,899 @@
+/* EINA - EFL data type library
+ * Copyright (C) 2013 Yossi Kantor
+ *                    Cedric Bail
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library;
+ * if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef EINA_JSON_H_
+#define EINA_JSON_H_
+
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "eina_config.h"
+
+#include "eina_types.h"
+#include "eina_iterator.h"
+#include "eina_inlist.h"
+#include "eina_array.h"
+#include "eina_strbuf.h"
+#include "eina_safety_checks.h"
+
+/**
+ * @page eina_json_example_01
+ * @include eina_json_01.c
+ * @example eina_json_01.c
+ */
+
+ /**
+ * @page eina_json_example_02
+ * @include eina_json_02.c
+ * @example eina_json_02.c
+ */
+
+ /**
+ * @page eina_json_example_03
+ * @include eina_json_03.c
+ * @example eina_json_03.c
+ */
+
+/**
+ * @page eina_json_dom_example_page @b Dom @b Parsing
+ * @dontinclude eina_json_01.c
+ * @n
+ * DOM parsing is a method of parsing the whole text document into a convinient
+ * data structure. In our case we'll have a @c Eina_Json_Value* pointer to a
+ * root json object after we done.
+ *
+ * So, we define a json string @c my_json
+ * @skip my_json
+ * @until ;
+ *
+ * Next we initilize parse context instance @c ctx
+ * @skipline Eina_Json_Context
+ *
+ * and now we can parse @c my_json string
+ * @skipline eina_json_context_parse
+ *
+ * Lets see if error occured
+ * @skipline Eina_Json_Error
+ *
+ * Since no error occurred @ref eina_json_context_error_get() will return
+ * EINA_JSON_ERROR_NONE. In our case the parsing was completed successfully so
+ * @ref eina_json_context_completed_get() will return true and the next code
+ * will be executed
+ * @skip eina_json_context_completed_get
+ * @until }
+ *
+ * Since DOM parsing was successful we can now use the function
+ * @ref eina_json_context_dom_tree_take in order to get the pointer to a root
+ * object. Once we "took" the tree, we explicitly own it and its our
+ * responsibility to free it with @ref eina_json_value_free(). We can
+ * now traverse, and fully manipulate the tree pointed by @c jsnval with
+ * @ref Eina_Json_Tree_Group "Eina_Json_Value API". In this example we
+ * just print the tree to screen.
+ *
+ * And after we done we free the @c ctx instance
+ * @skipline eina_json_context_free(ctx);
+ *
+ * You can see the full source code
+ * @ref eina_json_example_01 "here".
+ */
+
+/**
+ * @page eina_json_sax_example_page @b Sax @b Parsing
+ * @dontinclude eina_json_03.c
+ * @n
+ * Unlike DOM parser, SAX parser doesn't parses the text document into a
+ * defined data structure, but instead notifies via callback function about each
+ * element and node it encounters. In general,API-wise it works pretty much the
+ * same as the @ref eina_json_dom_example_page "DOM" , the main difference that
+ * you don't get to @ref eina_json_context_dom_tree_take at the end of successful
+ * parsing. What your callback function produces is what you get.
+ *
+ * First we define a @c struct to use it as data structure for the callback
+ * @skip typedef
+ * @until Sax_Parser_Data
+ *
+ * Again, we define a json string @c my_json
+ * @skip my_json
+ * @until ;
+ *
+ * Now we define the callback function ( @ref Eina_Json_Parser_Cb )
+ * @skip void
+ * @until {
+ *
+ * The callback function takes 4 parameters:
+ * @li @c type - the type of json object that was currently parsed
+ * @li @c parent - a unique parent's id (usually pointer) representing
+ * the parent of this object. If NULL then this is a root object.
+ * (Explained further below).
+ * @li @c text - a text data of the object. Depends on @c type as follows:
+ * @par
+ * @c type = @c EINA_JSON_TYPE_STRING @c text holds the string @n
+ * @c type = @c EINA_JSON_TYPE_PAIR @c text holds the name of key value @n
+ * @c type = @c EINA_JSON_TYPE_NUMBER @c text holds the string of
+ * a number (always legal) @n
+ * @c type = @c EINA_JSON_TYPE_BOOLEAN first letter of @c text
+ * (@c *text) @c 'f' = false, @c 't' = true @n
+ *
+ * @li @c data - data that is passed to the callback
+ *
+ * The return value of this callback function is a void* parent id. So as
+ * you might have guessed, the @c parent parameter that you receive in the
+ * callback is the one that was returned from that callback earlier. If you
+ * parsing a json array with 2 numbers @a '[2,3]' it will look like that:
+ * You get first call to callback identifying array with parameters
+ * @c type = @c EINA_JSON_TYPE_ARRAY and @c parent = Some previous Id... .
+ * Your callback allocates the array in memory with address 0x001EDFC,
+ * (you save this address your private @c data) and return it. Next
+ * call for first element in the array which is number 2,
+ * with parameters:  @c type = @c EINA_JSON_TYPE_NUMBER
+ * and @c parent = 0x001EDFC (right,from before) @c text = "2". The
+ * following call for a second element will be @c type =
+  @c EINA_JSON_TYPE_NUMBER and @c parent = 0x001EDFC
+ * @c text = "3". @n
+ * While its makes most sense that @ parent id will be a (void*) pointer,
+ * it doesn't necessary have to be one. As long as you have means to
+ * identify parents for their elements and common language between your
+ * callback and the parser stack its all good. Another thing about
+ * the return value, is that its only meaningful when processing
+ * parent types:
+ * EINA_JSON_TYPE_PAIR/EINA_JSON_TYPE_ARRAY/EINA_JSON_TYPE_OBJECT.
+ * Any other types can return any value (like (void*)1) except NULL.
+ * Returning NULL from the callback function will signal the parser
+ * that and error had occurred and @c EINA_JSON_ERROR_SYNTAX_TOKEN will
+ * be raised and the parser will stop.
+
+ * Now for the rest of our callback function:
+ * @until return
+ * @until }
+
+ * As you can see, our callback basically creates a string inside
+ * @c data->text which represents the elements it parses and the parent
+ * id is an increment of data->parent_idx.
+
+ * Now for the main function. First we define a variable to be passed as
+ * @c *data to our callback.
+ * @until Sax_Parser_Data
+
+ * Then we initialize it.
+ * @skip eina
+ * @until parent_idx
+ *
+ * Now create a SAX parse context instance and pass it our callback
+ * function and @c sax_parser_cb and reference to @c mysax as data.
+ * @skipline Eina_Json_Context
+ *
+ * Now we parse the the json text:
+ * @skipline eina_json_context_parse
+ *
+ * Upon successful completion we print our string in @c mysax
+ * @skip eina_json_context_completed_get
+ * @until }
+ *
+ * Not to forget to free the context
+ * @skipline eina_json_context_free
+ *
+ * You can see the full source code
+ * @ref eina_json_example_02 "here".
+ */
+
+/**
+ * @defgroup Eina_Json_Group Json
+ * Json format parser and data structure
+ *
+ * This module provides a complete set of tools for a Json format.
+ * It offers json @ref eina_json_sax_example_page "SAX" and
+ * @ref eina_json_dom_example_page "DOM" parser and json tree
+ * creation, traversal, manipulation and textual output abilities.
+ *
+ * @b Parsing @n
+ * While still offering a plain run-of-a-mill @ref eina_json_parse "eina_json_parse("
+ * @ref eina_json_parse_n "_n )" which takes a @a complete json text,parses it and
+ * then returns a json tree on success or NULL on failure,the main feature of this
+ * module is the context  parsing function(s) @ref eina_json_context_parse
+ * "eina_json_context_parse("  @ref eina_json_context_parse_n "_n )". Context parsing is
+ * using a @ref Eina_Json_Context instance to parse a single json root object.
+ * The instance is serving as a state keeper of this parsing and this gives us
+ * extended abilities to:
+ * @li Stream parsing - parsing a single json root object not necessarily in one piece
+ * but as a series of sequential parts.
+ * @li Configuration for a specific parsing.
+ * @li Extended diagnostics and probing for a state of a parsing.
+ * @li Easy to add any future API and properties for @ref Eina_Json_Context.
+ *
+ * A small example. Lets say we have a small json we want to parse:
+ * @code
+ * {
+ *   "Json1":"Hello",
+ *   "Json2":"World",
+ * }
+ * @endcode
+ *
+ *  We create new @c Eina_Json_Context instance @c called ctx
+ * @code
+ *    Eina_Json_Context *ctx = eina_json_context_dom_new();
+ * @endcode
+ * (Note: We choose @ref eina_json_context_dom_new for this example,
+ * but we could've initialized @c ctx with
+ * @ref eina_json_context_sax_new just as well.)
+ *
+ * Then we can parse this json as whole:
+ * @code
+ *    eina_json_context_parse(ctx, "{\"Json1\":\"Hello\",\"Json2\":\"World\"}");
+ * @endcode
+ *
+ * Or as a stream of sequential parts:
+ * @code
+ *    eina_json_context_parse(ctx, "{\"Json1\":\"H");
+ *    eina_json_context_parse(ctx, "ell");
+ *    eina_json_context_parse(ctx, "o\",\"Json2\":\"World\"}");
+ * @endcode
+ *
+ * (The examples above parses null-terminated strings.
+ * If it isn't your case, use @ref eina_json_context_parse_n
+ * with a length of a string)
+ *
+ * At any time, @c ctx can be probed for its status. Test If parsing was
+ * completed successfully, an error occurred or neither (waits further input)
+ * and so on with @ref eina_json_context_error_get,
+ * @ref eina_json_context_completed_get etc. This @ref eina_json_example_02
+ * "example" shows the use of sequential parsing when reading json from file
+ * and parsing it in X-sized chunks.
+ *
+ * Please refer to these examples for detailed explanation:
+ * @li @ref eina_json_dom_example_page "DOM parsing"
+ * @li @ref eina_json_sax_example_page "SAX parsing"
+ */
+
+/**
+ * @addtogroup Eina_Tools_Group Tools
+ *
+ * @{
+ */
+
+/**
+ * @defgroup Eina_Json_Group Json
+ *
+ * @{
+ */
+
+typedef struct _Eina_Json_Context Eina_Json_Context;
+typedef struct _Eina_Json_Value Eina_Json_Value;
+typedef struct _Eina_Json_Output_Options Eina_Json_Output_Options;
+
+/**
+ * @typedef Eina_Json_Format
+ * Determinates how a json tree will be converted to text
+ */
+typedef enum _Eina_Json_Format
+{
+   EINA_JSON_FORMAT_PACKED,/**< Prints json in one line no spaces between delimiters */
+   EINA_JSON_FORMAT_BASIC/**< Nice, delimitered and indented human readable format */
+} Eina_Json_Format;
+
+typedef enum _Eina_Json_Type
+{
+    EINA_JSON_TYPE_NULL,
+    EINA_JSON_TYPE_NUMBER,
+    EINA_JSON_TYPE_STRING,
+    EINA_JSON_TYPE_BOOLEAN,
+    EINA_JSON_TYPE_PAIR,
+    EINA_JSON_TYPE_OBJECT,
+    EINA_JSON_TYPE_ARRAY
+} Eina_Json_Type;
+
+/**
+ * @typedef Eina_Json_Error
+ * Json parser possible error states
+ */
+typedef enum _Eina_Json_Error
+{
+    EINA_JSON_ERROR_NONE,/**< No error */
+    EINA_JSON_ERROR_LEX_TOKEN,/**< Error in lexical analysis */
+    EINA_JSON_ERROR_SYNTAX_TOKEN,/**< Error in syntax analysis */
+    EINA_JSON_ERROR_PAST_END/**< Input was entered to the parser after its already successfully parsed a json root */
+} Eina_Json_Error;
+
+typedef void*(*Eina_Json_Parser_Cb)(Eina_Json_Type type, void *parent, const char *text, void*data);
+
+/**
+ * @section Eina_Json_Parser_Group "Json Parser API"
+ *
+ * @{
+ */
+
+
+/**
+ * @brief Create new json DOM parser context
+ *
+ * @return Newly created json parser context on success or @c NULL on failure
+ *
+ */
+EAPI Eina_Json_Context *eina_json_context_dom_new() EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @brief @brief Create new json DOM parser context.
+ *
+ * @param cb The SAX parser @ref eina_json_sax_example_page "callback".
+ * Must not be NULL
+ * @param data The data to be passed to the callback (@p cb)
+ * @return Newly created json parser context on success or @c NULL on failure
+ *
+ */
+EAPI Eina_Json_Context *eina_json_context_sax_new(Eina_Json_Parser_Cb cb, void *data) EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @brief Reset the parser context to its initial state.
+ *
+ * @param ctx The json parser context to be reset
+ *
+ * Resets the paser context to the state it was when it was just created
+ * with @c eina_json_context_dom_new or @c eina_json_context_sax_new and
+ * makes it ready to parse a new json text.
+ * Use this function when you want to recycle an already existing json
+ * context instead of allocating a new one.
+ */
+EAPI void eina_json_context_reset(Eina_Json_Context *ctx);
+
+
+/**
+ * @brief Free the jason parser context.
+ *
+ * @param ctx The json parser context to be freed
+ *
+ * Will free the allocated context with and all of its resourses
+ * no matter on what parsing stage it is.
+ */
+EAPI void eina_json_context_free(Eina_Json_Context *ctx);
+
+
+/**
+ * @brief Returns the current line in a json text document being parsed
+ *
+ * @param ctx The json parser context with which the text is parsed
+ * @return Line number
+ *
+ * Returns the current location inside a parced text line-wise.
+ * As any text document the line count starts from 1.
+ */
+EAPI unsigned eina_json_context_line_get(Eina_Json_Context *ctx);
+
+
+/**
+ * @brief Returns the current column in a json text document being parsed
+ *
+ * @param ctx The json parser context with which the text is parsed
+ * @return Column number
+ *
+ * Returns the current location inside a parced text column-wise.
+ * As any text document the column count starts from 1.
+ */
+EAPI unsigned eina_json_context_column_get(Eina_Json_Context *ctx);
+
+
+/**
+ * @brief Returns the error state of parse context
+ *
+ * @param ctx The json parser context to be probed for error state.
+ * @return Error type of @ref Eina_Json_Error.
+ *
+ * Probe the json parser context for error. If last @c eina_json_context_parse(_n)
+ * resulted in an error, it will be returned by this function. If no error occured
+ * @c EINA_JSON_ERROR_NONE will be returned.
+ *
+ */
+EAPI Eina_Json_Error eina_json_context_error_get(Eina_Json_Context *ctx);
+
+
+/**
+ * @brief Returns whether a context parsing was succesefully completed
+ *
+ * @param ctx The json parser context to be probed for complete state.
+ * @return @c EINA_TRUE if completed, @c EINA_FALSE is not.
+ *
+ * Returns true when a single json root was parsed without errors.
+ * @note Any input of non blank characters after parsing was completed
+ * will result in an @c EINA_ERROR_PAST_END error.
+ *
+ */
+EAPI Eina_Bool eina_json_context_completed_get(Eina_Json_Context *ctx);
+
+
+/**
+ * @brief Returns whether a context parsing awaits further input to complete.
+ *
+ * @param ctx The json parser context to be probed for unfinished state.
+ * @return @c EINA_TRUE if awaits further input or @c EINA_FALSE if not.
+ *
+ * Basically, this function return true when context parser in neither completed
+ * and neither errorneous. Usefull in read loops.
+ *
+ */
+EAPI Eina_Bool eina_json_context_unfinished_get(Eina_Json_Context *ctx);
+
+
+/**
+ * @brief "Takes" parsed json DOM tree from parsing context and returns it.
+ *
+ * @param ctx The sucessefully parsed DOM parser context.
+ * @return Json tree on sucess or @c NULL on error.
+ *
+ * Once a DOM context parsing was succesefully completed, use this function to
+ * obtain its json tree. After the tree is returned and recived into your variable,
+ * it will be unreferenced by the json parse context. It will be your responsibility to
+ * free it with @ref eina_json_value_free once you "took" it. This function will return
+ * @c NULL and will issue an appropriate error message if the @p ctx is not a dom context,
+ * parseing is incomplete or errorneous, or if the tree was already "taken".
+ *
+ */
+EAPI Eina_Json_Value *eina_json_context_dom_tree_take(Eina_Json_Context *ctx) EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @brief Parse json text into a a json tree.
+ *
+ * @param text Null terminated string of complete json root object
+ * @return A json tree on sucesses, @c NULL otherwise
+ *
+ * A simple json parsing function. On sucess returns a newly allocated json tree.
+ * If parsing fails for whatsoverver reason, @c NULL will be returned.
+ * @note Its your resonsibility to free the returned tree with
+ * @ref eina_json_value_free
+ *
+ */
+EAPI Eina_Json_Value *eina_json_parse(const char *text);
+
+
+/**
+ * @brief Parse json text of a maximum specified length into a a json tree.
+ *
+ * @param text String of complete json root object
+ * @param text_len The length of @p text
+ * @return A json tree on sucesses, @c NULL otherwise
+ *
+ * This function is same as @ref eina_json_parse. Use it when you have strings
+ * of specified length and not necceserelly null terminated. If however a
+ * null-terminating character will occur earlier than @p text_len, it will be
+ * the end of string.
+ *
+ * @note Its your resonsibility to free the returned tree with
+ * @ref eina_json_value_free
+ *
+ */
+EAPI Eina_Json_Value *eina_json_parse_n(const char *text, unsigned text_len);
+
+
+/**
+ * @brief Parse json text using a parse context
+ *
+ * @param ctx Json parsing context
+ * @param text Null terminated string of complete or sequantial part of json root object
+ * @return @c EINA_FALSE if error occured during parsing, otherwise @c EINA_TRUE
+ *
+ * This function is the core of this module and its usage is documented in the genearal
+ * documentation and examples.
+ *
+ */
+EAPI Eina_Bool eina_json_context_parse(Eina_Json_Context *ctx, const char *text);
+
+
+/**
+ * @brief Parse json text of a maximum specified length using a parse context
+ *
+ * @param ctx Json parsing context
+ * @param text String of complete or sequantial part of json root object
+ * @return @c EINA_FALSE if error occured during parsing, otherwise @c EINA_TRUE
+ *
+ * This function is same as @ref eina_json_context_parse .Use it when you have strings
+ * of specified length and not necceserelly null terminated. If however a
+ * null-terminating character will occur earlier than @p text_len, it will be
+ * the end of string.
+ *
+ */
+EAPI Eina_Bool eina_json_context_parse_n(Eina_Json_Context *ctx, const char *text, unsigned text_len);
+
+/**
+ * @brief Turn json tree into json text
+ *
+ * @param jsnval Json tree
+ * @param format A text format you wish your json text to be. See @ref Eina_Json_Format
+ * @return Null terminated string of json text
+ *
+ * Takes a json value object and returns a null terminated string reperesenting the text
+ * in a format specified by @p format. Its your responsibility to free the string.
+ *
+ */
+EAPI char * eina_json_format_string_get(Eina_Json_Value *jsnval, Eina_Json_Format format) EINA_WARN_UNUSED_RESULT;
+
+/**
+ * @}
+ */
+
+/**
+ * @section Eina_Json_Tree_Group "Json Value API"
+ *
+ * @{
+ *
+ */
+
+/**
+ * @brief Creates json number value object
+ *
+ * @param num Number to initilize json value object with.
+ * @return Newly allocated json object of type @c EINA_JSON_TYPE_NUMBER
+ *
+ */
+EAPI Eina_Json_Value *eina_json_number_new(double num) EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @brief Creates json string value object
+ *
+ * @param string String to initilize json value object with.
+ * @return Newly allocated json object of type @c EINA_JSON_TYPE_STRING
+ *
+ */
+EAPI Eina_Json_Value *eina_json_string_new(const char *string) EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @brief Creates json boolean value object
+ *
+ * @param boolval Boolean value to initilize json value object with.
+ * @return Newly allocated json object of type @c EINA_JSON_TYPE_BOOLEAN
+ *
+ */
+EAPI Eina_Json_Value *eina_json_boolean_new(Eina_Bool boolval) EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @brief Creates json null value object
+ *
+ * @return Newly allocated json object of type @c EINA_JSON_TYPE_NULL
+ *
+ */
+EAPI Eina_Json_Value *eina_json_null_new() EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @brief Creates json object container value object
+ *
+ * @return Newly allocated json object of type @c EINA_JSON_TYPE_OBJECT
+ *
+ */
+EAPI Eina_Json_Value *eina_json_object_new() EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @brief Creates json array value object
+ *
+ * @return Newly allocated json object of type @c EINA_JSON_TYPE_ARRAY
+ *
+ */
+EAPI Eina_Json_Value *eina_json_array_new() EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @brief Free json value object
+ *
+ * Frees allocated json value and its childern (if any) recursevly.
+ * @warning If a json object is a child of another object, freeing will fail
+ * and appropriate message will be logged.
+ *
+ */
+EAPI void eina_json_value_free(Eina_Json_Value *jsnval);
+
+
+/**
+ * @brief Get the type of json value object
+ *
+ * @param jsnval Json value object
+ * @return @p jsnval type
+ *
+ */
+EAPI Eina_Json_Type eina_json_type_get(Eina_Json_Value *jsnval);
+
+
+/**
+ * @brief Get number value of a json number value object
+ *
+ * @param jsnval Json value object of type @c EINA_JSON_TYPE_NUMBER
+ * @return Number value of a @p jsnval
+ *
+ */
+EAPI double eina_json_number_get(Eina_Json_Value *jsnval);
+
+
+/**
+ * @brief Get string value of a json string value object
+ *
+ * @param jsnval Json value object of type @c EINA_JSON_TYPE_STRING
+ * @return String value of a @p jsnval
+ *
+ */
+EAPI const char *eina_json_string_get(Eina_Json_Value *jsnval);
+
+
+/**
+ * @brief Get boolean value of a json boolean value object
+ *
+ * @param jsnval Json value object of type @c EINA_JSON_TYPE_BOOLEAN
+ * @return Boolean value of a @p jsnval
+ *
+ */
+EAPI Eina_Bool eina_json_boolean_get(Eina_Json_Value *jsnval);
+
+
+/**
+ * @brief Get key name part of a key-value pair
+ *
+ * @param jsnval Json value object of type @c EINA_JSON_TYPE_PAIR
+ * @return Key name string
+ *
+ */
+EAPI const char *eina_json_pair_name_get(Eina_Json_Value *jsnval);
+
+
+/**
+ * @brief Get value part of a key-value pair
+ *
+ * @param jsnval Json value object of type @c EINA_JSON_TYPE_PAIR
+ * @return Json value object reperesenting the value part of key-value pair
+ *
+ */
+EAPI Eina_Json_Value *eina_json_pair_value_get(Eina_Json_Value *jsnval);
+
+
+/**
+ * @brief Set number value to a json number value object
+ *
+ * @param num Json value object of type @c EINA_JSON_TYPE_NUMBER
+ * @param num Number to set json value object to.
+ * @return @c EINA_TRUE if setting sucesseded, otherwise EINA_FALSE
+ *
+ */
+EAPI Eina_Bool eina_json_number_set(Eina_Json_Value *jsnval, double num);
+
+
+/**
+ * @brief Set string value to a json string value object
+ *
+ * @param num Json value object of type @c EINA_JSON_TYPE_STRING
+ * @param string String to set json value object to.
+ * @return @c EINA_TRUE if setting sucesseded, otherwise EINA_FALSE
+ *
+ */
+EAPI Eina_Bool eina_json_string_set(Eina_Json_Value *jsnval, const char* string);
+
+
+/**
+ * @brief Set boolean value to a json string value object
+ *
+ * @param num Json value object of type @c EINA_JSON_TYPE_BOOLEAN
+ * @param boolval Boolean value to set json value object to.
+ * @return @c EINA_TRUE if setting sucesseded, otherwise EINA_FALSE
+ *
+ */
+EAPI Eina_Bool eina_json_boolean_set(Eina_Json_Value *jsnval, Eina_Bool boolval);
+
+
+/**
+ * @brief Get number of key-value pairs inside a json object
+ *
+ * @param obj Json value object of type @c EINA_JSON_TYPE_OBJECT
+ * @return Number of elements (key-value pairs) inside @p obj
+ *
+ */
+EAPI unsigned eina_json_object_count_get(Eina_Json_Value *obj);
+
+
+/**
+ * @brief Get the nth element of json object
+ *
+ * @param obj Json value object of type @c EINA_JSON_TYPE_OBJECT
+ * @param idx Index inside the @p obj
+ * @return Jason value object of @c EINA_JSON_TYPE_PAIR or @c NULL if @p idx
+ * out of bounds or other possible error
+ *
+ */
+EAPI Eina_Json_Value *eina_json_object_nth_get(Eina_Json_Value *obj, unsigned idx);
+
+
+/**
+ * @brief Append new key-value pair to the end of json object
+ *
+ * @param obj Json value object of type @c EINA_JSON_TYPE_OBJECT
+ * @param keyname Name of key in key-value pair
+ * @param jsnval Json value object as a value part of key-value pair. Must NOT be a @c EINA_JSON_TYPE_PAIR
+ * @return Reference of newly appended key-value pair inside @p obj, or @c NULL on failure
+ *
+ * @warning Once json value is appended or inserted into another json object or array its
+ * fully belongs to it. It can be freed only by that container and cannot be appended or
+ * inserted to any other. Doing so will triger a log message and error value will be returned.
+ */
+EAPI Eina_Json_Value *eina_json_object_append(Eina_Json_Value *obj, const char *keyname, Eina_Json_Value *jsnval);
+
+
+/**
+ * @brief Insert new key-value pair at nth place inside the json object
+ *
+ * @param obj Json value object of type @c EINA_JSON_TYPE_OBJECT
+ * @param idx Index inside the @p obj to insert the element at
+ * @param keyname Name of key in key-value pair
+ * @param jsnval Json value object as a value part of key-value pair. Must NOT be
+ *  a @c EINA_JSON_TYPE_PAIR
+ * @return Reference of newly inserted key-value pair inside @p obj, or @c NULL on failure
+ *
+ * @note Insertion at index 0 on empty object will append the pair. Insertion when index is out of bounds
+ * will return NULL.
+
+ * @warning Once json value is appended or inserted into another json object or array its
+ * fully belongs to it. It can be freed only by that container and cannot be appended or
+ * inserted to any other. Doing so will triger a log message and error value will be returned.
+ *
+ */
+EAPI Eina_Json_Value *eina_json_object_insert(Eina_Json_Value *obj, unsigned idx, const char *keyname, Eina_Json_Value *jsnval);
+
+/**
+ * @brief Remove and free a key-value pair at nth place from the json object
+ *
+ * @param obj Json value object of type @c EINA_JSON_TYPE_OBJECT
+ * @param idx Index inside the @p obj to remove the element at.
+ * @return @c EINA_TRUE if removal sucedeed, @c EINA_FALSE otherwise
+ *
+ * The remove element will be freed with @ref eina_json_value_free - thus all of its
+ * children will be freed too recursevly.
+ *
+ */
+EAPI Eina_Bool eina_json_object_nth_remove(Eina_Json_Value *obj, unsigned idx);
+
+
+/**
+ * @brief Get @ref Eina_Iterator to iterate over objects key-value elements.
+ *
+ * @param obj Json value object of type @c EINA_JSON_TYPE_OBJECT
+ * @return Json obect's @ref Eina_Iterator
+ *
+ * This is the fastest way to iterate over the jason object's elements. Use it
+ * like any other Eina containers itterator, dont forgewt to free it in the end.
+ * All elements of object are of @c EINA_JSON_TYPE_PAIR type
+ *
+ */
+EAPI Eina_Iterator *eina_json_object_iterator_new(Eina_Json_Value *obj) EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @brief Get value assosiated with a given key in json object recursively
+ *
+ * @param obj Json value object of type @c EINA_JSON_TYPE_OBJECT
+ * @param ... List of char* key names leading to the desired object. Must end with @c NULL
+ * @return Json value object if found, @c NULL otherwise.
+ *
+ * Finds the corresponding value in a key-value pair inside json object. This a recursive
+ * function so you can specify a number of keys and traverse into the children objects as well.
+ * If a key occurs more than once in the same object, only its first occurrence will be returned.
+ *
+ */
+EAPI Eina_Json_Value *eina_json_object_value_get_internal(Eina_Json_Value *obj, ...);
+
+
+/**
+ * @def eina_json_object_value_get
+ * A convenience wrapper around eina_json_object_value_get_internal()
+ * No @c NULL required at the end of paramenters
+ * @see eina_json_object_value_get_internal
+ */
+#define eina_json_object_value_get(obj, args...) eina_json_object_value_get_internal(obj, ## args, NULL)
+
+
+/**
+ * @brief Get number of elements inside a json array
+ *
+ * @param arr Json value object of type @c EINA_JSON_TYPE_ARRAY
+ * @return Number of elements inside @p arr
+ *
+ */
+EAPI unsigned eina_json_array_count_get(Eina_Json_Value *arr);
+
+
+/**
+ * @brief Get the nth element of json array
+ *
+ * @param arr Json value object of type @c EINA_JSON_TYPE_ARRAY
+ * @param idx Index inside the @p arr
+ * @return Json value object or @c NULL if @p idx out of bounds or other possible error
+ *
+ */
+EAPI Eina_Json_Value *eina_json_array_nth_get(Eina_Json_Value *arr, unsigned idx);
+
+
+/**
+ * @brief Append new element to the end of json array
+ *
+ * @param arr Json value object of type @c EINA_JSON_TYPE_ARRAY
+ * @param jsnval Json value object to be appended. Must NOT be a @c EINA_JSON_TYPE_PAIR
+ * @return Reference of newly appended elemnt inside @p arr or @c NULL on failure
+ *
+ * @warning Once json value is appended or inserted into another json object or array its
+ * fully belongs to it. It can be freed only by that container and cannot be appended or
+ * inserted to any other. Doing so will triger a log message and error value will be returned.
+ */
+EAPI Eina_Json_Value *eina_json_array_append(Eina_Json_Value *arr, Eina_Json_Value *jsnval);
+
+
+/**
+ * @brief Insert new element at nth place inside the json array
+ *
+ * @param arr Json value object of type @c EINA_JSON_TYPE_ARRAY
+ * @param idx Index inside the @p arr to insert the element at
+ * @param jsnval Json value object to be inserted. Must NOT be a @c EINA_JSON_TYPE_PAIR
+ * @return Reference of newly inserted element @p arr or @c NULL on failure
+ *
+ * @note Insertion at index 0 on empty array will append the element. Insertion when index is out of bounds
+ * will return NULL.
+
+ * @warning Once json value is appended or inserted into another json object or array its
+ * fully belongs to it. It can be freed only by that container and cannot be appended or
+ * inserted to any other. Doing so will triger a log message and error value will be returned.
+ *
+ */
+EAPI Eina_Json_Value *eina_json_array_insert(Eina_Json_Value *arr, unsigned idx, Eina_Json_Value *jsnval);
+
+
+/**
+ * @brief Remove and free an element at nth place from the json object
+ *
+ * @param arr Json value object of type @c EINA_JSON_TYPE_ARRAY
+ * @param idx Index inside the @p arr to remove the element at.
+ * @return @c EINA_TRUE if removal sucedeed, @c EINA_FALSE otherwise
+ *
+ * The remove element will be freed with @ref eina_json_value_free - thus all of its
+ * children will be freed too, recursevly.
+ *
+ */
+EAPI Eina_Bool eina_json_array_nth_remove(Eina_Json_Value *arr, unsigned idx);
+
+
+/**
+ * @brief Get @ref Eina_Iterator to iterate over array elements.
+ *
+ * @param arr Json value object of type @c EINA_JSON_TYPE_ARRAY
+ * @return Json obect's @ref Eina_Iterator
+ *
+ * This is the fastest way to iterate over the jason array's elements. Use it
+ * like any other Eina containers itterator, dont forget to free it in the end.
+ *
+ */
+EAPI Eina_Iterator *eina_json_array_iterator_new(Eina_Json_Value *arr) EINA_WARN_UNUSED_RESULT;
+
+
+/**
+ * @}
+ */
+
+/**
+ * @}
+ */
+
+/**
+ * @}
+ */
+
+#endif