Log inGet started
Package

sourceEditing.module

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

Source editing

Tools and script builders use this module to discover Luau call arguments and edit their source declarations. A snapshot records the file identity and exact text. Every replacement uses a checked UTF-8 byte range in that snapshot; apply refuses changed files and overlapping ranges, and validates Luau or JSON syntax before writing.

local Source = require("@builtin::modules.sourceEditing")
local snapshot = Source.read("/zero/source/scenes/main.scene/build.luau")
local calls = Source.calls(snapshot, "asset.resolve")
local edit = Source.replace(calls[1].arguments[1], Source.literal("props.Chair"))
local preview = Source.preview(snapshot, { edit })
local result = Source.apply(snapshot, { edit })
assert(result.applied, result.reason)

Candidate evaluation uses a coroutine-local read scope:

local report, value = Source.evaluate({{snapshot=snapshot, source=plan.candidate}}, function()
    return Source.read(snapshot.path).source
end)

Only Source.read uses the proposed bytes. The callback's ordinary VFS reads continue to see committed content. The report contains original read snapshots for revision guards and the candidate paths actually consumed. Nested scopes restore their caller after success or failure. Scene source replacement uses this for JSON inputs read through this module, and commits their source, rebuilt scene and refreshed bindings together. Encode JSON replacement values with Json.encode.

Choose the intended occurrence and scope before preparing a replacement: one call in a loop can produce many placements. Discovery reports the function spelling, original argument expressions, line numbers and zero-based byte offsets with exclusive ends. Builders supply the semantic relationship between their outputs and those inputs.

A package can retain an immutable target alongside its generated output:

local target = Source.bind(snapshot, calls[1].arguments[1], {
    id = "room-west.asset",
    scope = "west room declaration",
    outputs = {"room-west"},
    scopeComplete = true,
})
local plan = Source.prepareTarget(target, Source.literal("props.Chair"))
-- Present plan.candidate and plan.target.scope/outputs to the caller.
local result = Source.apply(plan.target.snapshot, plan.edits)
assert(result.applied, result.reason)

The package supplies the stable input id and output identities. A declaration used by several placements lists that scope; use scopeComplete = false when the known outputs are only part of its effect. The target retains the exact snapshot it was bound against, so another source edit makes its apply stale. Rebind against a fresh snapshot after resolving the intended input again. Per-iteration changes in procedural loops need a distinct editable input or a package transformation that creates one.

Apply returns the ordinary VFS write report. Edit-mode writes become source; a caller participating in play follows the play-shadow rules. World sync reports remote persistence and conflicts. Read a fresh snapshot to prepare the next operation.

JSON inputs use the same exact-range replacement and binding operations:

local Json = require("@builtin::modules.json")
local snapshot = Source.read("/zero/source/layout.json")
local value = Source.jsonValue(snapshot, "/rooms/1/asset")
local edit = Source.replace(value, Json.encode("props.Chair"))
local result = Source.apply(snapshot, {edit})
assert(result.applied, result.reason)

JSON Pointers use zero-based array indices; escape a key's tilde as ~0 and slash as ~1. An empty pointer selects the root value. Discovery validates the complete document and refuses duplicate member names in traversed objects. Replacement preserves the surrounding bytes, including formatting. Encode JSON replacements with Json.encode; Source.literal produces Luau expressions.

An array index locates a value in the reviewed snapshot. A package resolves its stable record key, such as a room id, before selecting that index and binding its input. Changed source invalidates the prepared edit, including a reordered array.

For an array of records with string identities, select by the key:

local value = Source.jsonRecordValue(snapshot, "/rooms", "id", "east", "/asset")
local target = Source.bind(snapshot, value, {
    id="east.asset", scope="east room", outputs={"east"}, scopeComplete=true,
})
local plan = Source.prepareTarget(target, Json.encode("props.Chair"))

Every record in the selected array must carry the named string key, and those keys must be unique. Missing identities, duplicate keys and non-record array members are refused. Resolve again against a fresh snapshot after an array reorder: the key finds the same record, while the prepared edit still checks the exact old bytes before applying.