/*
  JSONParser v1.2
  Copyright (C) 2009 Alex Diener

  This software is provided 'as-is', without any express or implied
  warranty.  In no event will the authors be held liable for any damages
  arising from the use of this software.

  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:

  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.

  Alex Diener adiener@sacredsoftware.net
*/

#ifndef __JSON_PARSER_H__
#define __JSON_PARSER_H__

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stdlib.h>

typedef struct JSONNode JSONNode;
typedef enum JSONType JSONType;

enum JSONType {
	JSON_TYPE_OBJECT = 0,
	JSON_TYPE_ARRAY = 1,
	JSON_TYPE_STRING = 2,
	JSON_TYPE_NUMBER = 3,
	JSON_TYPE_BOOLEAN = 4,
	JSON_TYPE_NULL = 5
};

struct JSONNode {
	JSONType type;
	char * key;
	size_t numberOfChildren;
	JSONNode * children;
	union {
		char * string;
		double number;
		bool boolean;
	} value;
};

/**
 * Description:
 *   Attempts to parse jsonString into a JSON object or array. Returns a JSONNode * representing
 *   the parsed JSON tree if parsing was successful.
 * 
 * Parameters:
 *   jsonString: String containing a valid JSON object or array. There must not be any non-whitespace
 *               characters before or after the object/array; if there are, parsing will fail.
 *   
 *   length:     Character length of jsonString.
 * 
 * Return value:
 *   On success, returns a fully populated JSONNode hierarchy. The caller is responsible for disposing
 *   of this value with JSONParser_freeNodeContents() and free(). If jsonString is not valid JSON,
 *   returns NULL.
 */
JSONNode * JSONParser_parse(const char * jsonString, size_t length);

/**
 * Description:
 *   Attempts to parse part of jsonString into a JSON object or array. If parsing is successful,
 *   populates outNode with the parsed JSON tree, writes the number of characters consumed to
 *   outCharsConsumed, and returns true.
 *   
 *   Note that even if parsing fails, some data may have already been written to outNode. The caller
 *   should ensure that outNode is in a valid state before calling this function (for example,
 *   {type = JSON_TYPE_NULL, key = NULL}), and is responsible for calling JSONParser_freeNodeContents
 *   even on parse failure.
 * 
 * Parameters:
 *   jsonString:       String containing a valid JSON object or array. If expectEOF is true, there
 *                     must not be any non-whitespace characters after the object/array. If expectEOF
 *                     is false, parsing completes successfully at the end of the object/array.
 *   
 *   length:           Character length of jsonString.
 *   
 *   outNode:          JSONNode to which the results of parsing will be written, including incomplete
 *                     results from partially-successful parsing.
 *   
 *   expectEOF:        If true, parsing will fail on any non-whitespace characters after the end of
 *                     the object/array being parsed. If false, parsing stops at the end of the
 *                     object/array.
 *   
 *   outCharsConsumed: On return, number of characters consumed during parsing. If the caller doesn't
 *                     need to know this value, pass NULL.
 * 
 * Return value:
 *   True if parsing completes successfully; false if parsing fails (including partial success).
 */
bool JSONParser_parseNode(const char * jsonString, size_t length, JSONNode * outNode, bool expectEOF, size_t * outCharsConsumed);

/**
 * Description:
 *   Frees memory allocated for strings in this node and all of its children. If the top-level node
 *   has been allocated with malloc (which is the case if it was returned from JSONParser_parse()),
 *   the caller is still responsible for calling free() on it after calling this function.
 */
void JSONParser_freeNodeContents(JSONNode * node);

#ifdef __cplusplus
}
#endif

#endif