Using the JSON Conversion Functions
===================================

The JSON Parser package provides three conversion functions, a JSON Parser, a JSON 
Generator and a JSON Validator. Additionally there are also a rich set of JSON
Support Functions to assist C developers is using JSON Data easily with the minimum
of coding overhead. Those are described in another document.

This document presents basic ideas on how to use the JSON Conversion Functions
provided in this JSON package, and a brief introduction on using the available
D-List functions, to access that JSON data after conversion.


Background
----------

This JSON Parser package was written to provide not only a fully functional, fast
and accurate JSON Parser for C programmers, but also to provide the JSON data in a
form that is more generally useful to C developers. Most JSON parsers write the
parsed JSON data into arrays etc, and there are numerous issues as C as a language
does not natively support unbounded or variable sized data. However the D-List 
package for C does natively provide such support with a very easy to use, and rich,
set of available functions to access, modify, add to, manipulate, manage and copy 
this variable data. The D-List package is also extremely fast & efficient and a 
great way to manipulate varied data from different sources.

All functions described in this document that start with json_xxx are part of the 
JSON Parser package, and details about there usage and arguments, can be found in
the JSON Parser documentation. All functions that start with list_xxx are part of
the D-List package.

JSON is a data format focused on inter-system and inter-language interoperability. 
If you are unfamiliar with JSON grammar or syntax, please refer to ECMA-404 and 
RFC 8259 or 
	
	http://json.org 

before trying to use the JSON Support Functions.

Throughout this JSON Parser package, all JSON Objects and JSON Arrays are accessed
and manipulated using D-List list_objects, and all JSON value items are elements
within those list_objects. The list_objects are arranged hierarchically allowing
these data structures to represent the JSON syntax exactly.

If you are unfamiliar with D-List, then please consult the reference documentation.
To find that documentation, or to learn more about list_objects, elements, and the
rich set of D-List functions; please refer to the D-List documentation, which is 
available in the D-List distribution Header Files, or a set of Doxy files that are
included in that distribution, or online at 

	http://info.fwsentry.org/dlist/index.html

JSON Data Functions
===================

The document JSON-Support-Functions in the GUIDES directory covers a general
guide and tutorial on how to access and manipulate JSON data using these JSON
Support Functions.

This document cover the list of the functions with brief descriptions. For more
details please refer to the header file. The JSON Conversion Functions are 
covered in a different document.

Everything that can be done with the JSON data representations can be achieved
directly with D-List functions. However these JSON specific functions make many
of the frequently used operations must easier to code and use. However using
D-List functions directly will always be more efficient, when needed.

All element removal, sorting, and other management functions must be done via the
D-List functions. There would be no point in replicating those functions here,
while not adding any value to them.



json_find_members_value_string()			Using the provided search criteria, search the 
											JSON data and locate all object members in the
											list hierarchy that match the criteria, 
											returning them in a new list_object to the 
											caller.

json_find_members_value_integer()			Using the provided search criteria, search the
											JSON data and locate all object members in the
											list hierarchy that match the criteria,
											returning them in a new list_object to the 
											caller.

json_find_members_value_double()			Using the provided search criteria, search the
											JSON data and locate all object members in the
											list hierarchy that match the criteria, 
											returning them in a new list_object to the 
											caller.

json_find_members_value_type()				Using the provided search criteria, search the
											JSON data and locate all object members in the
											list hierarchy that match the criteria, 
											returning them in a new list_object to the 
											caller

json_find_member_value()					Using the provided search criteria, search the
											JSON data and locate the first JSON object
											member in the list hierarchy that match the 
											criteria, returning a pointer to it to the
											caller.

json_path_locate()							Using the internal representation of a JSON 
											dotted notation path, trace the provided path
											and return the list_object or element found.
	
json_create_new_list_object()				Create a new list_object to be used to 
											represent either a JSON Object or a JSON Array

json_report_list_object_type()				Given an unknown list_object, provide the JSON 
											value type this list_object represents. The 
											result can either be JSON_object, JSON_array 
											or JSON_value.

json_list_object_member_add_string()		Add a new Member with a string value to a JSON
											Object, defined by the list_object provided.

json_list_object_member_add_number()		Add a new Member with a number value to a JSON
											Object, defined by the list_object provided.

json_list_object_member_add_boolean()		Add a new Member with a boolean value to a 
											JSON Object, defined by  the list_object 
											provided.

json_list_object_member_add_null()			Add a new Member with a null value to a JSON
											Object, defined by the list_object provided.

json_list_object_member_add_list()			Add a new Member with a JSON Array or JSON 
											Object value to an existing JSON Object, 
											defined by the list_object provided.

json_list_object_array_value_add_string()	Add a new String Value to a JSON Array, 
											defined by the list_object provided.

json_list_object_array_value_add_number()	Add a new Number Value to a JSON Array, 
											defined by the list_object provided.


json_list_object_array_value_add_boolean()	Add a new Boolean Value to a JSON Array, 
											defined by the list_object provided.

json_list_object_array_value_add_null()		Add a new null value to a JSON Array, defined 
											by the list_object provided.

json_list_object_array_value_add_list()		Add a new data value to an existing JSON 
											Array, that has as a value type of either a 
											JSON Array or JSON Object, defined by the 
											list_object provided.

json_path_to_list_object()					Convert a JSON dotted notation path to a 
											list_object for that path.
	
json_parse_dotted_path()					Create a set of links describing a JSON data
											path, by parsing  a character array with JSON
											dotted notion in it. 
	
json_generate_path_from_links()				Create a character array describing a set of 
											links in a JSON Data block for reporting or 
											printing purposes.
	
json_print_path_from_links()				Display to stdout text describing a set of 
											links in a JSON data block.


display_parsed_json_object()				This function will either display all the 
											elements in a single list_object, or will walk
											an entire hierarchy of list_objects displaying 
											the elements as it goes through them.
	


The elements in all the JSON lists, wither Object or Array can be sorted, 
and searched using the default search and compare functions that are attached 
to those lists when they are created.

All lists and elements are self cleaning, and will automatically remove any text
strings stored in them when the element is removed, or the list is erased.

Please refer to the json-parser.h header file and the D-List documentation for
more information.

















