From a2b0292cdbc510320f8973f1b01d3b9e9bfc9e07 Mon Sep 17 00:00:00 2001 From: michael Date: Mon, 13 Sep 2010 21:40:17 +0000 Subject: [PATCH] * Some minimal documentation git-svn-id: trunk@15978 - --- .gitattributes | 1 + packages/fcl-json/src/README.txt | 163 +++++++++++++++++++++++++++++++ 2 files changed, 164 insertions(+) create mode 100644 packages/fcl-json/src/README.txt diff --git a/.gitattributes b/.gitattributes index e035bbeb8e..17226791a1 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2014,6 +2014,7 @@ packages/fcl-json/examples/parsedemo.pp svneol=native#text/plain packages/fcl-json/examples/simpledemo.lpi svneol=native#text/plain packages/fcl-json/examples/simpledemo.pp svneol=native#text/plain packages/fcl-json/fpmake.pp svneol=native#text/plain +packages/fcl-json/src/README.txt svneol=native#text/plain packages/fcl-json/src/fpjson.pp svneol=native#text/plain packages/fcl-json/src/jsonconf.pp svneol=native#text/plain packages/fcl-json/src/jsonparser.pp svneol=native#text/plain diff --git a/packages/fcl-json/src/README.txt b/packages/fcl-json/src/README.txt new file mode 100644 index 0000000000..ee07f13c70 --- /dev/null +++ b/packages/fcl-json/src/README.txt @@ -0,0 +1,163 @@ +This package implements JSON support for FPC. + +JSON support consists of 3 parts: + +unit fpJSON contains the data representation. Basically, it defines a set of +classes: + +TJSONData ++- TJSONNumber + +- TJSONIntegerNumber + +- TJSONFloatNumber + +- TJSONInt64Number ++- TJSONString ++- TJSONBoolean ++- TJSONNull ++- TJSONObject ++- TJSONArray + +The TJSONData.JSONType property is an enumerated: +TJSONtype = (jtUnknown, jtNumber, jtString, jtBoolean, jtNull, jtArray, jtObject); + +Which allows to determine the type of a value. + +The following methods exist: + +Procedure Clear; + Clears the value. For arrays and objects, removes all elements/members +Function Clone : TJSONData; + Creates an exact replica of the valye +property Count: Integer; + For simple values this is zero, for complex values this is the number of + elements/members. Read only. +property Items[Index: Integer]: TJSONData + For simple values, reading this will result in an error. For complex + values, this gives access to the members. +property Value: variant; + The value as a variant. Only for simple values. +Property AsString : TJSONStringType: + The value as a string. Only for simple values. +Property AsFloat : TJSONFloat; + The value as a float (double). only for simple values. +Property AsInteger : Integer ; + The value as an integer. only for simple values. +Property AsInt64 : Int64; + The value as an 64-bit integer. only for simple values. +Property AsBoolean : Boolean ; + The value as a boolean. +Property IsNull : Boolean ; + Is the value Null ? +Property AsJSON : TJSONStringType + Return the value in JSON notation. For simple and complex values. + +The TJSONArray type provides access to the elements in the array in the +following ways: + +Property Types[Index : Integer] : TJSONType; + Indexed access to the types of the elements in the array. +Property Nulls[Index : Integer] : Boolean + Checks if the Index-the element is NULL. +Property Integers[Index : Integer] : Integer + Read/Write element values as integers. +Property Int64s[Index : Integer] : Int64 + Read/Write element values as 64-bit integers. +Property Strings[Index : Integer] : TJSONStringType; + Read/Write element values as strings. +Property Floats[Index : Integer] : TJSONFloat ; + Read/Write element values as floats (doubles). +Property Booleans[Index : Integer] : Boolean; + Read/Write element values as booleans. +Property Arrays[Index : Integer] : TJSONArray; + Read/Write element values as arrays. +Property Objects[Index : Integer] : TJSONObject; + Read/Write element values a strings + +Reading an element as a type which is incompatible, will result in an +exception. For instance if element 5 is an object value, then the following +will result in an exception: + i:=i+Array.Integers[5] + +The TJSONObject type similarly provides access to the elements in the array +using the member names: +property Names[Index : Integer] : TJSONStringType; + Indexed access to the member names. +property Elements[AName: string] : TJSONData; + Read/Write a member as a raw TJSONData value. +Property Types[AName : String] : TJSONType Read GetTypes; + Read/Write the type of a member. +Property Nulls[AName : String] : Boolean; + Read/Write a member as a NULL value. +Property Floats[AName : String] : TJSONFloat; + Read/Write a member as a float value (double) +Property Integers[AName : String] : Integer; + Read/Write a member as an integer value +Property Int64s[AName : String] : Int64; + Read/Write a member as an 64-bit integer value +Property Strings[AName : String] : TJSONStringType; + Read/Write a member as a string value. +Property Booleans[AName : String] : Boolean; + Read/Write a member as a boolean value. +Property Arrays[AName : String] : TJSONArray; + Read/Write a member as an array value. +Property Objects[AName : String] : TJSONObject + Read/Write a member as an object value. + +Members can be added with the Add() call, which exists in various overloaded +forms: + function Add(const AName: TJSONStringType; Const AValue): Integer; +Where the type of AVAlue is one of the supported types: +integer, int64, double, string, TJSONArray or TJSONObject. + +The Delete() call deletes an element from an array or object. + +Important remark: +The array and object classes own their members: the members are destroyed as +they are deleted. For this, the Extract() call exists: it removes an +element/member from the array/object, without destroying it. + +The JSONSCanner unit contains a scanner for JSON data: TJSONScanner. +Currently it does not support full unicode, only UTF-8 is supported. + +The JSONParser unit contains the parser for JSON data: TJSONParser. +It uses to scanner to read the tokens. The scanner is created automatically. + + +The Parse method will parse the data that was passed to the parser and will +return the JSON value. + +Sample use: + +Var + P : TJSONParser; + S : String; + D : TJSONObject; + +begin + P:=TJSONParser.Create('{ "top": 10, "left": 20}'); + try + D:=P.Parse as TJSONObject; + Writeln('Top : ',D.Integers['top']); + Writeln('Left : ',D.Integers['left']); + D.free; + Finally + P.free; + end; +end; + +Note that the member names are case sensitive. + +As an alternative, a stream may be passed to the constructor of TJSONParser. + +The scanner and parser support the 'Strict' property. +Strict JSON syntax requires the member names of an object to be strings: +{ "top": 10, "left": 20} +However, due to the sloppy definition of Javascript (and hence JSON), +the following type of JSON notation is frequently encountered: +{ top: 10, left: 20} +By default, this sloppy notation is accepted. Setting 'Strict' to true will +reject this. + +A second effect of the Strict property is the requirement of " as a string +delimiter. A single quote is also often found in Javascript and JSON: +{ title: 'A nice title' } +By default, this is accepted. Setting 'Strict' to true will reject this.