fpJson unit

JSON support for Free Pascal.

The JSON unit implements JSON support for Free Pascal. It contains the data structures (TJSONData and descendent objects) to treat JSON data and output JSON as a string AsJSON. The generated JSON can be formatted in several ways FormatJSON.

Using the JSON data structures is simple. Instantiate an appropriate descendent of TJSONData, set the data and call AsJSON. The following JSON data types are supported:

Numbers: in one of TJSONIntegerNumber, TJSONFloatNumber or TJSONInt64Number, depending on the type of the number.
Strings: in TJSONString.
Boolean: in TJSONBoolean.
null: is supported using TJSONNull
Array: is supported using TJSONArray
Object: is supported using TJSONObject

The constructors of these objects allow to set the value, making them very easy to use. The memory management is automatic in the sense that arrays and objects own their values, and when the array or object is freed, all data in it is freed as well.

Typical use would be:

Var
  O : TJSONObject;

begin
  O:=TJSONObject.Create(['Age',44,
                         'Firstname','Michael',
                         'Lastname','Van Canneyt']);
  Writeln(O.AsJSON);
  Write('Welcome ',O.Strings['Firstname'],', ');
  Writeln(O.Get('Lastname','')); // empty default.
  Writeln(', your current age is ',O.Integers('Age']);
  O.Free;
end;

The TJSONArray and TJSONObject classes offer methods to examine, get and set the various members and search through the various members.

Currently the JSON support only allows the use of UTF-8 data.

Parsing incoming JSON and constructing the JSON data structures is not implemented in the fpJSON unit. For this, the jsonscanner unit must be included in the program unit clause. This sets several callback hooks (using SetJSONParserHandler and then the GetJSON function can then be used to transform a string or stream to JSON data structures:

uses fpjson, jsonparser;

Var
  D,E : TJSONData;

begin
  D:=GetJSON('{ "Children" : ['+
             '  { "Age" : 23, '+
             '    "Names" : { "LastName" : "Rodriquez",'+
             '                "FirstName" : "Roberto" }},'+
             '  { "Age" : 20,'+
             '    "Names" : { "LastName" : "Rodriquez",'+
             '                "FirstName" : "Maria" }}'+
             '  ]}');
  E:=D.FindPath('Children[1].Names.FirstName');
  Writeln(E.AsJSON);
  D.Free;
end.

will print "Maria".

The FPJSON code does not use hardcoded class names when creating the JSON: it uses the various CreateJSON functions to create the data. These functions use a registry of classes, so it is possible to create descendents of the classes in the fpjson unit and have these used for construction of JSON Data structures. The GetJSONInstanceType and SetJSONInstanceType functions can be used to get or set the classes that must be used. the default parser used by GetJSON will also use these functions.

Classes and records

`EJSON`	class	JSON exception.
`TBaseJSONEnumerator`	class	JSON enumerator.
`TJSONArray`	class	Class of TJSONArray.
`TJSONBoolean`	class	Class to represent boolean JSON data.
`TJSONData`	class	Base (abstract) object for all JSON based data types.
`TJSONEnum`	record	JSON enumerator loop variable type.
`TJSONFloatNumber`	class	Class to represent floating-point JSON data.
`TJSONInt64Number`	class	Class to represent 64-bit integer JSON data.
`TJSONIntegerNumber`	class	Class to represent 32-bit integer JSON data.
`TJSONNull`	class	Class to represent boolean JSON data.
`TJSONNumber`	class	Common ancestor for the numerical value JSON classes.
`TJSONObject`	class	Class of TJSONObject.
`TJSONQWordNumber`	class	Class to represent 64-bit unsigned integer JSON data.
`TJSONString`	class	Class to represent string JSON data.

Procedures and functions

`CreateJSON`	function	Create a JSON data item.
`CreateJSONArray`	function	Create a JSON array.
`CreateJSONObject`	function	Create a JSON object.
`GetJSON`	function	Convert JSON string to JSON data structure.
`GetJSONInstanceType`	function	JSON factory: Get the JSONData class types to use.
`GetJSONParserHandler`	function	Get the current JSON parser handler.
`GetJSONStringParserHandler`	function	return the current JSON string to JSON Data conversion callback.
`JSONStringToString`	function	Convert a JSON-escaped string to a string.
`JSONTypeName`	function	Convert a JSON type to a string.
`SetJSONInstanceType`	function	JSON factory: Set the JSONData class types to use.
`SetJSONParserHandler`	function	Set the JSON parser handler.
`SetJSONStringParserHandler`	function	Install a JSON string to JSON Data conversion callback.
`StringToJSONString`	function	Convert a string to a JSON-escaped string.

Types

`PJSONCharType`	type	Pointer to TJSONCharType, used in parsing.
`TFormatOption`	enumeration	Formatting options for FormatJSON.
`TFormatOptions`	set	Set of TFormatOption options.
`TFPJSStream`	type	Stream alias type.
`TJSONArrayClass`	type	Class of TJSONArray.
`TJSONArrayIterator`	procedure type	Iterator callback for TJSONArray.Iterate.
`TJSONBooleanClass`	type	Class of TJSONBoolean.
`TJSONCharType`	type	Character type used in parsing.
`TJSONDataClass`	type	Class of TJSONData.
`TJSONFloat`	type	Float type used in JSON unit.
`TJSONFloatNumberClass`	type	Class of TJSONFloatNumber.
`TJSONInstanceType`	enumeration	Type of instance to create.
`TJSONInt64NumberClass`	type	Class of TJSONInt64Number.
`TJSONIntegerNumberClass`	type	Class of TJSONIntegerNumber.
`TJSONLargeInt`	type	Alias type.
`TJSONLargeIntNumber`	type	Class for TLargeInt value.
`TJSONLargeIntNumberClass`	type	Class reference for TJSONLargeIntNumberClass.
`TJSONNullClass`	type	Class of TJSONNull.
`TJSONNumberType`	enumeration	Enumerate the different kind of numerical types.
`TJSONObjectClass`	type	Class of TJSONObject.
`TJSONObjectIterator`	procedure type	Iterator callback for TJSONObject.Iterate.
`TJSONParserHandler`	procedure type	Callback to parse JSON into JSONData.
`TJSONQWordNumberClass`	type	Class of TJSONQWordNumber.
`TJSONStringClass`	type	Class of TJSONString.
`TJSONStringParserHandler`	procedure type	JSON String value parser handler prototype.
`TJSONStringType`	type	String type used in JSON unit.
`TJSONtype`	enumeration	Possible types of JSON data.
`TJSONUnicodeStringType`	type	Alias for Unicode strings.
`TJSONVariant`	type	Variant alias type.

Constants

`ActualValueJSONTypes`	constant	Set constant with JSON types of non-structured values that are not null.
`AsCompactJSON`	constant	Constant to format JSON with minimal whitespace and unquoted property names.
`AsCompressedJSON`	constant	Constant to format JSON with minimal whitespace.
`AsJSONFormat`	constant	Formatting options to reproduce JSON.
`DefaultFormat`	constant	Default formatting options.
`DefaultIndentSize`	constant	Default indent size for formatted JSON.
`jitNumberLargeInt`	constant	LargeInt type definition.
`StructuredJSONTypes`	constant	Set constant with JSON types of structured values.
`ValueJSONTypes`	constant	Set constant with JSON types of non-structured values.

Uses

An experiment, built from development snapshots. Not the official Free Pascal or Lazarus documentation.