IDocList/IDocDict JSON for Delphi and FPC

【英文原文】

多年來，我們的開源 mORMot 框架提供了多種方法來處理在運行時定義的數組/對象文檔的任意組合，例如通過 JSON，具有許多功能和非常高的性能。

我們的 TDocVariant自定義變體類型是處理這類無模式數據的一種強大方式，但一些用戶覺得它有些令人困惑。

因此，我們圍繞它開發了一套新的介面定義，以簡化其使用，同時不犧牲其功能。我們圍繞Python列表和字典對它們進行了建模，這已被證明是可行的——當然，也做了一些擴展。

TDocVariant的優缺點

多年來，我們的 TDocVariant可以存儲任何基於JSON/BSON的文檔內容，即：

• 面向對象文檔的名/值對——在內部被標識為 dvObject子類型；
• 面向數組文檔的值數組（包括嵌套文檔）——在內部被標識為 dvArray子類型；
• 通過嵌套 TDocVariant實例，可以實現上述兩者的任意組合。

每個 TDocVariant實例也是一個自定義的變體類型：

• 因此，您可以將它存儲或轉換為變體變數；
• 您可以使用後期綁定來訪問其對象屬性，這在現代Pascal的嚴格世界中有點像魔術；
• Delphi IDE（和Lazarus 3.x）調試器對其有原生支持，因此可以將變體內容顯示為JSON；
• 如果您在任何類或記錄中定義了變體類型，我們的框架將識別 TDocVariant內容，並將其序列化和反序列化為JSON，例如在其ORM、SOA或Mustache/MVC部分中。

這種強大功能也帶來了一些缺點：

• 在變體和其 TDocVariantData記錄之間切換可能很棘手，有時需要一些令人困惑的指針引用；
• 每個 TDocVariant實例都可以用作對其他數據的弱引用，或者維護其自身的內容——在某些極端情況下，不正確的使用可能會導致記憶體泄漏或GPF問題；
• TDocVariant可以是對象/字典或數組/列表，因此找到正確的方法可能很困難，或者在運行時引發異常；
• 它從一個簡單的存儲發展成了一個完整的記憶體引擎，因此高級功能通常被低估；
• TDocVariantData記錄與大多數Delphi/FPC用戶所習慣的類系統相去甚遠；
• 預設情況下，不解析雙精度值——只解析貨幣值——如果你不想損失任何精度，這是有意義的，但也被髮現會造成混淆。

抱怨夠了。

我們只需讓它變得更好。
引入IDocList和IDocDict介面

我們引入了兩個高級封裝介面類型：

• IDocList（或其別名IDocArray）用於存儲元素列表；
• IDocDict（或其別名IDocObject）用於存儲鍵值對字典。

介面方法和命名遵循通常的Python列表和字典，併在安全且專用於類的IDocList和IDocDict類型中封裝它們自己的TDocVariant存儲。

您可能會在現代Delphi中這樣寫：

var
  list: IDocList;
  dict: IDocDict;
  v: variant;
  i: integer;
begin  
  // 從項目創建一個新的列表/數組
  list := DocList([1, 2, 3, 'four', 1.0594631]); // 預設情況下允許雙精度值

  // 遍歷列表
  for v in list do
    Listbox1.Items.Add(v); // 將變數轉換為字元串

  // 或列表的一個子範圍（使用類似Python的負索引）
  for i in list.Range(0, -3) do
    Listbox2.Items.Add(IntToStr(i)); // [1, 2] 作為整數

  // 搜索某些元素的存在
  assert(list.Exists(2));
  assert(list.Exists('four'));

  // 從JSON中獲取一個對象列表，其中包含一個入侵者
  list := DocList('[{"a":0,"b":20},{"a":1,"b":21},"to be ignored",{"a":2,"b":22}]');

  // 枚舉所有對象/字典，忽略非對象元素
  for dict in list.Objects do
  begin
    if dict.Exists('b') then
      ListBox2.Items.Add(dict['b']);
    if dict.Get('a', i) then
      ListBox3.Items.Add(IntToStr(i));
  end;

  // 刪除一個元素
  list.Del(1);
  assert(list.Json = '[{"a":0,"b":20},"to be ignored",{"a":2,"b":22}]');

  // 提取一個元素
  if list.PopItem(v, 1) then
    assert(v = 'to be ignored');

  // 轉換為JSON字元串
  Label1.Caption := list.ToString;
  // 顯示 '[{"a":0,"b":20},{"a":2,"b":22}]'
end; 

以及更多高級功能，如排序、搜索和表達式過濾：

var
  v: variant;
  f: TDocDictFields;
  list, list2: IDocList;
  dict: IDocDict;
begin
  list := DocList('[{"a":10,"b":20},{"a":1,"b":21},{"a":11,"b":20}]');

  // 根據嵌套對象的欄位對列表/數組進行排序
  list.SortByKeyValue(['b', 'a']);
  assert(list.Json = '[{"a":10,"b":20},{"a":11,"b":20},{"a":1,"b":21}]');
  
  // 使用條件表達式枚舉列表/數組 :)
  for dict in list.Objects('b<21') do
    assert(dict.I['b'] < 21);

  // 使用變數作為條件表達式的另一個枚舉
  for dict in list.Objects('a=', 10) do
    assert(dict.I['a'] = 10);

  // 根據條件表達式創建新的IDocList
  list2 := list.Filter('b =', 20);
  assert(list2.Json = '[{"a":10,"b":20},{"a":11,"b":20}]');

  // 直接訪問內部TDocVariantData存儲
  assert(list.Value^.Count = 3);
  assert(list.Value^.Kind = dvArray);
  assert(dict.Value^.Kind = dvObject);
 
  // 通過變數中介獲取TDocVariantData
  v := list.AsVariant;
  assert(_Safe(v)^.Count = 3);
  v := dict.AsVariant;
  assert(_Safe(v)^.Count = 2);

  // 類似Python的高級方法
  if list.Len > 0 then
    while list.PopItem(v) do
    begin
      assert(list.Count(v) = 0); // 計算出現的次數
      assert(not list.Exists(v));
      Listbox1.Items.Add(v.a); // 後期綁定 
      dict := DocDictFrom(v); // 從變數轉換為IDocDict
      assert(dict.Exists('a') and dict.Exists('b'));
      // 枚舉此字典的鍵值元素
      for f in dict do
      begin
        Listbox2.Items.Add(f.Key);
        Listbox3.Items.Add(f.Value);
      end;
    end;

  // 從任何複雜的“緊湊”JSON創建
  // （註意鍵名沒有被“引用”）
  list := DocList('[{ab:1,cd:{ef:"two"}}]');

  // 我們仍然有後期綁定的魔法在工作
  assert(list[0].ab = 1);
  assert(list[0].cd.ef = 'two');

  // 從代碼中提供的鍵值對創建字典
  dict := DocDict(['one', 1, 'two', 2, 'three', _Arr([5, 6, 7, 'huit'])]);
  assert(dict.Len = 3); // 一個包含3個元素的字典
  assert(dict.Json = '{"one":1,"two":2,"three":[5,6,7,"huit"]}');

  // 轉換為帶有美觀格式（換行符和空格）的JSON
  Memo1.Caption := dic.ToString(jsonHumanReadable);

  // 按鍵名排序
  dict.Sort;
  assert(dict.Json = '{"one":1,"three":[5,6,7,"huit"],"two":2}');

  // 註意，它將在排序後確保更快的O(log(n))鍵查找：
  // （對於具有大量鍵的對象，這有利於提高性能）
  assert(dict['two'] = 2); // 作為變數值的預設查找
  assert(dict.I['two'] = 2); // 顯式轉換為整數
end;

以下是 TTextWriter.AddJsonReformat()方法及其 JsonBufferReformat()和 JsonReformat()封裝的可用JSON格式：

• jsonCompact是預設的、對機器友好的單行佈局
• jsonHumanReadable會添加換行符和縮進，以獲得更人性化的結果
• jsonUnquotedPropName將生成 jsonHumanReadable佈局，但只在必要時才引用所有屬性名稱：此格式可用於配置文件等場合 - 此格式與MongoDB擴展語法中使用的格式類似，與JSON不相容：不要與AJAX客戶端等一起使用，但它會被我們的所有單元按預期處理為有效的JSON輸入，而無需事先校正
• jsonUnquotedPropNameCompact將生成單行佈局，其中包含未引用的屬性名稱，這是mORMot實例中數據輸出量最小的方式
• 預設情況下，我們依賴於UTF-8編碼（在RFC 8259中是必需的），但您可以使用 jsonEscapeUnicode生成純7位ASCII輸出，其中非ASCII字元使用\u####轉義，例如預設的python json.dumps
• jsonNoEscapeUnicode會搜索任何\u####模式，並生成純UTF-8輸出
• 這些特性不是在此單元中實現，而是在mormot.core.json中實現

由於高級實例是介面，並且內部內容是變數，因此它們的使用壽命都是安全和正常的——您不需要編寫任何try..finaly list.Free代碼。

而且性能仍然很高，因為例如一個巨大的JSON數組會分配一個單獨的IDocList，所有嵌套的節點都將作為變體的有效動態數組來保存。

最後兩行代碼可能展示了我們的mORMot庫在Delphi和FPC的JSON庫森林/叢林中是如何獨樹一幟的：

assert(DocList('[{ab:1,cd:{ef:"two"}}]')[0].cd.ef = 'two');

assert(DocList('[{ab:1,cd:{ef:"two"}}]').First('ab<>0').cd.ef = 'two');

如果你與標準的Delphi JSON庫的工作方式進行比較，以及它與每個節點的類的工作方式，你可能會發現很大的不同！

請註意，這兩行代碼都可以用古老的Delphi 7編譯器進行編譯和運行——誰說Pascal語言在當年沒有表現力？

我們希望我們成功地開闢了一種與JSON文檔交互的新方式，這樣你就可以在你的Delphi或FPC項目中使用它。

一如既往，我們歡迎在我們的論壇中提供任何反饋！

順便說一句，你知道我為什麼在代碼中選擇1.0594631這個數字嗎？

提示：這是我在小時候使用Z80 CPU編程音樂時用過的東西……我仍然記得這個常數。