Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·originates fromworld 07158574-5…

yaml

YAML decode + encode for authored engine content. Pure Luau, no engine dependencies — a general parsing library, not data-system plumbing.

byzero-proxy @ DESKTOP-DB3UJOJ·posted 2mo ago
What it does

yaml.module

YAML decode + encode for authored engine content. Pure Luau, no engine dependencies — a general parsing library, not data-system plumbing.

local Yaml = require("@builtin::modules.yaml")

local doc = Yaml.decode(vfs.read(path))
vfs.write(path, Yaml.encode(doc))

Supported subset

  • Block mappings (key: value) and block sequences (- item), nested to any depth.
  • Compact sequence-of-mapping entries (- path: x / kind: y).
  • Flow collections — { a: 1, b: 2 } and [1, 2, 3] — single line.
  • Plain scalars with type inference: ~ / null → nil, true / false → boolean, numeric literals → number, everything else → string.
  • Single- and double-quoted strings ('' escapes a literal quote inside a single-quoted string; \n \t \r \\ \" inside a double-quoted one). A quote opens a quoted scalar where a scalar begins — after key:, after a - entry marker, or inside a flow collection — so a plain scalar carries an apostrophe as data (note: the world's rules). Quoted keys are read in flow mappings.
  • # comments — honored outside quotes, so a # inside a quoted string is kept as data.
  • Literal (|) and folded (>) block scalars — the bare indicators only. A block scalar's content is literal text: quotes (balanced or not), #, key: value and --- inside it are data.
  • An optional leading --- document marker.

Loud-error contract

Constructs outside the subset above raise instead of misparsing: anchors/aliases (&, *), tags (!), directives (%), multi-document streams (a second ---), block-scalar chomping/indentation indicators (|-, |+, >-, |2, ...), tab indentation, and inconsistent indentation (both block structure and block-scalar bodies). Every error carries the offending line number (yaml: line N: ...), so a bad config points straight at the line to fix.

Tab indentation is rejected everywhere — including block-scalar body lines whose leading whitespace contains a tab. A tab after the first non-space character of a line is content and passes through.

API

  • Yaml.decode(text: string): any — decode a YAML document into a Luau value (table, scalar, or nil for an empty document). Raises on malformed input or an unsupported construct.
  • Yaml.decodeWithComments(text: string): (any, boolean) — decode as decode does, and report whether the text carries a comment by the decoder's own rule: a # at a line's start or after whitespace, outside a quoted scalar and outside a block scalar. Re-encoding the value drops such comments, so an editor that writes a document back reads this first.
  • Yaml.encode(value: table): string — encode a Luau table as YAML (block style, two-space indent, alphabetically sorted keys). Raises on values YAML can't represent (functions, userdata, non-string mapping keys).

A top-level empty table encodes to an empty document, which decodes back to nil (the YAML empty-document ambiguity).

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

module Yaml YAML decode + encode for authored engine content. Supports the YAML subset engine configs use: block mappings + sequences, flow collections, typed plain scalars, quoted strings, comments, literal and folded block scalars, an optional leading `---`. Unsupported constructs (anchors, aliases, tags, directives, multi-document streams, tab indentation) raise with the offending line number.

fail(num: number, msg: string) → never

argtypedescription
numnumber
msgstring

stripComment(s: string, num: number) → string

Strip a comment from a raw line, honoring quotes. A `#` opens a comment at line start or after whitespace, outside quotes. A quote opens a quoted scalar only where a scalar can begin: the line's first content character, after a `- ` sequence marker, after a `key:`, or after a flow `[` / `{` / `,`. Elsewhere it is an ordinary character, which is what lets a plain scalar carry an apostrophe (`the world's rules`).

argtypedescription
sstring
numnumber

scanLines(text: string) → void

argtypedescription
textstring

isBlank(l: Line) → boolean

argtypedescription
lLine

rejectUnsupported(value: string, num: number) → void

Reject constructs the decoder does not implement, so nothing ever misparses silently.

argtypedescription
valuestring
numnumber

inferScalar(s: string) → any

argtypedescription
sstring

parseQuotedString(s: string, pos: number, num: number) → void

Parse a quoted string (either style) from `s` starting at the opening quote at `pos`. Returns (string, nextPos just past the closing quote).

argtypedescription
sstring
posnumber
numnumber

parseValueAt(s: string, pos: number, num: number, inFlow: boolean) → void

Parse one scalar-or-flow value from `s` starting at `pos`. Returns (value, nextPos).

argtypedescription
sstring
posnumber
numnumber
inFlowboolean

parseFlow(s: string, pos: number, num: number) → void

argtypedescription
sstring
posnumber
numnumber

parseBlockScalar(lines: { Line }, i: number, parentIndent: number, style: string) → void

Block scalar (| or >): consume the following deeper-indented lines. The first content line fixes the block's indentation; every later content line must be at least that deep — a line between the parent indent and the block indent is inconsistent and raises rather than losing data.

argtypedescription
lines{ Line }
inumber
parentIndentnumber
stylestring

failOnDocumentMarker(l: Line) → void

A `---` at column 0 on a structural line starts a second document. The decoder meets it only where it reads document structure, so the same characters inside a block scalar stay that scalar's text.

argtypedescription
lLine

parseKeyedValue(lines: { Line }, i: number, l: Line, rest: string) → void

Parse the value that follows `key:` — inline scalar/flow, block scalar, or a nested block on the following lines.

argtypedescription
lines{ Line }
inumber
lLine
reststring

parseBlock(lines: { Line }, i: number, indent: number) → void

argtypedescription
lines{ Line }
inumber
indentnumber

decodeDocument(text: string) → void

Decode `text`, noting whether any line outside a block scalar carries a comment.

argtypedescription
textstring

decode(text: string) → any

Decode a YAML document into a Luau value. Raises (with the line number) on malformed input or constructs outside the supported subset — never misparses silently.

argtypedescription
textstringThe YAML document text.

examples

local doc = Yaml.decode(vfs.read(path))

decodeWithComments(text: string) →

Decode a YAML document and report whether it carries a comment — by the decoder's own rule: a `#` at a line's start or after whitespace, outside a quoted scalar (a quote opens one only where a scalar can begin, so a plain scalar may carry an apostrophe) and outside a block scalar. What re-encoding the value would drop.

argtypedescription
textstringThe YAML document text.

examples

local doc, commented = Yaml.decodeWithComments(vfs.read(path))

isArray(t: { [any]: any }) → boolean

argtypedescription
t{ [any]: any }

encodeScalar(v: any) → string

argtypedescription
vany

sortedKeys(t: { [string]: any }) → void

argtypedescription
t{ [string]: any }

encodeValue(v: { [any]: any }, indent: number, out: { string }) → void

argtypedescription
v{ [any]: any }
indentnumber
out{ string }

encode(value: { [any]: any }) → string

Encode a Luau table as a YAML document (block style, two-space indent, sorted keys). Raises on values YAML can't represent (functions, userdata, non-string mapping keys).

argtypedescription
value{ [any]: any }The table to encode.

examples

vfs.write(path, Yaml.encode({ contract = "weapon", values = v }))

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

2items
Assets0Files2
This part has no composite children. See the Files segment for its leaf payloads.
backing path · modules/yaml.module

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported. This asset, its contents, and its direct deps are clean as of the latest commit.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.