lower_enums

Julia

Exported as lower_enums and lower_enums!. Both names refer to the same operation.

lower_enums

lower_enums(file::EsmFile)

lower_enums(file::EsmFile) -> EsmFile

The PURE form: return a DEEP COPY of file with every enum op replaced by the const integer the file’s enums block assigns it, leaving file untouched. This is the canonical spelling across the bindings (API_SPEC.md §8 item 15); lower_enums! is the in-place twin under Julia’s ! convention (§2.2), and is what the load path calls.

Validation (esm-spec §9.3) — every rejection is an EnumLoweringError :

• an enum op whose args are not exactly two strings → enum_op_malformed;
• an enum op naming an undeclared enum → unknown_enum;
• an enum op naming a symbol not declared under that enum → unknown_enum_symbol.

A file with no enums block therefore raises unknown_enum on the first enum op it contains.

Source

lower_enums!

lower_enums!(file::EsmFile)

lower_enums!(file::EsmFile)

Walk every expression tree in file and replace each enum op with a const integer per the file’s enums block. After this pass runs, no enum-op nodes remain in the in-memory representation.

The in-place twin of lower_enums , which documents the validation rules and the EnumLoweringError codes both raise.

Mutates file in place; returns the file for convenience.

Source

TypeScript

function lowerEnums(file: EsmFile): EsmFile

Resolve every enum op in file against file.enums. Returns the (possibly identical) input — the rewrite is structural, immutable: unchanged subtrees are shared with the input.

Source

Python

lower_enums(file: EsmFile) -> EsmFile

Return file with every enum op replaced by a const integer per the file’s enums block (esm-spec §9.3).

Pure: file is not modified. The canonical name carries the pure form in every binding (API_SPEC.md §8 item 15); the in-place twin is lower_enums_mut (Julia spells it lower_enums!). Node identity is preserved wherever nothing lowered, so a document with no enum ops comes back as the very same object.

After this pass runs, no enum-op nodes remain in the returned document.

Validation (esm-spec §9.3):

• An enum op naming an undeclared enum raises EnumLoweringError with code == "unknown_enum".
• An enum op naming a symbol not declared under that enum raises EnumLoweringError with code == "unknown_enum_symbol".

EnumLoweringError subclasses ValueError, so existing except ValueError callers continue to catch these.

Source

Rust

pub fn lower_enums(file: &EsmFile) -> Result<EsmFile, EnumLoweringError>

Lower every enum-op node in file to a {op: "const", value: <int>} node using the document’s top-level enums block, returning a NEW document. file is left untouched.

The canonical entry point (API_SPEC.md §8 items 14 and 15): TYPED, because every other binding takes a typed document, and PURE, because TypeScript and Python are pure and the mutating variants take a _mut suffix (Julia’s !). The in-place raw-JSON pass the loader itself runs is lower_enums_raw .

Pre-condition: the input has been schema-validated and any apply_expression_template ops have already been expanded.

Errors with an EnumLoweringError carrying one of the diagnostic codes listed on lower_enums_raw .

Source · Rust docs

Go

func LowerEnums(file *ESMFile) (*ESMFile, error)

LowerEnums resolves every enum op in the file to a {op: "const", value: <int>} node per esm-spec §9.3, and returns the lowered document. The argument is NOT modified.

Canonical lower_enums (API_SPEC.md §8 item 15): the canonical name is the PURE form in every binding, and the mutating twin takes a suffix (Mut here, ! in Julia).

Returns an *EnumLoweringError if any enum op names an undeclared enum or an undeclared symbol; the returned document is nil in that case, so a caller cannot mistake a partially-lowered value for a lowered one — which is the concrete reason the pure form is canonical. LowerEnumsMut, having written into the caller’s document as it went, cannot make that promise.

Source · Go docs