View source for TclJSON

TCLJSON is a structured and type-safe JSON processing library designed to facilitate the creation, manipulation, and validation of JSON data. It enables the definition of objects, arrays, and values representing standard JSON types, including strings, numbers, booleans, and null elements.

The library provides mechanisms for constructing hierarchical data models, performing key-value pair operations, merging multiple JSON structures, and retrieving nested elements through deep path access. TCLJSON ensures strict compliance with JSON syntax rules, offering validation methods to verify data integrity during parsing and serialization.

In addition to in-memory operations, TCLJSON supports persistent data handling through file-based loading and saving of JSON content. Its strongly typed architecture promotes reliability, consistency, and maintainability in applications that require structured data representation, configuration management, or data exchange using the JSON format.


<div style="margin-bottom: 20px;">
{| class="infobox" style="width: 100%; border: 1px solid #007bff; background-color: #e6f7ff; border-radius: 5px; padding: 15px; border-collapse: separate;"
| style="font-weight: bold; color: #007bff; padding-bottom: 5px;" | Information: What is TCLJSON?
|-
| style="padding-top: 5px;" | TCLJSON allows you to create, manipulate, and serialize JSON data structures. It supports nested objects, arrays, type-safe values, deep path access, merging, cloning, and file operations.
|}
</div>

<div class="table-responsive" style="margin-bottom: 20px;">
{| class="wikitable" style="width:100%"
! Class !! Description
|-
| [[TCLJSONArray]] || Represents a JSON array with ordered values. Supports adding/removing values or objects, merging, cloning, and enumeration.
|-
| [[TCLJSONObject]] || Represents a JSON object with key-value pairs. Provides methods for adding, removing, merging, cloning, and deep path access.
|-
| [[TCLJSONPair]] || Represents a single key-value pair inside a JSON object.
|-
| [[TCLJSONValue]] || Encapsulates a JSON value (string, integer, number, boolean, datetime, or null) and provides type-safe methods.
|}
</div>

<div style="margin-bottom: 20px;">
{| class="infobox" style="width: 100%; border: 1px solid #28a745; background-color: #d4edda; border-radius: 5px; padding: 15px; border-collapse: separate;"
| style="font-weight: bold; color: #28a745; padding-bottom: 5px;" | Important: Type-Safe JSON Values
|-
| TCLJSONValue provides class functions like '''Str''', '''Int''', '''Bool''', '''Num''', '''DT''', and '''Null''' to safely create JSON values without manual conversion.
|}
</div>

<div class="table-responsive" style="margin-bottom: 20px;">
{| class="wikitable" style="border: 2px solid #c3d7e0; width:100%"
! style="background-color: #c3d7e0"| Feature
! style="background-color: #c3d7e0"| Use of
! style="background-color: #c3d7e0"| Definition
|-
| '''TCLJSONObject''' || obj : TCLJSONObject; || Creates a variable for JSON object.
|-
| '''TCLJSONArray''' || arr : TCLJSONArray; || Creates a variable for JSON array.
|-
| '''AddPair''' || obj.AddPair('key', TCLJSONValue.Str('value')); || Adds a key-value pair to JSON object.
|-
| '''AddObject''' || obj.AddObject('child', ChildObj); || Adds a nested JSON object.
|-
| '''AddArray''' || obj.AddArray('letters', Arr); || Adds a JSON array inside object.
|-
| '''Merge''' || obj.Merge(ExtraObj); || Merges another object into current.
|-
| '''GetValueByPath''' || val = obj.GetValueByPath('level1.level2'); || Retrieves a value from nested path.
|-
| '''ToJSONString''' || obj.ToJSONString; || Converts object/array to JSON string.
|-
| '''IsValidJSON''' || TCLJSON.IsValidJSON(str); || Checks if string is valid JSON.
|-
| '''SaveObjectToFile''' || TCLJSON.SaveObjectToFile(obj, 'file.json'); || Saves JSON object to file.
|}
</div>


=== Example: TCLJSON in Action ===
<pre>
var
  MyForm: TClForm;
  NameEdt, AgeEdt: TClProEdit;
  ActiveChk: TClCheckBox;
  ShowBtn: TClProButton;
  ResultMemo: TClMemo;

void GenerateJSON
var
  Obj, Child, Extra: TCLJSONObject;
  Arr: TCLJSONArray;
  Val: TCLJSONValue;
{
  try
    // Main JSON object
    Obj = TCLJSONObject.Create;
    try
      Obj.AddPair('name', TCLJSONValue.Str(NameEdt.Text));
      Obj.AddPair('age', TCLJSONValue.Int(StrToInt(AgeEdt.Text)));
      Obj.AddPair('active', TCLJSONValue.Bool(ActiveChk.isChecked));

      // Nested object
      Child = TCLJSONObject.Create;
      Child.AddPair('ChildLevel', TCLJSONValue.Str('This is a deep value'));
      Obj.AddObject('ParentLevel', Child);

      // Array
      Arr = TCLJSONArray.Create;
      Arr.AddValue(TCLJSONValue.Str('X'));
      Arr.AddValue(TCLJSONValue.Str('Y'));
      Arr.AddValue(TCLJSONValue.Str('Z'));
      Obj.AddArray('letters', Arr);

      // Merge object
      Extra = TCLJSONObject.Create;
      Extra.AddPair('status', TCLJSONValue.Str('ok'));
      Obj.Merge(Extra);

      // Deep value access (Optional)
      Val = Obj.GetValueByPath('ParentLevel.ChildLevel');

      // Add JSON to Memo
      ResultMemo.Lines.Text = Obj.ToJSONString;

      // Deep value shown (Optional)
      ShowMessage('Deep value: ' + Val.AsString);

    except
      ShowMessage('Error: ' + LastExceptionMessage);
    }
  except
    ShowMessage('Unexpected Error: ' + LastExceptionMessage);
  }
}

{
  MyForm = TClForm.Create(Self);

  NameEdt = MyForm.AddNewProEdit(MyForm,'NameEdt','Name');
  NameEdt.Align = alTop;
  NameEdt.Height = 35;
  NameEdt.Margins.Left = 25;
  NameEdt.Margins.Bottom = 25;
  NameEdt.Margins.Right = 25;

  AgeEdt = MyForm.AddNewProEdit(MyForm,'AgeEdt','Age');
  AgeEdt.Align = alTop;
  AgeEdt.Height = 35;
  AgeEdt.Margins.Left = 25;
  AgeEdt.Margins.Bottom = 25;
  AgeEdt.Margins.Right = 25;

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

  ResultMemo = MyForm.AddNewMemo(MyForm,'ResultMemo','JSON Output');
  ResultMemo.Align = alClient;
  ResultMemo.Height = 200;
  ResultMemo.StyledSettings = ssFamily;
  ResultMemo.TextSettings.WordWrap = True;

  ShowBtn = MyForm.AddNewProButton(MyForm,'ShowBtn','Show JSON');
  ShowBtn.Align = alBottom;
  ShowBtn.Margins.Left = 15;
  ShowBtn.Margins.Right = 15;
  ShowBtn.Margins.Bottom = 10;
  ShowBtn.OnClick = 'GenerateJSON';

  MyForm.Run;
}


</pre>

Output:

[[File:TCLJSONExample.png|frameless|700px]]<br>

<h2> See Also </h2>
* [[TCLJSONObject]]
* [[TCLJSONArray]]
* [[TCLJSONValue]]
* [[TCLJSONPair]]

{{#seo:|title=TCLJSON Library Overview - Clomosy Docs}}
{{#seo:|description=Learn how to create, manipulate, validate, and save JSON objects and arrays using TCLJSON, with examples and type-safe value handling.}}