IDocList/IDocDict JSON for Delphi and FPC

海利鸟發表於2024-05-23
JSON

IDocList/IDocDict JSON for Delphi and FPC

【英文原文】

多年來，我們的開源 mORMot 框架提供了多種方法來處理在執行時定義的陣列/物件文件的任意組合，例如透過 JSON，具有許多功能和非常高的效能。

img

我們的 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程式設計音樂時用過的東西……我仍然記得這個常數。😄

相關文章