API Host TypedDocumentSerializer

TypedDocumentSerializer

Static TDoc text serializer

命名空间：AuroraScript.Runtime.Serialization。类型：static class。适用版本：4.0.0。

Namespace: AuroraScript.Runtime.Serialization. Kind: static class. Applies to 4.0.0.

.NET Host API 目录 · TDoc 格式

.NET Host API Directory · TDoc Format

介绍

Introduction

TypedDocumentSerializer 是最小的宿主字符串 API：给定 AuroraEngine、ScriptDatum 或文本后，直接进行 TDoc 序列化或反序列化。

TypedDocumentSerializer is the minimal host text API: given an AuroraEngine, a ScriptDatum, or text, it directly serializes or deserializes TDoc.

它适合一次性文本转换。需要复用引擎、读写文件或流时，使用 AuroraTypedDocument。

It suits one-off text conversion. Use AuroraTypedDocument when reusing an engine or reading and writing files or streams.

快速开始

Quick Start

using AuroraScript;
using AuroraScript.Runtime;
using AuroraScript.Runtime.Serialization;
using System;

var engine = new AuroraEngine(EngineOptions.Default);
var text = TypedDocumentSerializer.Serialize(engine, ScriptDatum.FromString("Aurora"));
var value = TypedDocumentSerializer.Deserialize(engine, text);

Console.WriteLine(value); // Aurora

API

API

static string Serialize(AuroraEngine engine, ScriptDatum value, TypedDocumentOptions options = null)

将一个 AuroraScript 值写为独立 TDoc 文本。

Writes one AuroraScript value as standalone TDoc text.

Parameters:

• engine
  用于日期格式和 CLR/CIL 类型注册表的 AuroraScript 引擎。不能为 null。

  AuroraScript engine used for date formatting and the CLR/CIL type registry. Cannot be null.

• value
  待序列化的 AuroraScript 值。

  AuroraScript value to serialize.

• options
  可选文本选项；为 null 时使用 TypedDocumentOptions.Default。

  Optional text options; TypedDocumentOptions.Default is used when null.

Returns

TDoc 文本。

TDoc text.

边界行为

Boundary Behavior

• 文本不含 @data 标记；默认使用四空格缩进、尾逗号，并仅输出无法由字面量推断的类型名。

  Text contains no @data marker; the default uses four-space indentation, trailing commas, and only type names that cannot be inferred from literals.

• 写入运行时不可表示值时不会因为该值失败：对象属性会省略；数组元素以及 HashMap 条目中的不可表示键或值会写为 null；根值会写为 null。这包括函数、代理、访问器属性、未注册 CLR/CIL 对象、非有限 Number，以及已见过的循环/共享引用。

  Writing an unrepresentable runtime value does not fail because of that value: object properties are omitted; array elements and unrepresentable keys or values in a HashMap entry become null; and a root value becomes null. This includes functions, proxies, accessor properties, unregistered CLR/CIL objects, non-finite Numbers, and previously seen circular/shared references.

• ScriptObject 的可枚举 prototype 属性会写为扁平的可见成员；读取后不会还原原型链。

  Enumerable prototype properties of a ScriptObject are written as flat visible members; reading does not restore the prototype chain.

简单示例

Simple Example

var text = TypedDocumentSerializer.Serialize(
    engine,
    ScriptDatum.FromNumber(42.5),
    new TypedDocumentOptions { Indented = false });

Console.WriteLine(text); // 42.5

static ScriptDatum Deserialize(AuroraEngine engine, string text, TypedDocumentOptions options = null)

将一个独立 TDoc 文本读为 ScriptDatum。根级原始值保持其原始种类，而不是总被包装为 ScriptObject。

Reads standalone TDoc text as ScriptDatum. Root primitive values keep their original kind instead of always being wrapped as ScriptObject.

Parameters:

• engine
  用于日期格式和 CLR/CIL 类型注册表的 AuroraScript 引擎。不能为 null。

  AuroraScript engine used for date formatting and the CLR/CIL type registry. Cannot be null.

• text
  要读取的完整 TDoc 文本。不能为 null。

  Complete TDoc text to read. Cannot be null.

• options
  可选读取与诊断选项；为 null 时使用 TypedDocumentOptions.Default。

  Optional read and diagnostic options; TypedDocumentOptions.Default is used when null.

Returns

解析得到的 ScriptDatum。

Parsed ScriptDatum.

边界行为

Boundary Behavior

• 文本只能有一个根值；未知类型、错误的类型形状、重复属性或超出深度限制时抛出 TypedDocumentException。

  Text may contain one root value only; unknown types, invalid type shapes, duplicate properties, or depth-limit violations throw TypedDocumentException.

• Date 字符串必须匹配引擎的 Runtime.DateTimeFormat；CLR/CIL 别名必须已经由当前引擎注册。

  Date strings must match the engine Runtime.DateTimeFormat; CLR/CIL aliases must already be registered on the current engine.

简单示例

Simple Example

using AuroraScript.Runtime.Types;

var value = TypedDocumentSerializer.Deserialize(
    engine,
    "Object { String name \"Aurora\", Int8Array levels [1, 2] }");

var profile = (ScriptObject)value.Object;
Console.WriteLine(profile.GetPropertyValue("name")); // Aurora

类型输出选项

Type-Emission Option

EmitTypeNames 默认是 false。默认省略原始字面量能够唯一推断的 Object、Array、String、Number 和 Boolean；Packed Array 与 CLR/CIL 类型始终保留类型名。设为 true 时强制输出所有可用类型名。

EmitTypeNames defaults to false. By default it omits Object, Array, String, Number, and Boolean when a raw literal uniquely infers them; packed arrays and CLR/CIL types always retain type names. Set it to true to force every available type name.

var compact = TypedDocumentSerializer.Serialize(
    engine,
    ScriptDatum.FromString("Aurora"),
    new TypedDocumentOptions { Indented = false, EmitTypeNames = true });

Console.WriteLine(compact); // String "Aurora"

相关 API

Related APIs

• AuroraTypedDocument

  AuroraTypedDocument

• TypedDocumentOptions

  TypedDocumentOptions

• TypedDocumentException

  TypedDocumentException