fcl-json: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		# General info
2	2
3	3		fcl-json is a [[JSON]] implementation.
4	4
5	5		It contains units such as:
6	6
7	7		- fpjson: base unit which implements TJsonData and its children, e.g. TJsonObject
8	8		- jsonParser: implements TJsonParser, used in the From JsonViewer example below
9	9		- jsonConf: implements TJsonConfig which is handy to read/write application data from/to files
10	10		- jsonScanner: json source lexical analyzer
11	11
12	12		Note: In fpjson, accessing e.g.
13	13
14	14		``` pascal
15	15		SomeJSONObject.Integers['price']
16	16		```
17	17
18	18		may give a SIGSEGV/Access Violation if that integer variable does not exist. This is apparently intentional, see [1](http://bugs.freepascal.org/view.php?id=22273). You'd have to use the Find method (available since FPC 2.6.2) to first check if the element ('price' in this example) exists.
19	19
20	20		# Streaming
21	21
22	22		fcl-json contains the unit "fpjsonrtti" which is used to load objects (TObject instances) from or save them to JSON format.
23	23
24	24		See [[Streaming JSON]] for a short example.
25	25
26	26		# Examples
27	27
28	28		## Getting Started
29	29
30	30		``` pascal
31	31		uses
32	32		fpjson, jsonparser;
33	33
34	34		procedure JSONTest;
35	35		var
36	36		jData : TJSONData;
37	37		jObject : TJSONObject;
38	38		jArray : TJSONArray;
39	39		s : String;
40	40		begin
41	41		// this is only a minimal sampling of what can be done with this API
42	42
43	43		// create from string
44	44		jData := GetJSON('{"Fld1" : "Hello", "Fld2" : 42, "Colors" : ["Red", "Green", "Blue"]}');
45	45
46	46		// output as a flat string
47	47		s := jData.AsJSON;
48	48
49	49		// output as nicely formatted JSON
50	50		s := jData.FormatJSON;
51	51
52	52		// cast as TJSONObject to make access easier
53	53		jObject := jData as TJSONObject;
54	54
55	55		// retrieve value of Fld1
56	56		s := jObject.Get('Fld1');
57	57
58	58		// change value of Fld2
59	59		jObject.Integers['Fld2'] := 123;
60	60
61	61		// retrieve the second color
62	62		s := jData.FindPath('Colors[1]').AsString;
63	63
64	64		// add a new element
65	65		jObject.Add('Happy', True);
66	66
67	67		// add a new sub-array
68	68		jArray := TJSONArray.Create;
69	69		jArray.Add('North');
70	70		jArray.Add('South');
71	71		jArray.Add('East');
72	72		jArray.Add('West');
73	73		jObject.Add('Directions', jArray);
74	74
75	75		end;
76	76		```
77	77
78	78		Note: it's necessary to free jData when you have finished with it. Otherwise a memory leak is created.
79	79
80	80		## Traversing Items
81	81
82	82		``` pascal
83	83		uses
84	84		Classes, TypInfo, fpjson, jsonparser;
85	85
86	86		procedure JSONItems(Info: TStrings);
87	87		var
88	88		jData : TJSONData;
89	89		jItem : TJSONData;
90	90		i, j: Integer;
91	91		object_name, field_name, field_value, object_type, object_items: String;
92	92		begin
93	93		jData := GetJSON('{"A":{"field1":0, "field2": false},"B":{"field1":0, "field2": false}}');
94	94
95	95		for i := 0 to jData.Count - 1 do
96	96		begin
97	97		jItem := jData.Items[i];
98	98
99	99		object_type := GetEnumName(TypeInfo(TJSONtype), Ord(jItem.JSONType));
100	100		object_name := TJSONObject(jData).Names[i];
101	101		WriteStr(object_items, jItem.Count);
102	102
103	103		Info.Append('object type: ' + object_type + '\|object name: ' + object_name + '\|number of fields: ' + object_items);
104	104
105	105		for j := 0 to jItem.Count - 1 do
106	106		begin
107	107		field_name := TJSONObject(jItem).Names[j];
108	108		field_value := jItem.FindPath(TJSONObject(jItem).Names[j]).AsString;
109	109
110	110		Info.Append(field_name + '\|' + field_value);
111	111		end;
112	112		end;
113	113
114	114		jData.Free;
115	115		end;
116	116		```
117	117
118	118		## Save/load form position to/from file
119	119
120	120		``` pascal
121	121		uses
122	122		jsonConf;
123	123
124	124		procedure SaveFormPos(AForm: TForm; const AFilename: string);
125	125		var
126	126		c: TJSONConfig;
127	127		begin
128	128		c:= TJSONConfig.Create(Nil);
129	129		try
130	130		//try/except to handle broken json file
131	131		try
132	132		c.Formatted:= true;
133	133		c.Filename:= AFilename;
134	134		except
135	135		exit;
136	136		end;
137	137
138	138		c.SetValue('/dialog/max', AForm.WindowState=wsMaximized);
139	139		if AForm.WindowState<>wsMaximized then
140	140		begin
141	141		c.SetValue('/dialog/posx', AForm.Left);
142	142		c.SetValue('/dialog/posy', AForm.Top);
143	143		c.SetValue('/dialog/sizex', AForm.Width);
144	144		c.SetValue('/dialog/sizey', AForm.Height);
145	145		end;
146	146		finally
147	147		c.Free;
148	148		end;
149	149		end;
150	150
151	151		procedure LoadFormPos(AForm: TForm; const AFilename: string);
152	152		var
153	153		nLeft, nTop, nW, nH: Integer;
154	154		c: TJSONConfig;
155	155		begin
156	156		c:= TJSONConfig.Create(Nil);
157	157		try
158	158		//try/except to handle broken json file
159	159		try
160	160		c.Formatted:= true;
161	161		c.Filename:= AFilename;
162	162		except
163	163		exit;
164	164		end;
165	165
166	166		nLeft:= c.GetValue('/dialog/posx', AForm.Left);
167	167		nTop:= c.GetValue('/dialog/posy', AForm.Top);
168	168		nW:= c.GetValue('/dialog/sizex', AForm.Width);
169	169		nH:= c.GetValue('/dialog/sizey', AForm.Height);
170	170		AForm.SetBounds(nLeft, nTop, nW, nH);
171	171
172	172		if c.GetValue('/dialog/max', false) then
173	173		AForm.WindowState:= wsMaximized;
174	174		finally
175	175		c.Free;
176	176		end;
177	177		end;
178	178		```
179	179
180	180		## Save/load TStringList
181	181
182	182		``` pascal
183	183		uses
184	184		jsonConf;
185	185		var
186	186		cfg: TJSONConfig;
187	187		List: TStringList;
188	188		path: string;
189	189		begin
190	190		List:= TStringList.Create;
191	191		cfg:= TJSONConfig.Create(nil);
192	192		try
193	193		//try/except to handle broken json file
194	194		try
195	195		cfg.Formatted:= true;
196	196		cfg.Filename:= AJsonFilename;
197	197		except
198	198		exit;
199	199		end;
200	200
201	201		cfg.GetValue('/mylist', List, '');
202	202		List.Add('some_value');
203	203		cfg.SetValue('/mylist', List);
204	204		finally
205	205		cfg.Free;
206	206		List.Free;
207	207		end;
208	208		```
209	209
210	210		## From JsonViewer
211	211
212	212		Example usage can be found in the Lazarus jsonviewer tool (located in lazarus/tools/jsonviewer). In particular, this part of the tool shows how to use json:
213	213
214	214		``` pascal
215	215		procedure TMainForm.OpenFile(Const AFileName : String);
216	216		var
217	217		S : TFileStream;
218	218		P : TJSONParser;
219	219		D : TJSONData;
220	220		begin
221	221		S:=TFileStream.Create(AFileName,fmOpenRead);
222	222		try
223	223		P:=TJSONParser.Create(S);
224	224		try
225	225		P.Strict:=FStrict;
226	226		D:=P.Parse;
227	227		finally
228	228		P.Free;
229	229		end;
230	230		finally
231	231		S.Free;
232	232		end;
233	233		FFileName:=AFileName;
234	234		SetCaption;
235	235		FreeAndNil(FRoot);
236	236		FRoot:=D;
237	237		ShowJSONDocument;
238	238		end;
239	239
240	240		procedure TMainForm.ShowJSONDocument;
241	241		begin
242	242		with TVJSON.Items do
243	243		begin
244	244		BeginUpdate;
245	245		try
246	246		TVJSON.Items.Clear;
247	247		SHowJSONData(Nil,FRoot);
248	248		with TVJSON do
249	249		if (Items.Count>0) and Assigned(Items[0]) then
250	250		begin
251	251		Items[0].Expand(False);
252	252		Selected:=Items[0];
253	253		end;
254	254		finally
255	255		EndUpdate;
256	256		end;
257	257		end;
258	258		end;
259	259
260	260		procedure TMainForm.ShowJSONData(AParent : TTreeNode; Data : TJSONData);
261	261		var
262	262		N,N2 : TTreeNode;
263	263		I : Integer;
264	264		D : TJSONData;
265	265		C : String;
266	266		S : TStringList;
267	267		begin
268	268		N:=Nil;
269	269		if Assigned(Data) then
270	270		begin
271	271		case Data.JSONType of
272	272		jtArray,
273	273		jtObject:
274	274		begin
275	275		if (Data.JSONType=jtArray) then
276	276		C:=SArray
277	277		else
278	278		C:=SObject;
279	279		N:=TVJSON.Items.AddChild(AParent,Format(C,[Data.Count]));
280	280		S:=TstringList.Create;
281	281		try
282	282		for I:=0 to Data.Count-1 do
283	283		if Data.JSONtype=jtArray then
284	284		S.AddObject(IntToStr(I),Data.items[i])
285	285		else
286	286		S.AddObject(TJSONObject(Data).Names[i],Data.items[i]);
287	287		if FSortObjectMembers and (Data.JSONType=jtObject) then
288	288		S.Sort;
289	289		for I:=0 to S.Count-1 do
290	290		begin
291	291		N2:=TVJSON.Items.AddChild(N,S[i]);
292	292		D:=TJSONData(S.Objects[i]);
293	293		N2.ImageIndex:=ImageTypeMap[D.JSONType];
294	294		N2.SelectedIndex:=ImageTypeMap[D.JSONType];
295	295		ShowJSONData(N2,D);
296	296		end
297	297		finally
298	298		S.Free;
299	299		end;
300	300		end;
301	301		jtNull:
302	302		N:=TVJSON.Items.AddChild(AParent,SNull);
303	303		else
304	304		N:=TVJSON.Items.AddChild(AParent,Data.AsString);
305	305		end;
306	306		if Assigned(N) then
307	307		begin
308	308		N.ImageIndex:=ImageTypeMap[Data.JSONType];
309	309		N.SelectedIndex:=ImageTypeMap[Data.JSONType];
310	310		N.Data:=Data;
311	311		end;
312	312		end;
313	313		end;
314	314		```
315	315
316	316		## Change formatting of float numbers
317	317
318	318		Q: My program generates and writes data to JSON file. I use FormatJSON() method to make output more readable. I'm not quite satisfied how numbers with float point look:
319	319
320		-	~~`"coordinates" : [`\~~
321		-	~~` 5.5978631048365003E+001,`\~~
322		-	~~` 2.2100000000000000E+002`\~~
323		-	~~`]`~~
	320	+	```text
	321	+	"coordinates" : [
	322	+	5.5978631048365003E+001,
	323	+	2.2100000000000000E+002
	324	+	]
	325	+	```
324	326
325	327		I want to see normal form:
326	328
327		-	~~`"coordinates" : [`\~~
328		-	~~` 55.978631048365003,`\~~
329		-	~~` 221.0`\~~
330		-	~~`]`~~
	329	+	```text
	330	+	"coordinates" : [
	331	+	55.978631048365003,
	332	+	221.0
	333	+	]
	334	+	```
331	335
332	336		A (forum members y.ivanov, rvk, wp):
333	337
334	338		``` pascal
335	339		{$mode objfpc}{$h+}
336	340		uses
337	341		fpjson,
338	342		jsonparser,
339	343		SysUtils;
340	344
341	345		type
342	346		TJSONFloat4Number = class(TJSONFloatNumber)
343	347		protected
344	348		function GetAsString: TJSONStringType; override;
345	349		end;
346	350
347	351		function TJSONFloat4Number.GetAsString: TJSONStringType;
348	352		var
349	353		F: TJSONFloat;
350	354		fs: TFormatSettings;
351	355		begin
352	356		fs := DefaultFormatSettings;
353	357		fs.DecimalSeparator := '.';
354	358		F := GetAsFloat;
355	359		Result := FormatFloat('0.0###############', F, fs); // format with your preferences
356	360		end;
357	361
358	362		procedure JSONTest;
359	363		var
360	364		jData: TJSONData;
361	365		begin
362	366		jData := GetJSON('{"coordinates": [5.5978631048365003E+001, 2.2100000000000000E+002]}');
363	367		writeln(jData.FormatJSON);
364	368		jData.Free;
365	369		end;
366	370
367	371		begin
368	372		SetJSONInstanceType(jitNumberFloat, TJSONFloat4Number);
369	373		JSONTest;
370	374		Readln;
371	375		end.
372	376		```
373	377
374	378		## See also
375	379
376	380		- The FpcTwit example in the [[Components and Code examples]] library makes use of JSON to send/receive data.
377	381		- [FCL Reference](https://lazarus-ccr.sourceforge.io/fpcdoc/fcl/fpjson/index.html) for unit fpjson.
378	382		- [An article (PDF)](http://www.freepascal.org/~michael/articles/webdata/webdata.pdf) covering use of XML and JSON in FreePascal.
379	383		- [[Package List]]
380	384
381	385		---
382	386		From the Free Pascal wiki, page "fcl-json", as it stood on 2022-10-06 after a change by Alextp, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history