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.

脚本原生 tdoc 字面量

Native tdoc Literals

tdoc 是 .as 脚本中的原生表达式前缀，用来直接构造 TDoc 值。它与 TDoc.parse/TDoc.stringify 不同：前者在编译后的脚本表达式中产生运行时值，后两者负责字符串和运行时值之间的转换。

tdoc is the native expression prefix in an .as script for constructing a TDoc value directly. Unlike TDoc.parse and TDoc.stringify, it produces a runtime value in compiled script code; those methods convert between text and runtime values.

tdoc [type-name] value

语法

Syntax

func createProfile(user) {
    return tdoc Object {
        readonly String id $(user.id),
        name "Aurora",
        tags [String "system", Number 4],
    };
}

语法规则

Syntax Rules

• tdoc 必须是小写；根值可以省略类型名，也可以写一个显式类型名。

  tdoc is lowercase; the root may omit its type name or specify an explicit type name.

• 对象成员使用 readonly、可选类型名、属性名和值的空格分隔形式，例如 readonly String id "u-1"；不支持 id: "u-1"。

  Object members use space-separated readonly, optional type name, property name, and value, such as readonly String id "u-1"; id: "u-1" is not supported.

• 值可以是 null、Boolean、Number、引号字符串、数组、对象或受支持的显式类型。

  A value may be null, Boolean, Number, a quoted string, an array, an object, or a supported explicit type.

• 脚本原生字面量的显式类型限于编译器支持的内置 TDoc 类型；注册的 CLR/CIL 实例应通过 $() 注入，不能写成 tdoc User { ... }。

  Explicit types in native script literals are limited to built-in TDoc types supported by the compiler; registered CLR/CIL instances should be supplied through $(), not written as tdoc User { ... }.

• $() 只允许出现在值位置，括号中使用普通 AuroraScript 表达式；属性名和类型名不能动态计算。

  $() is allowed only in value positions and contains an ordinary AuroraScript expression; property names and type names cannot be computed dynamically.

• 该表达式返回普通 AuroraScript 值；它不会自动生成 TDoc 文本。要生成文本，请调用 TDoc.stringify。

  The expression returns a normal AuroraScript value; it does not generate TDoc text automatically. Call TDoc.stringify when text is required.

简单示例

Simple Example

func makeSettings(user) {
    var settings = tdoc Object {
        readonly String id $(user.id),
        enabled $(user.enabled),
        values [1, $(user.defaultValue), 3],
    };
    return TDoc.stringify(settings, false);
}

不支持的写法

Unsupported Forms

tdoc Object { $(key) "value" }      // dynamic property name: invalid
tdoc $(typeName) { enabled true }    // dynamic type name: invalid

独立 .tdoc 文件和 TDoc.parse(text) 不写 tdoc 前缀，也不允许 $()；它们从根值直接开始。脚本原生字面量和独立文档共享 TDoc 的类型、readonly 和尾逗号规则，但解析入口不同。

Standalone .tdoc files and TDoc.parse(text) omit the tdoc prefix and do not allow $(); they start directly with the root value. Native script literals and standalone documents share TDoc types, readonly, and trailing-comma rules, but use different parsing entry points.

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