API Host AuroraTypedDocument

AuroraTypedDocument

Engine-bound TDoc host helper

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

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

.NET Host API 目录 · TDoc 格式

.NET Host API Directory · TDoc Format

介绍

Introduction

AuroraTypedDocument 是绑定到一个 AuroraEngine 的宿主帮助对象。它在 TypedDocumentSerializer 的字符串读写能力之上，补充了文件与 Stream 的读写入口。

AuroraTypedDocument is a host helper bound to one AuroraEngine. It adds file and Stream I/O on top of TypedDocumentSerializer text serialization.

绑定引擎不是可选细节：引擎提供 DateTimeFormat，并决定哪些 CLR/CIL 类型及别名能够被 TDoc 读取或写入。

Binding an engine is essential: the engine supplies DateTimeFormat and determines which CLR/CIL types and aliases TDoc may read or write.

用途与快速开始

Use Cases and Quick Start

当宿主需要持续读写同一种 TDoc 配置、快照或消息时，创建一个实例并复用它；单次字符串转换可直接使用 TypedDocumentSerializer。

Create and reuse one instance when a host repeatedly reads or writes TDoc configuration, snapshots, or messages; use TypedDocumentSerializer for a one-off text conversion.

using AuroraScript;
using AuroraScript.Runtime;
using AuroraScript.Runtime.Serialization;
using AuroraScript.Runtime.Types;

var engine = new AuroraEngine(EngineOptions.Default);
var tdoc = new AuroraTypedDocument(engine);

var root = new ScriptObject();
root.Define("name", ScriptDatum.FromString("Aurora"));

tdoc.WriteFile("settings.tdoc", ScriptDatum.FromObject(root));
var restored = tdoc.ReadFile("settings.tdoc");

默认文件和流编码为无 BOM 的 UTF-8。流默认保持打开，调用者仍拥有流的生命周期。

Files and streams default to UTF-8 without a BOM. Streams remain open by default, so the caller retains their lifecycle.

API

API

AuroraTypedDocument(AuroraEngine engine, TypedDocumentOptions options = null)

创建绑定引擎的帮助对象。

Creates an engine-bound helper.

Parameters:

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

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

• options
  可选默认 TDoc 选项。各操作传入的 options 会优先于此值。

  Optional default TDoc options. Per-operation options take precedence.

Returns

新建的 AuroraTypedDocument 实例。

A new AuroraTypedDocument instance.

简单示例

Simple Example

var tdoc = new AuroraTypedDocument(
    engine,
    new TypedDocumentOptions { Indented = false });

AuroraEngine Engine

返回构造时绑定的引擎。

Returns the engine bound at construction.

Parameters:

• 无。

  None.

Returns

AuroraEngine。

AuroraEngine.

简单示例

Simple Example

var format = tdoc.Engine.Options.Runtime.DateTimeFormat;

TypedDocumentOptions Options

返回帮助对象的默认选项。该记录不可变；如需改变配置，请创建新实例或在单次调用中传入新选项。

Returns the helper's default options. The record is immutable; create a new helper or pass new per-call options to change configuration.

Parameters:

• 无。

  None.

Returns

TypedDocumentOptions。

TypedDocumentOptions.

简单示例

Simple Example

var emitTypes = tdoc.Options.EmitTypeNames;

string Serialize(ScriptDatum value, TypedDocumentOptions options = null)

将值写为 TDoc 字符串。

Writes a value as a TDoc string.

Parameters:

• value
  待序列化的 AuroraScript 值。

  AuroraScript value to serialize.

• options
  可选单次写入选项；为 null 时使用 Options。

  Optional per-write options; Options is used when null.

Returns

TDoc 文本。

TDoc text.

简单示例

Simple Example

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

ScriptDatum Deserialize(string text, TypedDocumentOptions options = null)

将 TDoc 字符串读为 ScriptDatum。使用 ScriptDatum 使根级 Number、String、Boolean 与 null 不会被强制包装成对象。

Reads TDoc text as ScriptDatum. Using ScriptDatum preserves root Number, String, Boolean, and null values without forcing object wrapping.

Parameters:

• text
  完整 TDoc 文本。不能为 null。

  Complete TDoc text. Cannot be null.

• options
  可选单次读取选项；为 null 时使用 Options。

  Optional per-read options; Options is used when null.

Returns

读取到的 ScriptDatum。

Parsed ScriptDatum.

简单示例

Simple Example

var value = tdoc.Deserialize("Int8Array [-1, 0, 1]");
var bytes = (ScriptInt8Array)value.Object;

void WriteFile(string path, ScriptDatum value, TypedDocumentOptions options = null, Encoding encoding = null)

序列化值并覆盖写入文件。默认使用无 BOM UTF-8。

Serializes a value and overwrites a file. UTF-8 without a BOM is the default.

Parameters:

• path
  目标文件路径。父目录必须已存在。

  Target file path. Its parent directory must already exist.

• value
  待写入的 AuroraScript 值。

  AuroraScript value to write.

• options
  可选单次写入选项。

  Optional per-write options.

• encoding
  可选文本编码；为 null 时使用无 BOM UTF-8。

  Optional text encoding; UTF-8 without a BOM is used when null.

Returns

无。

None.

简单示例

Simple Example

tdoc.WriteFile("settings.tdoc", ScriptDatum.FromString("Aurora"));

ScriptDatum ReadFile(string path, TypedDocumentOptions options = null, Encoding encoding = null)

读取整个文件并解析 TDoc。读取错误会自动把文件路径作为错误来源。

Reads an entire file and parses TDoc. A read error automatically uses the file path as its source.

Parameters:

• path
  要读取的文件路径。

  File path to read.

• options
  可选单次读取选项。

  Optional per-read options.

• encoding
  可选文本编码；为 null 时使用无 BOM UTF-8。

  Optional text encoding; UTF-8 without a BOM is used when null.

Returns

读取到的 ScriptDatum。

Parsed ScriptDatum.

简单示例

Simple Example

var settings = tdoc.ReadFile("settings.tdoc");

void WriteStream(Stream stream, ScriptDatum value, TypedDocumentOptions options = null, Encoding encoding = null, bool leaveOpen = true)

序列化值并写入流。写入完成前会刷新内部 StreamWriter。

Serializes a value and writes it to a stream. The internal StreamWriter flushes before completion.

Parameters:

• stream
  可写目标流。不能为 null。

  Writable target stream. Cannot be null.

• value
  待写入的 AuroraScript 值。

  AuroraScript value to write.

• options
  可选单次写入选项。

  Optional per-write options.

• encoding
  可选文本编码；为 null 时使用无 BOM UTF-8。

  Optional text encoding; UTF-8 without a BOM is used when null.

• leaveOpen
  是否在操作后保持流打开。默认 true。

  Whether to keep the stream open after the operation. Defaults to true.

Returns

无。

None.

简单示例

Simple Example

using System.IO;

using var stream = new MemoryStream();
tdoc.WriteStream(stream, ScriptDatum.FromBoolean(true));
stream.Position = 0; // stream remains open by default

ScriptDatum ReadStream(Stream stream, TypedDocumentOptions options = null, Encoding encoding = null, bool leaveOpen = true)

从当前位置读取流的其余文本并解析 TDoc。读取支持 BOM 检测。

Reads the remaining text from the current stream position and parses TDoc. Reading supports BOM detection.

Parameters:

• stream
  可读源流。不能为 null。

  Readable source stream. Cannot be null.

• options
  可选单次读取选项。

  Optional per-read options.

• encoding
  可选默认文本编码；检测到 BOM 时会使用 BOM 指定编码。

  Optional default text encoding; a detected BOM takes precedence.

• leaveOpen
  是否在操作后保持流打开。默认 true。

  Whether to keep the stream open after the operation. Defaults to true.

Returns

读取到的 ScriptDatum。

Parsed ScriptDatum.

简单示例

Simple Example

using System;
using System.IO;
using System.Text;

using var stream = new MemoryStream(Encoding.UTF8.GetBytes("String \"Aurora\""));
var value = tdoc.ReadStream(stream);
Console.WriteLine(value); // Aurora

异常与边界

Exceptions and Boundaries

• 读取时，文本语法、类型绑定和范围问题会产生 TypedDocumentException。写入时，函数、未注册 CLR/CIL 对象和循环/共享引用等不可表示值会按 TDoc 的可跳过值规则降级，不会单独造成异常。

  While reading, text syntax, type binding, and range problems produce TypedDocumentException. While writing, unrepresentable values such as functions, unregistered CLR/CIL objects, and circular/shared references follow TDoc's skippable-value rules and do not independently cause an exception.

• 文件和流的 I/O 异常直接来自 .NET，例如 FileNotFoundException、DirectoryNotFoundException 或 NotSupportedException。

  File and stream I/O exceptions come directly from .NET, such as FileNotFoundException, DirectoryNotFoundException, or NotSupportedException.

• 本类型不负责创建目录、锁、事务或并发协调；由宿主在其 I/O 边界处理。

  This type does not create directories or handle locks, transactions, or concurrency coordination; the host handles those at its I/O boundary.

相关 API

Related APIs

• TypedDocumentSerializer

  TypedDocumentSerializer

• TypedDocumentOptions

  TypedDocumentOptions

• TDoc 脚本 API

  TDoc Script API