Reference for unit 'fpjson'

JSON support for Free Pascal.

Overview

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 TJSONData.AsJSON. The generated JSON can be formatted in several ways TJSONData.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.