Misc

DataValue, the dynamic value behind JSON serialisation, and opaque.

Generated by bin/build_library_doc.py from the kernel sources. Do not edit by hand: change the generator, or the doc comments in kernel/src/, and re-run it.

DataValue

CLASS DataValue

IMPLEMENTS Cloneable, Serializable, Comparable, Equatable

The kernel's neutral, format-independent value model.

A DataValue carries a DataKind discriminant plus the storage for whichever shape it represents — the abstract value model shared by JSON, BSON, CBOR, MessagePack, and DB rows (promoted from the Json module's JsonValue so the model is a kernel citizen while wire formats stay in their modules):

• NULL_KIND — absent value
• BOOL_KIND — a boolean
• NUMBER_KIND — a number (int64 XOR uint64 XOR float64 — the full tower, so integer fidelity round-trips without the lossy-float64 gap JsonValue carried)
• STRING_KIND — a String
• ARRAY_KIND — Array[DataValue]
• OBJECT_KIND — Dictionary[String, DataValue, DefaultHasher[String]]

Recursive structure needs no Box[DataValue] — Array and Dictionary heap-indirect their elements, so the recursion through collection storage is finite.

Accessors, three flavors per kind: - isXxx() RETURNS boolean — predicate - asXxx() RETURNS (T | STATUS) — by-value; PRIMITIVE kinds only - asXxxReference() RETURNS (REFERENCE T | STATUS) — handle (no clone), lifetime bound by SELF - asStringView() RETURNS (StringView | STATUS) — bounded view, no clone, copies freely

No accessor clones. A by-value form exists only where the value IS the datum (asBool, asNumber); for a class kind the by-value form would be a deep copy on every read, which is what asString was and why it is gone. asStringReference / asStringView replace it.

Constructors, one per kind: INIT() NULL, INIT(boolean), INIT(number), INIT(String), INIT(Array[DataValue]) (owning), INIT(Dictionary[String, DataValue, DefaultHasher[String]]) (owning).

This is a value model, not a format — it has no toString/serialize of its own; a format module maps DataValue ↔ text (Json) or ↔ rows (Data). Serialization rides the Serializable/Serializer interface.

_{kernel/src/DataValue.ev:51}

Fields

• DataKind kind

Constructors

INIT()

INIT(boolean v)

INIT(number v)

INIT(REFERENCE String v)

INIT(OrderedArray[DataValue] items)

INIT(Dictionary[String, DataValue, DefaultHasher[String]] entries)

Methods

METHOD clone() RETURNS DataValue

METHOD isNull() RETURNS boolean

METHOD isBool() RETURNS boolean

METHOD isNumber() RETURNS boolean

METHOD isString() RETURNS boolean

METHOD isArray() RETURNS boolean

METHOD isObject() RETURNS boolean

METHOD asBool() RETURNS | boolean

METHOD asNumber() RETURNS | number

METHOD asStringReference() RETURNS | REFERENCE String

METHOD asStringView() RETURNS | StringView

METHOD asArrayReference() RETURNS | REFERENCE OrderedArray[DataValue]

METHOD asObjectReference() RETURNS | REFERENCE Dictionary[String, DataValue, DefaultHasher[String]]

METHOD lookupReference(REFERENCE String key) RETURNS | REFERENCE DataValue

METHOD serialize(MUTABLE REFERENCE Serializer s) RETURNS STATUS

METHOD equals(REFERENCE DataValue other) RETURNS boolean

METHOD isLessThan(REFERENCE DataValue other) RETURNS boolean

CLASS DataValueBuilder

IMPLEMENTS Serializer

_{kernel/src/DataValueBuilder.ev:15}

Constructors

INIT()

Methods

MODIFY METHOD putNull() RETURNS STATUS

MODIFY METHOD putBool(boolean v) RETURNS STATUS

MODIFY METHOD putNumber(number v) RETURNS STATUS

MODIFY METHOD putString(REFERENCE String v) RETURNS STATUS

MODIFY METHOD putKey(REFERENCE String key) RETURNS STATUS

MODIFY METHOD beginArray() RETURNS STATUS

MODIFY METHOD beginObject() RETURNS STATUS

MODIFY METHOD endArray() RETURNS STATUS

MODIFY METHOD endObject() RETURNS STATUS

METHOD result() RETURNS | DataValue

MODIFY METHOD takeResult() RETURNS | DataValue

CLASS DataValueReader

IMPLEMENTS Deserializer

The tree Deserializer backend.

A non-owning reader over a DataValue tree (the 2-layer-cake borrow pattern, like StringView over char32[]): it holds a REFERENCE DataValue and, on deserialize, re-emits that tree's content as a flat event stream into the given Serializer sink. The walk already lives on the data (DataValue.serialize), so the reader is a one-line adapter that delegates to it — its job is only to present a borrowed tree through the Deserializer interface (so a DataValue source and a JsonReader stream are interchangeable sources for the same sink).

Short-lived / locals-only, by the same reference-checker rules StringView relies on: the source DataValue's lifetime must enclose the reader's.

_{kernel/src/DataValueReader.ev:25}

Constructors

INIT(REFERENCE DataValue source)

Methods

MODIFY METHOD deserialize(MUTABLE REFERENCE Serializer sink) RETURNS STATUS

opaque

PRIMITIVE opaque

opaque — type-erased value primitive.

Boxes a typed value behind a runtime type-tag for heterogeneous storage. Two static operations are called via the receiver-side template form opaque[T]->...; two instance operations are called on a opaque value via d->....

opaque   d := opaque[Esquire]->wrap(myEsquire)
Esquire  e =  opaque[Esquire]->unwrap(d)          // moves the value out; d now empty
boolean   b =  d->loaded()                        // FALSE only after a successful unwrap
opaque   c := d->deepCopy()                       // non-destructive deep copy

opaque is not a parametric type. The [T] only appears at the call site of the two statics; the type position is always bare opaque.

Runtime: hand-written EV_opaque.hpp (the floor header carries _Opaque plus the four thunks). This .ev file is the doc-only surface: the compiler does not emit a .hpp from it.

Spec reference: ENVZN_CONSTITUTION.md "### opaque — type-erased value".

_{kernel/src/opaque.ev:32}

Methods

METHOD wrap(REFERENCE T value) RETURNS opaque

Boxes value with a runtime tag of T. Static call form opaque[T]->wrap(value). Captures the cloner used by a later deepCopy() at the moment of wrap.

METHOD unwrap(opaque d) RETURNS T

Recovers a typed value from d. Static call form opaque[T]->unwrap(d). Returns the moved-out value when T matches d's runtime tag; returns a default-constructed T on tag mismatch or on an already-unloaded d. Destructive on success — d is empty afterward.

2.0 note: opaque.unwrap is the documented exception to the pipe-XOR fallible-return convention. Publisher and subscriber are expected to agree on T at the contract boundary; the default-T return on mismatch is a degenerate-case fallback, not a status-distinguishable error.

METHOD loaded() RETURNS boolean

TRUE while this opaque still holds a payload; FALSE only after a successful unwrap consumed it.

METHOD deepCopy() RETURNS opaque

Non-destructive deep copy. Source and copy are both loaded after; copying an unloaded opaque returns a fresh unloaded one. Named deepCopy (not clone) because opaque is move-only and deliberately does not satisfy the Cloneable interface.

Serialisation

INTERFACE Deserializer

Deserializer — a read source. deserialize reads its source (a JSON stream, a DataValue tree, …) and re-emits the content as a flat event stream into a Serializer sink, recursing INTERNALLY through nested containers. This is the shape Envzn's memory floor admits: the sink is a MUTABLE REFERENCE interface param (its MODIFY methods mutate the underlying object, so no stored mutable borrow — E1115 — and no SELF-as-argument — E1085); a streaming reader owns its cursor and threads it down its own recursion, a tree reader recurses over its (immutable) child nodes. There is no separate visitor abstraction — a reconstruct event stream IS a serialize event stream, so Serializer is the one universal sink. The sink backend decides what the events become: a DataValueBuilder builds a tree, a JsonWriter transcodes to text.

_{kernel/src/interfaces.ev:667}

Methods

MODIFY METHOD deserialize(MUTABLE REFERENCE Serializer sink) RETURNS STATUS

INTERFACE Serializable

Serializable — the type-side contract. serialize pushes the type's shape into the serializer (read-only on SELF; the MUTABLE REFERENCE param lets the sink's MODIFY methods be called). The compiler synthesizes the body per type (derive-by-use); kernel types implement it by hand.

_{kernel/src/interfaces.ev:651}

Methods

METHOD serialize(MUTABLE REFERENCE Serializer s) RETURNS STATUS

INTERFACE Serializer

The serialization surface (serde-style, format-neutral) — three interfaces that let the compiler synthesize a type's codec (derive-by-use) against a format-agnostic value model. A format module supplies the backends: the Json module gives a JsonWriter (Serializer) + JsonReader (Deserializer) over text; the kernel gives DataValueBuilder/DataValueReader over the DataValue tree. See Constitution I.P (Serialization and Reconstruction).

(Supersedes the earlier unused binary Serializable {encode()} / JSON_Serializer {toJson()} stubs — no code implemented either.) Serializer — a write sink. A serializable type describes its shape by pushing a flat event stream into the serializer; the backend decides whether that becomes bytes (streaming) or a DataValue tree. All methods mutate the sink.

_{kernel/src/interfaces.ev:635}

Methods

MODIFY METHOD putNull() RETURNS STATUS

MODIFY METHOD putBool(boolean v) RETURNS STATUS

MODIFY METHOD putNumber(number v) RETURNS STATUS

MODIFY METHOD putString(REFERENCE String v) RETURNS STATUS

MODIFY METHOD beginObject() RETURNS STATUS

MODIFY METHOD putKey(REFERENCE String key) RETURNS STATUS

MODIFY METHOD endObject() RETURNS STATUS

MODIFY METHOD beginArray() RETURNS STATUS

MODIFY METHOD endArray() RETURNS STATUS

ENUM DataKind

DataKind — the discriminant of DataValue, the kernel's neutral, format-independent value model (the abstract shape shared by JSON, BSON, CBOR, MessagePack, and DB rows). A DataValue carries one of these kinds plus the storage for that shape. Promoted from the Json module's Kind so the value model is a kernel citizen while wire formats stay in their modules (Json maps DataValue ↔ text).

_{kernel/src/enums.ev:258}