.. _stdlib_json:

=========================
JSON 操作库
=========================

.. include:: detail/json.rst

JSON 模块实现 JSON 解析器和序列化例程。
有关详细信息，请参阅`JHSON <www.json.org>`。

所有函数和符号都在 “json” 模块中，使用 require 来访问它。 ::

    require daslib/json


++++++++++++
类型别名
++++++++++++

.. _alias-JsValue:

.. das:attribute:: JsValue is a variant type

+-------+------------------------+
+_object+table<string;JsonValue?>+
+-------+------------------------+
+_array +array<JsonValue?>       +
+-------+------------------------+
+_string+string                  +
+-------+------------------------+
+_number+double                  +
+-------+------------------------+
+_bool  +bool                    +
+-------+------------------------+
+_null  +void?                   +
+-------+------------------------+


单个 JSON 元素。

.. _alias-Token:

.. das:attribute:: Token is a variant type

+-------+------+
+_string+string+
+-------+------+
+_number+double+
+-------+------+
+_bool  +bool  +
+-------+------+
+_null  +void? +
+-------+------+
+_symbol+int   +
+-------+------+
+_error +string+
+-------+------+


JSON 输入流token。

.. _struct-json-JsonValue:

.. das:attribute:: JsonValue



JsonValue字段是

+-----+--------------------------------+
+value+ :ref:`JsValue <alias-JsValue>` +
+-----+--------------------------------+


JSON 值，包装任何 JSON 元素。

.. _struct-json-TokenAt:

.. das:attribute:: TokenAt



TokenAt字段是

+-----+----------------------------+
+value+ :ref:`Token <alias-Token>` +
+-----+----------------------------+
+line +int                         +
+-----+----------------------------+
+row  +int                         +
+-----+----------------------------+


JSON 解析令牌。包含 token 及其位置。

++++++++++++++++
值转换
++++++++++++++++

  *  :ref:`JV (v:string const) : json::JsonValue? <function-_at_json_c__c_JV_Cs>` 
  *  :ref:`JV (v:double const) : json::JsonValue? <function-_at_json_c__c_JV_Cd>` 
  *  :ref:`JV (v:bool const) : json::JsonValue? <function-_at_json_c__c_JV_Cb>` 
  *  :ref:`JVNull () : json::JsonValue? <function-_at_json_c__c_JVNull>` 
  *  :ref:`JV (v:table\<string;json::JsonValue?\> -const) : json::JsonValue? <function-_at_json_c__c_JV_1_ls_s_gr_2_ls_1_ls_S_ls_json_c__c_JsonValue_gr__gr__qm__gr_T>` 
  *  :ref:`JV (v:array\<json::JsonValue?\> -const) : json::JsonValue? <function-_at_json_c__c_JV_1_ls_1_ls_S_ls_json_c__c_JsonValue_gr__gr__qm__gr_A>` 

.. _function-_at_json_c__c_JV_Cs:

.. das:function:: JV(v: string const)

JV returns  :ref:`json::JsonValue <struct-json-JsonValue>` ?

+--------+-------------+
+argument+argument type+
+========+=============+
+v       +string const +
+--------+-------------+


从 value 中创建 `JsonValue`。

.. _function-_at_json_c__c_JV_Cd:

.. das:function:: JV(v: double const)

JV returns  :ref:`json::JsonValue <struct-json-JsonValue>` ?

+--------+-------------+
+argument+argument type+
+========+=============+
+v       +double const +
+--------+-------------+


从 value 中创建 `JsonValue`。

.. _function-_at_json_c__c_JV_Cb:

.. das:function:: JV(v: bool const)

JV returns  :ref:`json::JsonValue <struct-json-JsonValue>` ?

+--------+-------------+
+argument+argument type+
+========+=============+
+v       +bool const   +
+--------+-------------+


从 value 中创建 `JsonValue`。

.. _function-_at_json_c__c_JVNull:

.. das:function:: JVNull()

JVNull returns  :ref:`json::JsonValue <struct-json-JsonValue>` ?

创建表示 `null` 的 `JsonValue`。

.. _function-_at_json_c__c_JV_1_ls_s_gr_2_ls_1_ls_S_ls_json_c__c_JsonValue_gr__gr__qm__gr_T:

.. das:function:: JV(v: table<string;JsonValue?>)

JV returns  :ref:`json::JsonValue <struct-json-JsonValue>` ?

+--------+---------------------------------------------------------------+
+argument+argument type                                                  +
+========+===============================================================+
+v       +table<string; :ref:`json::JsonValue <struct-json-JsonValue>` ?>+
+--------+---------------------------------------------------------------+


从 value 中创建 `JsonValue`。

.. _function-_at_json_c__c_JV_1_ls_1_ls_S_ls_json_c__c_JsonValue_gr__gr__qm__gr_A:

.. das:function:: JV(v: array<JsonValue?>)

JV returns  :ref:`json::JsonValue <struct-json-JsonValue>` ?

+--------+--------------------------------------------------------+
+argument+argument type                                           +
+========+========================================================+
+v       +array< :ref:`json::JsonValue <struct-json-JsonValue>` ?>+
+--------+--------------------------------------------------------+


从 value 中创建 `JsonValue`。

++++++++++++++
读取和写入
++++++++++++++

  *  :ref:`read_json (text:string const implicit;error:string& -const) : json::JsonValue? <function-_at_json_c__c_read_json_CIs_&s>` 
  *  :ref:`read_json (text:array\<uint8\> const;error:string& -const) : json::JsonValue? <function-_at_json_c__c_read_json_C1_ls_u8_gr_A_&s>` 
  *  :ref:`write_json (val:json::JsonValue? const) : string <function-_at_json_c__c_write_json_C1_ls_S_ls_json_c__c_JsonValue_gr__gr__qm_>` 
  *  :ref:`write_json (val:json::JsonValue? const#) : string <function-_at_json_c__c_write_json_C_hh_1_ls_S_ls_json_c__c_JsonValue_gr__gr__qm_>` 

.. _function-_at_json_c__c_read_json_CIs_&s:

.. das:function:: read_json(text: string const implicit; error: string&)

read_json returns  :ref:`json::JsonValue <struct-json-JsonValue>` ?

+--------+---------------------+
+argument+argument type        +
+========+=====================+
+text    +string const implicit+
+--------+---------------------+
+error   +string&              +
+--------+---------------------+


从 `text` 字符串中读取 JSON。
如果 `error` 不为空，则包含解析错误消息。

.. _function-_at_json_c__c_read_json_C1_ls_u8_gr_A_&s:

.. das:function:: read_json(text: array<uint8> const; error: string&)

read_json returns  :ref:`json::JsonValue <struct-json-JsonValue>` ?

+--------+------------------+
+argument+argument type     +
+========+==================+
+text    +array<uint8> const+
+--------+------------------+
+error   +string&           +
+--------+------------------+


从 `text` 字符串中读取 JSON。
如果 `error` 不为空，则包含解析错误消息。

.. _function-_at_json_c__c_write_json_C1_ls_S_ls_json_c__c_JsonValue_gr__gr__qm_:

.. das:function:: write_json(val: JsonValue? const)

write_json returns string

+--------+-------------------------------------------------------+
+argument+argument type                                          +
+========+=======================================================+
+val     + :ref:`json::JsonValue <struct-json-JsonValue>` ? const+
+--------+-------------------------------------------------------+


接受临时类型的重载
很好，因为 json 不会转义函数

.. _function-_at_json_c__c_write_json_C_hh_1_ls_S_ls_json_c__c_JsonValue_gr__gr__qm_:

.. das:function:: write_json(val: JsonValue? const#)

write_json returns string

+--------+--------------------------------------------------------+
+argument+argument type                                           +
+========+========================================================+
+val     + :ref:`json::JsonValue <struct-json-JsonValue>` ? const#+
+--------+--------------------------------------------------------+


接受临时类型的重载
很好，因为 json 不会转义函数

+++++++++++++++
JSON 属性
+++++++++++++++

  *  :ref:`set_no_trailing_zeros (value:bool const) : bool const <function-_at_json_c__c_set_no_trailing_zeros_Cb>` 
  *  :ref:`set_no_empty_arrays (value:bool const) : bool const <function-_at_json_c__c_set_no_empty_arrays_Cb>` 
  *  :ref:`set_allow_duplicate_keys (value:bool const) : bool const <function-_at_json_c__c_set_allow_duplicate_keys_Cb>` 

.. _function-_at_json_c__c_set_no_trailing_zeros_Cb:

.. das:function:: set_no_trailing_zeros(value: bool const)

set_no_trailing_zeros returns bool const

+--------+-------------+
+argument+argument type+
+========+=============+
+value   +bool const   +
+--------+-------------+


如果 `value` 为 true，则写入数字时不带尾随零。

.. _function-_at_json_c__c_set_no_empty_arrays_Cb:

.. das:function:: set_no_empty_arrays(value: bool const)

set_no_empty_arrays returns bool const

+--------+-------------+
+argument+argument type+
+========+=============+
+value   +bool const   +
+--------+-------------+


如果`value` 为 true，则根本不写入空数组

.. _function-_at_json_c__c_set_allow_duplicate_keys_Cb:

.. das:function:: set_allow_duplicate_keys(value: bool const)

set_allow_duplicate_keys returns bool const

+--------+-------------+
+argument+argument type+
+========+=============+
+value   +bool const   +
+--------+-------------+


如果 `value` 为 true，则对象中允许重复键。后面的键会覆盖前面的键。
注意 - 出于性能原因，我们在此处使用 StringBuilderWriter

+++++++++++
损坏的 JSON
+++++++++++

  *  :ref:`try_fixing_broken_json (bad:string -const) : string <function-_at_json_c__c_try_fixing_broken_json_s>` 

.. _function-_at_json_c__c_try_fixing_broken_json_s:

.. das:function:: try_fixing_broken_json(bad: string)

try_fixing_broken_json returns string

+--------+-------------+
+argument+argument type+
+========+=============+
+bad     +string       +
+--------+-------------+


修复了已损坏的 json，到目前为止支持
1. "string" + "string" 字符串连接
2. "text "嵌套文本 "text "嵌套引号
3. 在对象或数组末尾添加额外的
4. /uXXXXXX 序列在空白区域中间
写入直到字符串开头或结束
如果 eof 我们完成
写入第一个引号
写入直到字符串结束或文件结束
如果 eof 我们完成，我们固定结束引号并完成
跳过空白区域
如果 eof 我们完成，我们固定结束引号并完成
字符串后面有效的 JSON 事物是 ： , }, ], 或 , 如果是其中之一，我们关闭字符串，完成
现在，如果是 + -，它可能是一个字符串连接
如果确实是新字符串，我们回到字符串编写，并添加分隔符
OK，它不是字符串连接，也不是有效字符
如果引号后是空白，我们假定它缺少 ','
 。我们假定它是嵌套引号，并用\" 替换
如果是这样，我们就完成了，我们修复了嵌套引号和结束引号，我们就完成了
写入第二个被替换的引号