API TDoc

TDoc

Typed Document script API

适用版本：4.0.0。全局 TDoc 为只读、不可枚举对象。

Applies to 4.0.0. The global TDoc is a read-only, non-enumerable object.

脚本 API 目录 · TDoc 格式

Script API Directory · TDoc Format

介绍

Introduction

TDoc 在 AuroraScript 内部解析和生成 TDoc 文本。它保留 TDoc 支持的类型身份，而 JSON 面向通用 JSON 互操作，可能将这些类型降级为普通对象、数组或字符串。

TDoc parses and produces TDoc text inside AuroraScript. It preserves the identities supported by TDoc, whereas JSON targets general JSON interoperability and can reduce those types to ordinary objects, arrays, or strings.

TDoc 只处理字符串和脚本值；文件和 Stream 读写由 .NET 宿主 API 提供。

TDoc only processes strings and script values; file and Stream I/O are provided by the .NET host API.

快速开始

Quick Start

var document = 'Object { String name "Aurora", Int8Array scores [1, 2, 3] }';
var value = TDoc.parse(document);

var compact = TDoc.stringify(value, false);
return compact;

compact 的值为 {name "Aurora",Int8Array scores [1,2,3,],}：可推断的 Object 和 String 类型被省略，而 Int8Array 始终保留。

compact is {name "Aurora",Int8Array scores [1,2,3,],}: inferable Object and String types are omitted, while Int8Array always remains explicit.

API

API

TDoc.parse(text)

将一个独立 TDoc 文本解析为 AuroraScript 值。根值可以是 null、Boolean、Number、String、Array、Object 或任意受支持的显式类型。

Parses standalone TDoc text into an AuroraScript value. The root may be null, Boolean, Number, String, Array, Object, or any supported explicit type.

Parameters:

• text
  要解析的完整 TDoc 文本。文档从根值开始，不要加脚本 tdoc 标记。

  Complete TDoc text to parse. The document starts with its root value; do not add the script tdoc marker.

Returns

对应的 AuroraScript 值；例如 Int8Array 返回 Packed Array，Date 返回 Date，注册的 User 返回对应的 CLR/CIL 实例包装值。

The corresponding AuroraScript value; for example, an Int8Array returns a packed array, a Date returns a Date, and a registered User returns its CLR/CIL instance wrapper.

边界行为

Boundary Behavior

• 文本只能含有一个根值；尾随内容、未知类型、类型形状错误和重复属性会失败。

  Text may contain only one root value; trailing content, unknown types, invalid type shapes, and duplicate properties fail.

• 日期字符串必须匹配宿主配置的日期格式；未注册的 CLR/CIL 类型不会自动反射或加载。

  Date strings must match the host-configured date format; unregistered CLR/CIL types are never reflected or loaded automatically.

• 解析失败时抛出 AuroraRuntimeException，消息以 TDoc.parse error: 开头。

  Parse failures throw AuroraRuntimeException with a message starting with TDoc.parse error:.

简单示例

Simple Example

var config = TDoc.parse('Object { readonly String id "u-1", enabled true }');
return [config.id, config.enabled];

TDoc.stringify(value, [indented], [emitTypes])

将一个 AuroraScript 值写成 TDoc 文本。默认输出规范化、缩进，并只输出无法由字面量推断的类型名。

Writes an AuroraScript value as TDoc text. By default it produces normalized, indented text and emits only type names that cannot be inferred from literals.

Parameters:

• value
  待序列化的 AuroraScript 值。

  AuroraScript value to serialize.

• indented
  可选 Boolean。默认为 true；为 false 时输出紧凑文本。

  Optional Boolean. Defaults to true; false produces compact text.

• emitTypes
  可选 Boolean。默认为 false；默认省略可由字面量唯一推断的 Object、Array、String、Number 和 Boolean 类型名。设为 true 时强制输出所有可用类型名。

  Optional Boolean. Defaults to false; by default it omits Object, Array, String, Number, and Boolean type names when their literals uniquely infer them. Set it to true to force every available type name.

Returns

TDoc 字符串。

TDoc string.

边界行为

Boundary Behavior

• Date、Regex、Path、HashMap、StringBuffer、全部 Packed Array 与已注册 CLR/CIL 类型即使默认 emitTypes = false 也保留类型名。

  Date, Regex, Path, HashMap, StringBuffer, every packed array, and registered CLR/CIL types retain a type name even with the default emitTypes = false.

• indented 只控制 TDoc 容器的格式空白；如果 value 本身是含有换行的 String，换行会保留为 \r、\n 或 \f 转义，不能借此压缩字符串内容。

  indented controls only TDoc container whitespace; if value itself is a String containing line breaks, they remain as \r, \n, or \f escapes and cannot be compacted this way.

• 函数、代理、访问器属性、未注册 CLR/CIL 对象、非有限 Number，以及已见过的循环/共享引用会自动跳过：对象属性省略，数组元素写为 null，根值写为 null。普通 ScriptObject 的可枚举 prototype 属性会作为可见属性扁平写入；prototype 身份不会保留。

  Functions, proxies, accessor properties, unregistered CLR/CIL objects, non-finite Numbers, and previously seen circular/shared references are skipped automatically: object properties are omitted, array elements become null, and a root value becomes null. Enumerable prototype properties of an ordinary ScriptObject are flattened as visible properties; prototype identity is not preserved.

• TDoc.stringify error: 只表示无法安全继续的宿主配置或运行时错误，例如无效的日期格式；不可表示的值本身不会触发该错误。

  TDoc.stringify error: indicates a host configuration or runtime failure that cannot safely continue, such as an invalid date format; an unrepresentable value by itself does not trigger it.

简单示例：默认可读输出

Simple Example: Default Readable Output

var text = TDoc.stringify({ name: "Aurora", enabled: true });
return text.contains("\n"); // true

简单示例：紧凑默认输出

Simple Example: Compact Default Output

var bytes = new Int8Array(2);
bytes[0] = 1;
bytes[1] = 2;

var text = TDoc.stringify({ name: "Aurora", bytes: bytes }, false);
return text; // {name "Aurora",Int8Array bytes [1,2,],}

简单示例：强制输出所有类型

Simple Example: Force All Type Names

var text = TDoc.stringify({ name: "Aurora", enabled: true }, false, true);
return text; // Object {String name "Aurora",Boolean enabled true,}

与 JSON 的选择

Choosing Between TDoc and JSON

需求	推荐
对外部服务、浏览器或标准 JSON 工具互操作	JSON
保留 Date、Packed Array、Path、HashMap 或注册 CLR/CIL 类型	TDoc
从脚本读写文件或流	宿主的 AuroraTypedDocument

Use JSON for standard interoperability, TDoc when AuroraScript type identity must survive, and host AuroraTypedDocument for file or stream I/O.

相关 API

Related APIs

• TDoc 格式说明

  TDoc format guide

• JSON

  JSON

• AuroraTypedDocument

  AuroraTypedDocument