TclJSONObject

The TCLJSONObject class represents a JSON object composed of key–value pairs. It provides structured methods to add, remove, clone, merge, and retrieve data. Objects can contain nested objects or arrays, allowing hierarchical and deeply structured JSON representations. TCLJSONObject ensures type safety by operating with TCLJSONValue, preventing data inconsistency during serialization and deserialization.

Information: JSON Object Structure

A JSON object is an unordered collection of name–value pairs, where each name is a string and the value may be a string, number, boolean, array, or another object.

Example: {"name":"Alice","age":25,"active":true}

Feature	Use of	Definition
AddPair	obj.AddPair('name', TCLJSONValue.Str('John'));	Adds a new key–value pair to the JSON object. Updates the value if the key already exists.
AddObject	obj.AddObject('address', childObj);	Adds a new JSON object under the specified key, enabling nested structures.
AddArray	obj.AddArray('items', arr);	Stores a JSON array under the specified key, supporting complex data structures.
RemovePair	obj.RemovePair('age');	Removes the key–value pair with the specified key name from the JSON object.
GetValue	val = obj.GetValue('name');	Returns the value for the specified key. Returns nil if the key does not exist.
SetValue	obj.SetValue('active', TCLJSONValue.Bool(False));	Updates the value of an existing key or adds the key if it doesn’t exist.
GetValueByPath	val = obj.GetValueByPath('address.city');	Provides direct access to nested values using dot notation, e.g., "address.city".
GetValueAsPair	pair = obj.GetValueAsPair(0);	Returns the key–value pair at the specified index. Useful for iteration.
HasKey	obj.HasKey('status');	Checks whether the specified key exists in the JSON object.
Clone	copyObj = obj.Clone;	Creates a deep copy of the JSON object, completely independent of the original.
Merge	obj.Merge(extraObj);	Merges all key–value pairs from another JSON object into the current one. Overwrites existing keys.
ToJSONString	jsonStr = obj.ToJSONString;	Converts the object to a formatted JSON string for file saving or data transmission.
Count	count = obj.Count;	Returns the total number of key–value pairs in the JSON object.
Clear	obj.Clear;	Completely clears the object, removing all stored data.

Important: Nested Object Access

Use GetValueByPath to access deeply nested elements. Example: user.GetValueByPath('account.details.email') returns the email value from a nested JSON structure.

Important Notes

• All key names in TCLJSONObject are case-sensitive.
• Nested paths must use dot notation.
• When merging objects, existing keys are overwritten by the new object’s values.
• Use Clone for duplication instead of manual re-construction to preserve data integrity.
• Always free JSON objects after use to avoid memory leaks.

Example: TCLJSONObject in Use

var
  MyForm: TClForm;
  NameEdt, AgeEdt, CityEdt: TClProEdit;
  ActiveChk: TClCheckBox;
  CreateBtn, MergeBtn, ShowBtn: TClProButton;
  OutputMemo: TClMemo;
  Obj, Child, Extra: TCLJSONObject;
  Val: TCLJSONValue;

void CreateJSONObject
{
  Obj = TCLJSONObject.Create;
  Child = TCLJSONObject.Create;
  Extra = TCLJSONObject.Create;

  // User input values
  Obj.AddPair('name', TCLJSONValue.Str(NameEdt.Text));
  Obj.AddPair('age', TCLJSONValue.Int(StrToIntDef(AgeEdt.Text, 0)));
  Obj.AddPair('active', TCLJSONValue.Bool(ActiveChk.IsChecked));

  // Nested object (address)
  Child.AddPair('city', TCLJSONValue.Str(CityEdt.Text));
  Obj.AddObject('address', Child);

  // Merge with extra info
  Extra.AddPair('status', TCLJSONValue.Str('OK'));
  Obj.Merge(Extra);

  // Show final JSON
  OutputMemo.Lines.Text = Obj.ToJSONString;
}

void ShowNestedValue
{
  Val = Obj.GetValueByPath('address.city');
  ShowMessage('City: ' + Val.AsString);
}

void MergeExample
var
  NewObj: TCLJSONObject;
{
  NewObj = TCLJSONObject.Create;
  NewObj.AddPair('role', TCLJSONValue.Str('Admin'));
  Obj.Merge(NewObj);
  OutputMemo.Lines.Text = Obj.ToJSONString;
}

{
  MyForm = TClForm.Create(Self);

  // Input fields
  NameEdt = MyForm.AddNewProEdit(MyForm, 'NameEdt', 'Enter name...');
  NameEdt.Align = alTop;
  NameEdt.Height = 35;
  NameEdt.Margins.Top = 10;
  NameEdt.Margins.Left = 10;
  NameEdt.Margins.Bottom = 10;
  NameEdt.Margins.Right = 10;

  AgeEdt = MyForm.AddNewProEdit(MyForm, 'AgeEdt', 'Enter age...');
  AgeEdt.Align = alTop;
  AgeEdt.Height = 35;
  AgeEdt.Margins.Top = 10;
  AgeEdt.Margins.Right = 10;
  AgeEdt.Margins.Left = 10;
  AgeEdt.Margins.Bottom = 10;

  CityEdt = MyForm.AddNewProEdit(MyForm, 'CityEdt', 'Enter city...');
  CityEdt.Align = alTop;
  CityEdt.Height = 35;
  CityEdt.Margins.Top = 10;
  CityEdt.Margins.Right = 10;
  CityEdt.Margins.Left = 10;
  CityEdt.Margins.Bottom = 10;

  ActiveChk = MyForm.AddNewCheckBox(MyForm, 'ActiveChk', 'Is Active?');
  ActiveChk.Align = alTop;
  ActiveChk.Margins.Left = 10;

  // Output area
  OutputMemo = MyForm.AddNewMemo(MyForm, 'OutputMemo', 'JSON Output');
  OutputMemo.Align = alClient;
  OutputMemo.Height = 180;
  OutputMemo.Margins.Left = 10;
  OutputMemo.Margins.Right = 10;
  OutputMemo.TextSettings.WordWrap = True;

  // Buttons
  CreateBtn = MyForm.AddNewProButton(MyForm, 'CreateBtn', 'Create JSON Object');
  CreateBtn.Align = alBottom;
  CreateBtn.OnClick = 'CreateJSONObject';

  ShowBtn = MyForm.AddNewProButton(MyForm, 'ShowBtn', 'Show Nested Value');
  ShowBtn.Align = alBottom;
  ShowBtn.OnClick = 'ShowNestedValue';

  MergeBtn = MyForm.AddNewProButton(MyForm, 'MergeBtn', 'Merge Extra Object');
  MergeBtn.Align = alBottom;
  MergeBtn.OnClick = 'MergeExample';

  MyForm.Run;
}

Output:

See Also

• TclJSONArray
• TclJSONValue
• TclJSONPair
• TclJSON