API TDoc

TDoc

Typed Document parsing and serialization API for AuroraScript values.

Script API Reference · TDoc Format

Overview

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

TDoc is a static object with no constructor. The global is read-only and non-enumerable, and applies to version 4.0.0.

TDoc works with strings and script values only. 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; // {name "Aurora",Int8Array scores [1,2,3,],}

The inferable Object and String type names are omitted from the output, while Int8Array always remains explicit.

Native tdoc Literals

tdoc is a native expression prefix in an .as script for constructing a TDoc value directly. It differs from TDoc.parse and TDoc.stringify: the literal produces a runtime value in compiled script code, while the methods convert between text and runtime values.

Standalone .tdoc documents omit the tdoc prefix and start directly with the root value.

Syntax

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

Syntax Rules

• tdoc is lowercase. The root value may omit its type name or state one explicitly.
• Object members are space-separated: optional readonly, optional type name, property name, then value, as in readonly String id "u-1". The id: "u-1" form is not supported.
• A value may be null, a Boolean, a Number, a quoted string, an array, an object, or a supported explicit type.
• Explicit types in a native script literal are limited to the built-in TDoc types the compiler supports. Registered CLR/CIL instances must be supplied through $() and cannot be written as tdoc User { ... }.
• $() is allowed only in value positions and contains an ordinary AuroraScript expression. Property names and type names cannot be computed dynamically.
• The expression returns a normal AuroraScript value; it does not generate TDoc text. Call TDoc.stringify when text is required.

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

Note

TDoc.parse(text) and standalone .tdoc files do not accept the tdoc prefix or $(). Native script literals and standalone documents share the TDoc type, readonly, and trailing-comma rules, but use different parsing entry points.

Methods

TDoc.parse(text)

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

Parameters

Name	Type	Required	Description
text	string	Yes	Complete TDoc text. The document starts with its root value; do not add the script tdoc marker.

Returns

any — the corresponding AuroraScript value. For example, an Int8Array becomes a packed array, a Date becomes a Date, and a registered User becomes its CLR/CIL instance wrapper.

Behavior

• The text may contain only one root value. Trailing content, unknown types, invalid type shapes, and duplicate properties all fail.
• Date strings must match the host-configured date format.
• Unregistered CLR/CIL types are never reflected or loaded automatically.

Warning

A parse failure throws AuroraRuntimeException with a message beginning TDoc.parse error:.

Example

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

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

Writes an AuroraScript value as TDoc text. By default the output is normalized and indented, and only type names that cannot be inferred from the literal are emitted.

Parameters

Name	Type	Required	Description
value	any	Yes	Value to serialize.
indented	boolean	No	Defaults to true. Set it to false for compact text.
emitTypes	boolean	No	Defaults to false, which omits the Object, Array, String, Number, and Boolean type names that their literals uniquely infer. Set it to true to force every available type name.

Returns

string — the TDoc text.

Behavior

• Date, Regex, Path, HashMap, StringBuffer, every packed array, and registered CLR/CIL types keep their type name even with the default emitTypes = false.
• indented controls TDoc container whitespace only. Line breaks inside a String value remain as \r, \n, or \f escapes and cannot be compacted this way.
• Functions, proxies, accessor properties, unregistered CLR/CIL objects, non-finite Numbers, and already-seen circular or shared references are skipped: object properties are omitted, array elements become null, and a root value becomes null.
• Enumerable prototype properties of an ordinary ScriptObject are flattened into visible properties. Prototype identity is not preserved.

Note

TDoc.stringify error: reports a host configuration or runtime failure that cannot safely continue, such as an invalid date format. An unrepresentable value on its own does not trigger it.

Example

Default readable output:

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

Compact 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,],}

Every type name forced:

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

Choosing Between TDoc and JSON

Requirement	Use
Interoperate with external services, browsers, or standard JSON tooling	JSON
Preserve Date, packed arrays, Path, HashMap, or registered CLR/CIL types	TDoc
Read or write files and streams	Host AuroraTypedDocument

Related APIs

• TDoc format guide
• JSON
• AuroraTypedDocument