poe-code 15.0.4 → 15.0.5

package/packages/safe-bash/dist/shell/runtime.js

@@ -5,7 +5,7 @@ import { ACCESS_MODES, FsError, composeMiddleware, createBytePipe, pipeBytes, re
 import { concatShellValues, shellValueByteLength, shellValueBytes, shellValueFromBytes, shellValueText } from "../contracts/value.js";
 import { createCommandArguments, getCommandArguments } from "../contracts/command.js";
 import { ValueArena } from "./value-state.js";
-import { compoundEntryWords, HereDocumentSyntaxError, hereDocumentWords, parseShellInputUnit, parseShellUnit } from "./parser.js";
+import { parseArraySubscript, compoundEntryWords, HereDocumentSyntaxError, hereDocumentWords, parseShellInputUnit, parseShellUnit } from "./parser.js";
 import { SourceLineIndex } from "./source-line-index.js";
 import { ShellLimitError, ShellSyntaxError } from "./types.js";
 import { scopeFileSystem } from "poe-code/safe-fs/core";
@@ -16,6 +16,7 @@ import { BraceExpansionFailure, expandBraces } from "./brace-expansion.js";
 import { evaluatePositionalArithmetic } from "./arithmetic-parameters.js";
 import { compilePattern, compilePatternBoundaries, matchesPattern } from "./pattern.js";
 import { nextCodePointOffset, previousCodePointOffset, scanString, stringCheckpoint } from "./string-operations.js";
+import { selectMenu } from "./select-menu.js";
 import { byteLocale } from "./locale.js";
 import { functionDisplay } from "./display.js";
 import { ConditionalUnsupported, evaluateConditional } from "./conditional.js";
@@ -29,7 +30,8 @@ import { cloneGetoptsState, createGetoptsInput, createGetoptsState, GetoptsError
 import { activateChildCancellation, prepareChildCancellation, selectRuntimeCancellationOutcome, subscribeCancellation, } from "./cancellation.js";
 import { getArrayAssignment, getArraySelector, copyArraySelector, numericIndex, literalIndex, isQuoteMarker, prefixNameQuoteGroups } from "./arrays/syntax.js";
 import { ArrayFailure, ArrayOwner, exactSum } from "./arrays/ledger.js";
-import { controlNames, IndexedBinding, textToken } from "./arrays/bindings.js";
+import { controlNames, IndexedBinding, textToken, valueToken } from "./arrays/bindings.js";
+import { collectMapfile, mapfileOptions, MapfileUsageError } from "./mapfile.js";
 import { arrayStore, guestArrays, requireArrays, snapshotState, stateMonitor, trackState } from "./arrays/state.js";
 import { publishPipelineStatus } from "./pipestatus.js";
 import { EreProfileLimitError, EreSyntaxError, EreUnsupportedError } from "../commands/regex-execution/ere/errors.js";
@@ -37,6 +39,7 @@ import { EreLedger } from "../commands/regex-execution/ere/limits.js";
 import { compileEre } from "../commands/regex-execution/ere/syntax.js";
 import { matchEre } from "../commands/regex-execution/ere/matcher.js";
 import { PathLookup, pathTargets } from "./path-lookup.js";
+import { transformParameter } from "./parameter-transforms.js";
 export const defaultLimits = {
     maxParseUnits: defaultMaxParseUnits,
     maxInputBytes: 32 * 1024 * 1024,
@@ -56,7 +59,7 @@ export const defaultLimits = {
     pipeHighWaterMark: 64 * 1024,
 };
 const shellBuiltinNames = new Set([
-    ":", "true", "false", "pwd", "cd", "set", "shift", "export", "local", "unset", "read",
+    ":", "true", "false", "pwd", "cd", "set", "shift", "export", "local", "unset", "read", "declare", "mapfile", "readarray",
     "exit", "return", "break", "continue", "command", "builtin", "type", "readonly", "echo", "printf", "test", "[", ".", "source", "eval", "getopts", "let", "pushd", "dirs", "popd", "shopt",
 ]);
 const implementedBuiltins = new Set([...shellBuiltinNames].filter(name => !["echo", "printf", "test", "["].includes(name)));
@@ -1079,6 +1082,7 @@ class InvocationCancellationOwner {
         this.#failures.push(...result.failures);
     }
 }
+const mapfileCallbackStates = new WeakSet();
 export class Runtime {
     fs;
     commands;
@@ -1407,6 +1411,16 @@ export class Runtime {
         if (error instanceof NounsetFailure || error instanceof Flow || error instanceof ShellLimitError || error instanceof ShellSyntaxError)
             throw error;
     }
+    arithmeticValue(program, state, io) {
+        return evaluatePositionalArithmetic(program, {
+            parseBudget: this.budget.parsing,
+            positional: state.positional, arg0: state.arg0 ?? "virtual-bash", owner: arrayStore(state)?.owner,
+            maximumBytes: this.budget.limits.maxExpansionBytes,
+            checkpoint: () => this.signal.throwIfAborted(),
+            requireParameter: (name, value) => this.requireParameter(value, name, state, io),
+            limit: () => this.budget.fail("maxExpansionBytes"),
+        }, prepared => evaluateArithmetic(prepared, this.arithmeticVariables(state, io.diagnosticLine), this.budget.parsing));
+    }
     arithmeticVariables(state, line) {
         return new Proxy(state.variables, {
             get: (target, key) => {
@@ -1423,7 +1437,7 @@ export class Runtime {
     }
     variable(state, name) {
         const binding = arrayStore(state)?.get(name);
-        return binding ? binding.get(0) : state.variables[name];
+        return binding ? binding.get(binding.associative ? binding.keys.get("30")?.index ?? -1 : 0) : state.variables[name];
     }
     requireParameter(value, name, state, io, line) {
         if (state.nounset && value === undefined)
@@ -1434,7 +1448,7 @@ export class Runtime {
             this.writeVariable(state, name, value, origin);
             return;
         }
-        await this.arrayZero(state, name, async () => shellValueText(value));
+        await this.arrayZero(state, name, async () => value);
     }
     async prepareVariable(state, name, saved, scalarLegacy = false) {
         const store = requireArrays(state);
@@ -1579,7 +1593,7 @@ export class Runtime {
                     await operation.ledger.checkpoint(this.signal, 2);
                 }
                 if (typeof index === "number")
-                    staged.values.get(index)?.slot.release();
+                    staged.remove(index);
                 staged.maximum = maximum;
             }
             this.signal.throwIfAborted();
@@ -1617,6 +1631,7 @@ export class Runtime {
         const store = requireArrays(state);
         const operation = ArrayOwner.create(store.owner.ledger, store.owner);
         const holding = store.owner.hold();
+        const valueAllocation = this.budget.values.scope();
         let staged;
         try {
             const watch = await store.watch(name, operation, this.signal);
@@ -1637,10 +1652,13 @@ export class Runtime {
             if (!current)
                 throw new ArrayFailure("stale binding");
             staged = await current.copy(this.signal);
-            const value = append ? await this.arrayJoin(operation, [current.get(0) ?? "", expanded], "") : expanded;
-            const token = await textToken(staged.owner, value, this.signal);
+            const index = staged.associative ? (await staged.keyIndex("0", operation, this.signal, true)) : 0;
+            const previous = current.values.get(index)?.text.rawValue ?? current.get(index) ?? "";
+            const value = !append ? expanded : typeof previous === "string" && typeof expanded === "string"
+                ? await this.arrayJoin(operation, [previous, expanded], "") : concatShellValues([previous, expanded], valueAllocation);
+            const token = await valueToken(staged.owner, value, this.signal);
             try {
-                staged.insert(0, token);
+                staged.insert(index, token);
             }
             catch (error) {
                 token.release();
@@ -1671,6 +1689,7 @@ export class Runtime {
                 await operation.close();
             }
             finally {
+                valueAllocation.close();
                 holding.release();
             }
         }
@@ -1689,11 +1708,35 @@ export class Runtime {
         await owner.ledger.checkpoint(this.signal);
         return result;
     }
+    async arrayIndex(binding, index, state, io, owner, create = false) {
+        if (!binding?.associative) {
+            const selected = index.source === undefined ? index : literalIndex(index.source, 0, this.budget.parsing);
+            const number = numericIndex(selected);
+            if (number === undefined)
+                throw new ArrayFailure("index outside 0..2147483647");
+            return number;
+        }
+        const word = index.word ?? parseArraySubscript(index.source ?? index.decimal, this.budget.parsing, byteLocale(state.variables), state.depth);
+        const fields = await this.valueWord(word, state, io, false);
+        const value = fields.length === 1 ? fields[0] : concatShellValues(fields, io[valueScope]);
+        if (shellValueByteLength(value) === 0) {
+            await this.diagnostic(io, "associative array: bad array subscript");
+            if (create)
+                throw completedExit(1);
+            return undefined;
+        }
+        return binding.keyIndex(value, owner, this.signal, create);
+    }
     async arrayAssignment(assignment, state, io) {
         const name = assignment.name;
         this.signal.throwIfAborted();
-        if (state.readonlyVariables?.has(name))
+        if (state.readonlyVariables?.has(name)) {
+            if (arrayStore(state)?.get(name)?.associative) {
+                await this.diagnostic(io, `${name}: readonly variable`);
+                throw completedExit(1);
+            }
             throw new ArrayFailure("readonly binding");
+        }
         if (controlNames.has(name))
             throw new ArrayFailure("control binding cannot be indexed");
         if (state.exported.has(name))
@@ -1705,11 +1748,13 @@ export class Runtime {
         try {
             const watch = await store.watch(name, operation, this.signal);
             const current = store.get(name);
+            if (current?.associative && assignment.kind === "compound" && assignment.entries.length)
+                throw new ArrayFailure("nonempty associative compound assignment is unsupported");
             const initialMaximum = current?.maximum ?? (state.variables[name] === undefined ? -1 : 0);
             let planned = assignment.append && assignment.kind === "compound" ? initialMaximum + 1 : 0;
             if (assignment.kind === "element") {
                 operation.reserve({ work: assignment.index.decimal.length + 1 }).release();
-                if (numericIndex(assignment.index) === undefined)
+                if (!current?.associative && numericIndex(literalIndex(assignment.index.source ?? assignment.index.decimal, 0, this.budget.parsing)) === undefined)
                     throw new ArrayFailure("index outside 0..2147483647");
             }
             else
@@ -1743,9 +1788,9 @@ export class Runtime {
             const tickets = operation.reserve({ generation: true, version: true, epoch: true, work: 8 });
             const prepared = await store.prepareName(name, operation, this.signal);
             const preserve = assignment.kind === "element" || assignment.append;
-            staged = preserve && current ? await current.copy(this.signal) : IndexedBinding.create(store.owner);
+            staged = preserve && current ? await current.copy(this.signal) : IndexedBinding.create(store.owner, current?.associative);
             if (preserve && !current && state.variables[name] !== undefined) {
-                const token = await textToken(staged.owner, state.variables[name], this.signal);
+                const token = await valueToken(staged.owner, stateMonitor(state)?.values.get(name, state.variables[name]) ?? state.variables[name], this.signal);
                 try {
                     staged.insert(0, token);
                 }
@@ -1759,7 +1804,7 @@ export class Runtime {
             const insert = async (index, value) => {
                 if (index > 2147483647)
                     throw new ArrayFailure("index outside 0..2147483647");
-                const token = await textToken(staged.owner, value, this.signal);
+                const token = await valueToken(staged.owner, value, this.signal);
                 try {
                     staged.insert(index, token);
                 }
@@ -1769,12 +1814,14 @@ export class Runtime {
                 }
                 writes++;
             };
+            const join = async (values) => values.every(value => typeof value === "string")
+                ? this.arrayJoin(operation, values, "") : concatShellValues(values, io[valueScope]);
             if (assignment.kind === "element") {
-                const index = numericIndex(assignment.index);
-                const fields = await this.word(assignment.value, state, io, false);
-                let value = await this.arrayJoin(operation, fields, "");
+                const index = (await this.arrayIndex(staged, assignment.index, state, io, operation, true));
+                const fields = await this.valueWord(assignment.value, state, io, false);
+                let value = await join(fields);
                 if (assignment.append)
-                    value = await this.arrayJoin(operation, [staged.get(index) ?? "", value], "");
+                    value = await join([staged.values.get(index)?.text.rawValue ?? staged.get(index) ?? "", value]);
                 await insert(index, value);
             }
             else
@@ -1788,17 +1835,17 @@ export class Runtime {
                             expandedEntry = true;
                             const values = await this.valueWord(expanded, state, io, true, false, false, false, undefined, false);
                             for (const value of values) {
-                                await insert(cursor, shellValueText(value));
+                                await insert(cursor, value);
                                 cursor++;
                             }
                         }
                         if (expandedEntry)
                             continue;
                     }
-                    const fields = await this.word(entry.value, state, io, entry.index === undefined);
+                    const fields = await this.valueWord(entry.value, state, io, entry.index === undefined);
                     if (entry.index) {
                         const index = numericIndex(entry.index);
-                        await insert(index, await this.arrayJoin(operation, fields, ""));
+                        await insert(index, await join(fields));
                         cursor = index + 1;
                     }
                     else
@@ -2188,14 +2235,7 @@ export class Runtime {
                 }
                 if (command.kind === "arithmetic") {
                     try {
-                        return Number(evaluatePositionalArithmetic(command.expression, {
-                            parseBudget: this.budget.parsing,
-                            positional: state.positional, arg0: state.arg0 ?? "virtual-bash", owner: arrayStore(state)?.owner,
-                            maximumBytes: this.budget.limits.maxExpansionBytes,
-                            checkpoint: () => this.signal.throwIfAborted(),
-                            requireParameter: (name, value) => this.requireParameter(value, name, state, io),
-                            limit: () => this.budget.fail("maxExpansionBytes"),
-                        }, (prepared) => evaluateArithmetic(prepared, this.arithmeticVariables(state, io.diagnosticLine), this.budget.parsing)) === 0n);
+                        return Number(this.arithmeticValue(command.expression, state, io) === 0n);
                     }
                     catch (error) {
                         this.rethrowArithmeticControl(error);
@@ -2265,6 +2305,101 @@ export class Runtime {
                                 break;
                         }
                     }
+                    else if (command.kind === "arithmetic-for") {
+                        const evaluate = async (program) => {
+                            if (!program)
+                                return 1n;
+                            try {
+                                return this.arithmeticValue(program, state, io);
+                            }
+                            catch (error) {
+                                this.rethrowArithmeticControl(error);
+                                await this.diagnostic(io, `((: ${message(error, this.budget.onInternalError)}`);
+                                return undefined;
+                            }
+                        };
+                        if (await evaluate(command.expressions[0]) === undefined)
+                            return 1;
+                        while (true) {
+                            this.budget.loop();
+                            await yieldTurn(this.signal);
+                            const condition = await evaluate(command.expressions[1]);
+                            if (condition === undefined)
+                                return 1;
+                            if (condition === 0n)
+                                break;
+                            const result = await this.loopBody(command.body, state, io);
+                            status = result.status;
+                            if (result.stop)
+                                break;
+                            if (await evaluate(command.expressions[2]) === undefined)
+                                return 1;
+                        }
+                    }
+                    else if (command.kind === "select") {
+                        const values = command.words ? await this.valueWords(command.words, state, io) : this.positionalValues(state);
+                        if (!values.length)
+                            return 0;
+                        const input = io.stdin instanceof ShellInput ? io.stdin : new ShellInput(io.stdin, this.budget, this.signal);
+                        const work = { remaining: this.budget.limits.maxExpansionBytes * 8, signal: this.signal, exhausted: () => this.budget.fail("maxExpansionBytes") };
+                        let showMenu = true;
+                        while (true) {
+                            this.budget.loop();
+                            if (showMenu)
+                                await selectMenu(values, state.variables.COLUMNS, byteLocale(state.variables), io.stderr, work, allocation);
+                            const prompt = stateMonitor(state)?.values.get("PS3", state.variables.PS3 ?? "#? ") ?? state.variables.PS3 ?? "#? ";
+                            await io.stderr.write(shellValueBytes(prompt, allocation));
+                            const line = await input.selectLine(allocation);
+                            if (state.readonlyVariables?.has("REPLY")) {
+                                await this.diagnostic(io, "REPLY: readonly variable");
+                                await writeText(io.stdout, "\n");
+                                return 1;
+                            }
+                            this.writeVariable(state, "REPLY", line.value);
+                            if (!line.terminated) {
+                                await writeText(io.stdout, "\n");
+                                return 1;
+                            }
+                            const bytes = shellValueBytes(line.value, allocation);
+                            if (!bytes.length) {
+                                showMenu = true;
+                                continue;
+                            }
+                            let choice = 0;
+                            let phase = "start";
+                            let valid = true;
+                            let negative = false;
+                            let digits = false;
+                            for (const byte of bytes) {
+                                const pending = stringCheckpoint(work);
+                                if (pending)
+                                    await pending;
+                                if (byte === 32 || byte >= 9 && byte <= 13) {
+                                    if (phase === "digits")
+                                        phase = "tail";
+                                    continue;
+                                }
+                                if (phase === "start" && (byte === 43 || byte === 45)) {
+                                    negative = byte === 45;
+                                    phase = "digits";
+                                    continue;
+                                }
+                                if (phase === "tail" || byte < 48 || byte > 57) {
+                                    valid = false;
+                                    continue;
+                                }
+                                phase = "digits";
+                                digits = true;
+                                choice = Math.min(values.length + 1, choice * 10 + byte - 48);
+                            }
+                            await this.assignVariable(state, command.name, valid && digits && !negative && choice >= 1 && choice <= values.length ? values[choice - 1] : "");
+                            const result = await this.loopBody(command.body, state, io);
+                            status = result.status;
+                            if (result.stop)
+                                break;
+                            showMenu = shellValueByteLength(stateMonitor(state)?.values.get("REPLY", state.variables.REPLY ?? "") ?? state.variables.REPLY ?? "") === 0;
+                        }
+                    }
                     else {
                         while (true) {
                             this.budget.loop();
@@ -2384,6 +2519,7 @@ export class Runtime {
     async document(document, state, io, line = document.endLine) {
         this.signal.throwIfAborted();
         let value = "";
+        let fragments;
         let size = 0;
         let words = 0;
         const warnings = [];
@@ -2394,18 +2530,28 @@ export class Runtime {
                     await writeDiagnostic(io.stderr, `shell: warning: ${warning}\n`);
                 if (++words % 128 === 0)
                     await yieldTurn(this.signal);
-                const part = (await this.word(word, state, { ...io, nameExpansionContext: "document" }, false)).join("");
-                size += Buffer.byteLength(part);
+                const part = concatShellValues(await this.valueWord(word, state, { ...io, nameExpansionContext: "document" }, false), io[valueScope]);
+                size += shellValueByteLength(part);
                 if (size > this.budget.limits.maxExpansionBytes)
                     this.budget.fail("maxExpansionBytes");
-                value += part;
+                if (!fragments && typeof part === "string")
+                    value += part;
+                else {
+                    if (!fragments) {
+                        io[valueScope]?.reserve(64 + value.length * 2, 0);
+                        fragments = [value];
+                        value = "";
+                    }
+                    io[valueScope]?.reserve(32 + (typeof part === "string" ? part.length * 2 : 0), 0);
+                    fragments.push(part);
+                }
             }
         }
         finally {
             for (const warning of warnings.splice(0))
                 await writeDiagnostic(io.stderr, `shell: warning: ${warning}\n`);
         }
-        return value;
+        return fragments ? concatShellValues(fragments, io[valueScope]) : value;
     }
     async redirect(redirects, state, io, inputs, outputs, isolatedInlineInput = false, persistMoves = false, fileShortcut = false, line) {
         this.signal.throwIfAborted();
@@ -2437,6 +2583,7 @@ export class Runtime {
             const stdinIsDefault = descriptor?.input ? descriptor.stdinIsDefault : false;
             return {
                 [invocationScope]: io[invocationScope],
+                ...(io[valueScope] === undefined ? {} : { [valueScope]: io[valueScope] }),
                 ...(io.execution === undefined ? {} : { execution: io.execution }),
                 ...(io.diagnosticLine === undefined ? {} : { diagnosticLine: io.diagnosticLine }),
                 ...(io.diagnosticOffset === undefined ? {} : { diagnosticOffset: io.diagnosticOffset }),
@@ -2457,7 +2604,7 @@ export class Runtime {
                     const hereString = redirect.operator === "<<<";
                     let value;
                     try {
-                        value = redirect.document ? await this.document(redirect.document, state, currentIO(), line) : (await this.word(redirect.target, state, currentIO(), false, false, hereString)).join("");
+                        value = redirect.document ? await this.document(redirect.document, state, currentIO(), line) : concatShellValues(await this.valueWord(redirect.target, state, currentIO(), false, false, hereString), io[valueScope]);
                     }
                     catch (error) {
                         if (error instanceof NounsetFailure)
@@ -2471,11 +2618,11 @@ export class Runtime {
                         throw error;
                     }
                     if (hereString) {
-                        if (Buffer.byteLength(value) >= this.budget.limits.maxExpansionBytes)
+                        if (shellValueByteLength(value) >= this.budget.limits.maxExpansionBytes)
                             this.budget.fail("maxExpansionBytes");
-                        value += "\n";
+                        value = concatShellValues([value, "\n"], io[valueScope]);
                     }
-                    const input = new ShellInput(toByteSource(value), this.budget, this.signal);
+                    const input = new ShellInput(toByteSource(typeof value === "string" ? value : shellValueBytes(value, io[valueScope])), this.budget, this.signal);
                     inputs.add(input);
                     descriptors.set(redirect.descriptor, { input, stdinIsDefault: false });
                     continue;
@@ -2706,8 +2853,8 @@ export class Runtime {
                         throw new ArrayFailure("indexed binding cannot be a command prefix");
                     }
                     await this.arrayZero(state, assignment.name, async () => {
-                        const fields = await this.word(assignment.value, state, io, false);
-                        return this.arrayJoin(requireArrays(state).owner, fields, "");
+                        const fields = await this.valueWord(assignment.value, state, io, false);
+                        return fields.every(value => typeof value === "string") ? this.arrayJoin(requireArrays(state).owner, fields, "") : concatShellValues(fields, io[valueScope]);
                     }, assignment.append);
                     continue;
                 }
@@ -2870,6 +3017,7 @@ export class Runtime {
     }
     async dispatchScoped(name, values, state, io, assignments, bypassFunctions) {
         const { [invocationScope]: scope, ...publicIO } = io;
+        Reflect.deleteProperty(publicIO, valueScope);
         const allocation = this.budget.values.scope();
         scope.register(() => allocation.close());
         const argumentValues = this.admitArguments(values, allocation);
@@ -2911,7 +3059,8 @@ export class Runtime {
             scope.assertOpen();
             const forwardedValues = getCommandArguments(forwarded);
             const admitted = forwardedValues === argumentValues ? argumentValues : this.admitArguments(forwardedValues.values, allocation);
-            const context = { ...forwarded, args: admitted.args, argumentValues: admitted, [invocationScope]: scope };
+            const context = { ...forwarded, args: admitted.args, argumentValues: admitted, [invocationScope]: scope,
+                ...(io[valueScope] === undefined ? {} : { [valueScope]: io[valueScope] }) };
             const previous = new Map();
             const cwd = state.cwd;
             const directoryStackCwdPublication = state.directoryStackCwdPublication;
@@ -3047,6 +3196,9 @@ export class Runtime {
                         functionRestoration?.close();
                         throw error;
                     }
+                    const callerLoopDepth = state.loopDepth;
+                    if (mapfileCallbackStates.has(state))
+                        state.loopDepth = 0;
                     try {
                         return { exitCode: await this.command(body, state, { ...io, ...context, scriptName: body.sourceName ?? io.scriptName ?? "shell" }) };
                     }
@@ -3061,6 +3213,7 @@ export class Runtime {
                             savedPositionals.close();
                             state.positionalSetVersion = positionalSetVersion;
                             state.functionDepth--;
+                            state.loopDepth = callerLoopDepth;
                             state.depth--;
                             state.locals.pop();
                         };
@@ -3558,6 +3711,8 @@ export class Runtime {
                     return invocation;
                 },
             };
+            Reflect.deleteProperty(context, invocationScope);
+            Reflect.deleteProperty(context, valueScope);
             bindCommandIO(context);
             bindFileOutputBudget(context, sink => this.budget.sink(sink, runtime.signal));
             if (argumentValues.values.every(value => typeof value === "string"))
@@ -4677,6 +4832,137 @@ export class Runtime {
             allocation.close();
         }
     }
+    async mapfileBuiltin(context, state) {
+        const allocation = this.budget.values.scope();
+        const work = { remaining: this.budget.limits.maxExpansionBytes * 8, signal: this.signal, exhausted: () => this.budget.fail("maxExpansionBytes") };
+        let pinned;
+        let releaseHolding;
+        try {
+            const options = await mapfileOptions(context, work, allocation);
+            if (arrayStore(state)?.get(options.name)?.associative)
+                throw new MapfileUsageError(`${options.name}: not an indexed array`, 1);
+            if (state.readonlyVariables?.has(options.name))
+                throw new MapfileUsageError(`${options.name}: readonly variable`, 1);
+            if (controlNames.has(options.name) || state.exported.has(options.name))
+                throw new ArrayFailure("control or exported binding cannot be indexed");
+            const store = requireArrays(state);
+            const holding = store.owner.hold();
+            releaseHolding = () => holding.release();
+            if (!options.preserve || !store.get(options.name))
+                await this.arrayAssignment({ kind: "compound", name: options.name, append: options.preserve, entries: [] }, state, context);
+            const entry = store.bindings.get(options.name);
+            allocation.reserve(128 + Buffer.byteLength(options.name) * 2, 0);
+            pinned = entry.binding.retain();
+            const input = context.stdin instanceof ShellInput ? context.stdin : new ShellInput(context.stdin, this.budget, this.signal);
+            let pendingFlow;
+            await collectMapfile(options, input, {
+                allocation: () => this.budget.values.scope(),
+                loop: () => this.budget.loop(),
+                write: async (index, value) => {
+                    if (pinned !== entry.binding) {
+                        const previous = pinned;
+                        pinned = entry.binding.retain();
+                        await previous.release();
+                    }
+                    const operation = ArrayOwner.create(store.owner.ledger, store.owner);
+                    let staged;
+                    try {
+                        const current = pinned;
+                        const attached = store.bindings.get(options.name) === entry;
+                        const watch = attached ? await store.watch(options.name, operation, this.signal) : undefined;
+                        const supersede = attached ? await stateMonitor(state).prepareTypedPublication(options.name, operation, this.signal) : undefined;
+                        if (attached)
+                            await this.prepareArrayObservers(state, operation);
+                        const tickets = operation.reserve({ generation: true, version: true, epoch: true, work: 8 });
+                        // Exclude the mapfile pin and the live name's reference from COW.
+                        staged = current.references > (attached ? 2 : 1) ? await current.copy(this.signal) : current.retain();
+                        const token = await valueToken(staged.owner, value, this.signal);
+                        try {
+                            this.signal.throwIfAborted();
+                            if (watch && !watch.valid())
+                                throw new ArrayFailure("stale binding");
+                            staged.insert(index, token);
+                        }
+                        catch (error) {
+                            token.release();
+                            throw error;
+                        }
+                        if (attached) {
+                            let released;
+                            stateMonitor(state).publish(tickets, options.name, () => {
+                                supersede();
+                                released = store.publish(options.name, staged, tickets);
+                            });
+                            staged = undefined;
+                            await released;
+                        }
+                        else {
+                            const previous = pinned;
+                            pinned = staged;
+                            entry.binding = staged;
+                            staged = undefined;
+                            await previous.release();
+                        }
+                    }
+                    finally {
+                        try {
+                            await staged?.release();
+                        }
+                        finally {
+                            await operation.close();
+                        }
+                    }
+                },
+                callback: async (source, index, value) => {
+                    if (pendingFlow)
+                        return;
+                    const callbackAllocation = this.budget.values.scope();
+                    const nested = mapfileCallbackStates.has(state);
+                    try {
+                        const quoted = shellValueText(await transformParameter(value, "Q", { maximumBytes: this.budget.limits.maxExpansionBytes, byteLocale: byteLocale(state.variables), work, allocation: callbackAllocation }));
+                        if (Buffer.byteLength(source) + Buffer.byteLength(quoted) + String(index).length + 2 > this.budget.limits.maxExpansionBytes)
+                            this.budget.fail("maxExpansionBytes");
+                        mapfileCallbackStates.add(state);
+                        await this.evalBuiltin({ ...context, args: [source, String(index), quoted] }, state, context, false);
+                    }
+                    catch (error) {
+                        if (error instanceof Flow && (error.kind === "break" || error.kind === "continue"))
+                            pendingFlow = error;
+                        else
+                            throw error;
+                    }
+                    finally {
+                        if (!nested)
+                            mapfileCallbackStates.delete(state);
+                        callbackAllocation.close();
+                    }
+                },
+            });
+            if (pendingFlow)
+                throw pendingFlow;
+            return 0;
+        }
+        catch (error) {
+            this.signal.throwIfAborted();
+            if (!(error instanceof MapfileUsageError))
+                throw error;
+            await this.diagnostic(context, `${context.command}: ${error.message}`);
+            return error.status;
+        }
+        finally {
+            try {
+                await pinned?.release();
+            }
+            finally {
+                try {
+                    releaseHolding?.();
+                }
+                finally {
+                    allocation.close();
+                }
+            }
+        }
+    }
     async builtin(context, state, assignments, diagnose, suppressSpecial = false) {
         const { command, args, stdout, stderr } = context;
         if (command === ":" || command === "true")
@@ -4687,6 +4973,8 @@ export class Runtime {
             return this.shoptBuiltin(context, state);
         if (command === "let")
             return this.letBuiltin(context, state);
+        if (command === "mapfile" || command === "readarray")
+            return this.mapfileBuiltin(context, state);
         if (command === "getopts")
             return this.getoptsBuiltin(context, state);
         if (command === "pushd" || command === "dirs" || command === "popd")
@@ -4760,9 +5048,16 @@ export class Runtime {
             this.replacePositionals(state, this.positionalValues(state).slice(count));
             return 0;
         }
-        if (command === "export" || command === "local" || command === "readonly") {
+        if (command === "export" || command === "local" || command === "readonly" || command === "declare") {
+            const associativeDeclaration = command === "declare";
             const declarationArgs = [...args];
-            let indexedLocal = false;
+            let indexedLocal = associativeDeclaration;
+            if (associativeDeclaration) {
+                if (declarationArgs.shift() !== "-A" || !declarationArgs.length) {
+                    await this.diagnostic(context, "declare: only -A NAME is supported");
+                    return 2;
+                }
+            }
             if (command === "local") {
                 const options = localDeclarationOptions(declarationArgs, this.signal);
                 if (options.error !== undefined) {
@@ -4825,13 +5120,13 @@ export class Runtime {
                     status = 1;
                     continue;
                 }
-                if (command === "local" && indexedLocal) {
+                if ((command === "local" || associativeDeclaration) && indexedLocal) {
                     if (controlNames.has(name))
                         throw new ArrayFailure("control binding cannot be indexed");
                     if (state.exported.has(name))
                         throw new ArrayFailure("exported binding cannot be indexed");
-                    const existingLocal = locals.get(name);
-                    const saved = existingLocal ? undefined : assignments.get(name) ?? saveVariable(state, name);
+                    const existingLocal = locals?.get(name);
+                    const saved = !locals || existingLocal ? undefined : assignments.get(name) ?? saveVariable(state, name);
                     let operation;
                     let holding;
                     let shadow;
@@ -4856,12 +5151,15 @@ export class Runtime {
                         const tickets = operation.reserve({ generation: true, version: true, epoch: true, work: 8 });
                         const prepared = await store.prepareName(name, operation, this.signal);
                         const current = store.get(name);
-                        shadow = !saved && current ? await current.copy(this.signal) : IndexedBinding.create(store.owner);
+                        if (!saved && current && current.associative !== associativeDeclaration)
+                            throw new ArrayFailure("cannot convert array kind");
+                        shadow = !saved && current ? await current.copy(this.signal) : IndexedBinding.create(store.owner, associativeDeclaration);
                         const value = match[2] ?? (!saved && !current && Object.hasOwn(state.variables, name) ? state.variables[name] : undefined);
                         if (value !== undefined) {
-                            const token = await textToken(shadow.owner, value, this.signal);
+                            const retained = associativeDeclaration && match[2] === undefined ? stateMonitor(state).values.get(name, value) : value;
+                            const token = await valueToken(shadow.owner, retained, this.signal);
                             try {
-                                shadow.insert(0, token);
+                                shadow.insert(associativeDeclaration ? (await shadow.keyIndex("0", operation, this.signal, true)) : 0, token);
                             }
                             catch (error) {
                                 token.release();
@@ -5036,7 +5334,8 @@ export class Runtime {
         }
         if (command === "unset") {
             let status = 0;
-            for (const name of args) {
+            for (let argument = 0; argument < args.length; argument++) {
+                const name = args[argument];
                 const selected = /^([a-zA-Z_][a-zA-Z_0-9]*)\[(.*)\]$/su.exec(name);
                 if (selected) {
                     const base = selected[1];
@@ -5046,7 +5345,16 @@ export class Runtime {
                         status = 1;
                         continue;
                     }
-                    if (selector === "@" || selector === "*")
+                    const binding = arrayStore(state)?.get(base);
+                    if (binding?.associative) {
+                        const original = getCommandArguments(context).values[argument];
+                        const index = typeof original === "string"
+                            ? await this.arrayIndex(binding, { decimal: selector, source: selector }, state, context, binding.owner)
+                            : await binding.keyIndex(shellValueFromBytes(shellValueBytes(original, context[valueScope]).subarray(base.length + 1, shellValueByteLength(original) - 1), context[valueScope]), binding.owner, this.signal);
+                        if (index !== undefined)
+                            await this.unsetIndexed(state, base, index);
+                    }
+                    else if (selector === "@" || selector === "*")
                         await this.unsetIndexed(state, base, "members");
                     else {
                         let index;
@@ -5304,6 +5612,35 @@ export class Runtime {
         }
     }
     async valuePart(part, state, io, hereString = false) {
+        if (part.kind === "variable" && part.transform) {
+            const selector = getArraySelector(part);
+            if (selector?.kind === "members" || part.name === "@" || part.name === "*") {
+                const members = selector ? await this.arrayMembers(part.name, state, io, part.keys) : this.positionalValues(state);
+                const ifs = state.variables.IFS ?? " ";
+                const separator = ifs.length ? String.fromCodePoint(ifs.codePointAt(0)) : "";
+                const fragments = [];
+                let bytes = 0;
+                for (const member of members) {
+                    const value = await this.transformValue(member, part.transform, state, io);
+                    bytes += shellValueByteLength(value) + (fragments.length ? Buffer.byteLength(separator) : 0);
+                    if (bytes > this.budget.limits.maxExpansionBytes)
+                        this.budget.fail("maxExpansionBytes");
+                    io[valueScope]?.reserve(32, 0);
+                    if (fragments.length)
+                        fragments.push(separator);
+                    fragments.push(value);
+                }
+                return concatShellValues(fragments, io[valueScope]);
+            }
+            const base = { ...part };
+            delete base.transform;
+            copyArraySelector(part, base);
+            const existing = selector?.kind === "element" ? arrayStore(state)?.get(part.name)?.get(numericIndex(selector.index) ?? -1) ?? (numericIndex(selector.index) === 0 ? this.variable(state, part.name) : undefined)
+                : /^[a-zA-Z_][a-zA-Z_0-9]*$/u.test(part.name) ? this.variable(state, part.name)
+                    : /^[1-9][0-9]*$/u.test(part.name) ? state.positional[Number(part.name) - 1] : "";
+            const value = await this.valuePart(base, state, io, hereString);
+            return existing === undefined ? "" : this.transformValue(value, part.transform, state, io);
+        }
         if (part.kind === "variable" && part.prefixNames) {
             const ifs = state.variables.IFS ?? " ";
             const separator = io.nameExpansionContext === "document" || io.nameExpansionContext === "conditional" && part.prefixNames === "@"
@@ -5324,10 +5661,25 @@ export class Runtime {
         const binding = part.kind === "variable" ? arrayStore(state)?.get(part.name) : undefined;
         const holding = binding ? requireArrays(state).owner.hold() : undefined;
         const selector = getArraySelector(part);
-        const index = selector?.kind === "element" ? numericIndex(selector.index) : 0;
+        if (selector?.kind === "element" && binding?.associative) {
+            try {
+                const index = await this.arrayIndex(binding, selector.index, state, io, binding.owner);
+                const token = index === undefined ? undefined : binding.values.get(index)?.text;
+                this.requireParameter(token?.value, part.kind === "variable" ? part.name : "", state, io);
+                if (part.kind === "variable" && part.length)
+                    return this.parameterLength(token?.value ?? "");
+                return token?.rawValue ? shellValueFromBytes(shellValueBytes(token.rawValue, io[valueScope]), io[valueScope]) : token?.value ?? "";
+            }
+            finally {
+                holding?.release();
+            }
+        }
+        const index = selector?.kind === "element" ? numericIndex(selector.index) : binding?.associative ? binding.keys.get("30")?.index : 0;
         const token = index === undefined || selector?.kind === "members" ? undefined : binding?.values.get(index)?.text;
         token?.retain();
         try {
+            if (token?.rawValue && part.kind === "variable" && !part.length && !part.operator && !part.substring)
+                return shellValueFromBytes(shellValueBytes(token.rawValue, io[valueScope]), io[valueScope]);
             const value = await this.partValue(part, state, io, hereString);
             if (binding)
                 await textToken(requireArrays(state).owner, shellValueText(value), this.signal);
@@ -5345,6 +5697,19 @@ export class Runtime {
             throw new ShellSyntaxError("Syntax nesting exceeds 64", word.offset);
         return { ...io, parameterDepth };
     }
+    async transformValue(value, operator, state, io) {
+        const allocation = io[valueScope] ?? this.budget.values.scope();
+        try {
+            return await transformParameter(value, operator, {
+                maximumBytes: this.budget.limits.maxExpansionBytes, byteLocale: byteLocale(state.variables), allocation,
+                work: { remaining: Math.min(Number.MAX_SAFE_INTEGER, this.budget.limits.maxExpansionBytes * 8 + 1024), signal: this.signal, exhausted: () => this.budget.fail("maxExpansionBytes") },
+            });
+        }
+        finally {
+            if (!io[valueScope])
+                allocation.close();
+        }
+    }
     async partValue(part, state, io, hereString) {
         this.signal.throwIfAborted();
         if (part.kind === "compound-substitution-eof") {
@@ -5444,8 +5809,12 @@ export class Runtime {
             }
             if (part.length)
                 return String(binding?.values.size ?? (state.variables[part.name] === undefined ? 0 : 1));
-            const values = await this.arrayMembers(part.name, state);
-            return this.arrayJoin(store.owner, values, Array.from(state.variables.IFS ?? " ")[0] ?? "");
+            const values = await this.arrayMembers(part.name, state, io, part.keys);
+            const separator = Array.from(state.variables.IFS ?? " ")[0] ?? "";
+            if (values.every(value => typeof value === "string"))
+                return this.arrayJoin(store.owner, values, separator);
+            io[valueScope]?.reserve(values.length * 32 + 64, 0);
+            return concatShellValues(values.flatMap((value, index) => index ? [separator, value] : [value]), io[valueScope]);
         }
         let value = part.name === "?" ? String(state.status)
             : part.name === "-" ? `${state.errexit ? "e" : ""}${state.nounset ? "u" : ""}${state.braceexpand !== false ? "B" : ""}`
@@ -5769,7 +6138,7 @@ export class Runtime {
             return fields;
         }
         const arrayOwned = word.parts.some(part => part.kind === "variable" && !part.prefixNames && (getArraySelector(part) !== undefined || arrayStore(state)?.get(part.name) !== undefined));
-        const prefixOwned = word.parts.some(part => part.kind === "variable" && part.prefixNames === "@");
+        const prefixOwned = word.parts.some(part => part.kind === "variable" && (part.prefixNames === "@" || part.transform && part.name === "@"));
         const owner = arrayOwned ? requireArrays(state).owner : undefined;
         const holding = owner?.hold();
         const scratch = !owner && split && state.variables.IFS !== "" && word.parts.some(part => !part.quoted && part.kind !== "text")
@@ -5921,17 +6290,23 @@ export class Runtime {
                         emptyNameGroups.add(quoteGroup);
                     }
                 }
-                else if (part.kind === "variable" && selector?.kind === "members" && !part.length && split && (!part.quoted || selector.separator === "@")) {
-                    const members = await this.arrayMembers(part.name, state);
+                else if (part.kind === "variable" && split && (selector?.kind === "members" && !part.length && (!part.quoted || selector.separator === "@") || part.transform && part.name === "@")) {
+                    const members = selector?.kind === "members" ? await this.arrayMembers(part.name, state, io, part.keys) : this.positionalValues(state);
                     for (let position = 0; position < members.length; position++) {
                         if (position > 0)
                             addField();
-                        const value = members[position];
+                        const original = members[position];
+                        const value = part.transform ? await this.transformValue(original, part.transform, state, partIO) : original;
                         if (part.quoted || state.variables.IFS === "")
-                            append(value, !part.quoted, part.quoted || value.length > 0);
+                            append(value, !part.quoted, part.quoted || shellValueByteLength(value) > 0);
                         else
                             await appendSplit(value);
                     }
+                    if (part.transform && members.length === 0 && quoteGroup) {
+                        io[valueScope]?.reserve(32, 0);
+                        emptyNameGroups ??= new Set();
+                        emptyNameGroups.add(quoteGroup);
+                    }
                 }
                 else if (part.kind === "text" && !splitText) {
                     let value = invokedValues.get(part) ?? part.byteValue ?? part.value;
@@ -5939,7 +6314,7 @@ export class Runtime {
                         value = (state.variables.HOME ?? "~") + value.slice(1);
                     append(value, !part.quoted, quotedPresence || shellValueByteLength(value) > 0);
                 }
-                else if (part.kind === "variable" && part.name === "@" && part.quoted && !part.operator && split) {
+                else if (part.kind === "variable" && part.name === "@" && part.quoted && !part.operator && !part.transform && split) {
                     for (let position = 0; position < state.positional.length; position++) {
                         if (position > 0)
                             addField();
@@ -6091,7 +6466,7 @@ export class Runtime {
                 allocation.hold(value);
         return createCommandArguments(values, allocation);
     }
-    async arrayMembers(name, state) {
+    async arrayMembers(name, state, io, keys = false) {
         const store = requireArrays(state);
         const holding = store.owner.hold();
         try {
@@ -6103,7 +6478,7 @@ export class Runtime {
                     return [];
                 store.owner.reserve({ metadata: 32, allocatedSlots: 1, work: 3 });
                 await textToken(store.owner, value, this.signal);
-                return [value];
+                return [keys ? "0" : value];
             }
             binding.retain();
             try {
@@ -6111,8 +6486,10 @@ export class Runtime {
                 const values = [];
                 for (const index of indices) {
                     store.owner.reserve({ metadata: 32, allocatedSlots: 1, work: 4 });
-                    const value = binding.get(index);
-                    await textToken(store.owner, value, this.signal);
+                    const token = keys ? binding.associative ? binding.keys.get(binding.keyByIndex.get(index)).text : await textToken(store.owner, String(index), this.signal) : binding.values.get(index).text;
+                    const value = token.rawValue === undefined ? token.value : shellValueFromBytes(shellValueBytes(token.rawValue, io[valueScope]), io[valueScope]);
+                    if (typeof value === "string")
+                        await textToken(store.owner, value, this.signal);
                     values.push(value);
                     await store.owner.ledger.checkpoint(this.signal);
                 }