fauxnix-cli 0.9.2 → 0.11.0

package/dist/parser.js

@@ -1,7 +1,14 @@
 import { FauxnixParseError, isUnquotedLiteral, wordToString, } from './ast.js';
 const OPERATORS = [
-    '&&', '||', '>>', '<<', '2>&1', '1>&2', '2>', '&>>', '&>', '>', '<', '|', ';',
+    '&&', '||', '>>', '<<', '2>&1', '1>&2', '2>', '&>>', '&>', '>', '<', '|', ';;', ';', '&',
 ];
+const BACKGROUND_MSG = 'fauxnix: background & is not supported yet. Run the command in the foreground instead.';
+const WHILE_UNTIL_MSG = 'fauxnix: while/until loops are not supported yet. Use `for x in ...; do ...; done` over a known list instead.';
+const CASE_MSG = 'fauxnix: case is not supported yet. Use if/elif/else instead.';
+const FUNCTION_MSG = 'fauxnix: functions are not supported yet. Inline the body or repeat the command instead.';
+const IF_IN_PIPELINE_MSG = 'fauxnix: if in a pipeline is not supported. Run the if as its own list segment instead of piping into it.';
+const FOR_IN_PIPELINE_MSG = 'fauxnix: for in a pipeline is not supported. Run the for as its own list segment instead of piping into it.';
+const CSTYLE_FOR_MSG = 'fauxnix: C-style for ((...)) is not supported yet. Use `for x in ...; do ...; done` instead.';
 export function tokenize(input) {
     const tokens = [];
     let i = 0;
@@ -242,6 +249,64 @@ function readArithParts(input) {
         parts.push({ kind: 'Text', text: buf });
     return parts;
 }
+/** Integer or `$name` operand of `${name:offset:length}`. */
+function readSliceNum(s, i) {
+    while (i < s.length && (s[i] === ' ' || s[i] === '\t'))
+        i++;
+    if (i >= s.length)
+        return null;
+    if (s[i] === '$') {
+        const j = i + 1;
+        if (j < s.length && isNameStart(s[j])) {
+            let k = j + 1;
+            while (k < s.length && isNameChar(s[k]))
+                k++;
+            return { val: s.slice(i, k), next: k };
+        }
+        if (j < s.length && (/[0-9]/.test(s[j]) || s[j] === '?' || s[j] === '$')) {
+            return { val: s.slice(i, j + 1), next: j + 1 };
+        }
+        return null;
+    }
+    let sign = '';
+    if (s[i] === '-' || s[i] === '+') {
+        sign = s[i];
+        i++;
+    }
+    if (i >= s.length || !/[0-9]/.test(s[i]))
+        return null;
+    let k = i;
+    while (k < s.length && /[0-9]/.test(s[k]))
+        k++;
+    return { val: sign + s.slice(i, k), next: k };
+}
+/** Parse `offset` / `offset:length` after `${name:`. Null if not a slice. */
+function parseSliceSpec(after) {
+    const off = readSliceNum(after, 0);
+    if (!off)
+        return null;
+    let i = off.next;
+    while (i < after.length && (after[i] === ' ' || after[i] === '\t'))
+        i++;
+    if (i >= after.length)
+        return { offset: off.val };
+    if (after[i] !== ':')
+        return null;
+    i++;
+    while (i < after.length && (after[i] === ' ' || after[i] === '\t'))
+        i++;
+    if (i >= after.length)
+        return { offset: off.val, length: '0' };
+    const len = readSliceNum(after, i);
+    if (!len)
+        return null;
+    i = len.next;
+    while (i < after.length && (after[i] === ' ' || after[i] === '\t'))
+        i++;
+    if (i !== after.length)
+        return null;
+    return { offset: off.val, length: len.val };
+}
 /** Parse $VAR, ${VAR}, $(cmd substitution), $((arith)). Returns null when not a valid dollar construct. */
 function readDollar(input, i) {
     const n = input.length;
@@ -255,31 +320,76 @@ function readDollar(input, i) {
         const end = input.indexOf('}', j);
         if (end === -1)
             throw new FauxnixParseError('fauxnix: unclosed ${');
-        const name = input.slice(j + 1, end);
-        const sub = name.match(/^([A-Za-z_][A-Za-z0-9_]*)\[([0-9]+|@|\*)\]$/);
-        if (sub) {
-            return { part: { kind: 'Var', name: sub[1], index: sub[2] }, next: end + 1 };
-        }
-        const pm = name.match(/^([A-Za-z_][A-Za-z0-9_]*)(:?[-+?])(.*)$/);
-        if (pm) {
-            const op = pm[2];
-            return {
-                part: { kind: 'Var', name: pm[1], param: { op, word: pm[3] } },
-                next: end + 1,
-            };
-        }
-        const hash = name.match(/^#([A-Za-z_][A-Za-z0-9_]*)(\[([0-9]+|@|\*)\])?$/);
+        const inner = input.slice(j + 1, end);
+        const nextPos = end + 1;
+        const hash = inner.match(/^#([A-Za-z_][A-Za-z0-9_]*)(\[([0-9]+|@|\*)\])?$/);
         if (hash) {
             return {
                 part: { kind: 'Var', name: hash[1], index: hash[3], length: true },
-                next: end + 1,
+                next: nextPos,
             };
         }
-        if (!name || !isNameStart(name[0]) || !name.split('').every(isNameChar)) {
+        // ${1} ${#} ${@} ${*} — positional / special params (not ${#name} length)
+        if (inner === '#' || inner === '@' || inner === '*' || /^[0-9]+$/.test(inner)) {
+            return { part: { kind: 'Var', name: inner }, next: nextPos };
+        }
+        const sub = inner.match(/^([A-Za-z_][A-Za-z0-9_]*)\[([0-9]+|@|\*)\]$/);
+        if (sub) {
+            return { part: { kind: 'Var', name: sub[1], index: sub[2] }, next: nextPos };
+        }
+        if (/^[A-Za-z_][A-Za-z0-9_]*\[([0-9]+|@|\*)\]/.test(inner)) {
+            throw new FauxnixParseError('fauxnix: ${name[@]:offset:length} subarray slice is not supported; use ${name:offset:length} on a scalar or ${name[i]} per element');
+        }
+        const ident = inner.match(/^([A-Za-z_][A-Za-z0-9_]*)/);
+        if (ident) {
+            const nm = ident[1];
+            const rest = inner.slice(nm.length);
+            if (rest.startsWith('/#') || rest.startsWith('/%')) {
+                throw new FauxnixParseError('fauxnix: ${name/#pat/str} and ${name/%pat/str} are not supported; use ${name//pat/str} instead');
+            }
+            if (rest.startsWith('/')) {
+                const global = rest.startsWith('//');
+                const body = rest.slice(global ? 2 : 1);
+                const slash = body.indexOf('/');
+                const pat = slash === -1 ? body : body.slice(0, slash);
+                const repl = slash === -1 ? '' : body.slice(slash + 1);
+                return {
+                    part: { kind: 'Var', name: nm, replace: { global, pat, repl } },
+                    next: nextPos,
+                };
+            }
+            if (rest.startsWith(':')) {
+                const after = rest.slice(1);
+                let t = 0;
+                while (t < after.length && (after[t] === ' ' || after[t] === '\t'))
+                    t++;
+                const lead = t < after.length ? after[t] : '';
+                const hadSpace = t > 0;
+                const paramLead = lead === '+' || lead === '?' || lead === '=' || (lead === '-' && !hadSpace);
+                if (!paramLead && lead !== '') {
+                    const sl = parseSliceSpec(after);
+                    if (sl) {
+                        return { part: { kind: 'Var', name: nm, slice: sl }, next: nextPos };
+                    }
+                }
+            }
+            const pm = inner.match(/^([A-Za-z_][A-Za-z0-9_]*)(:?[-+?])(.*)$/);
+            if (pm) {
+                const op = pm[2];
+                return {
+                    part: { kind: 'Var', name: pm[1], param: { op, word: pm[3] } },
+                    next: nextPos,
+                };
+            }
+            if (rest === '') {
+                return { part: { kind: 'Var', name: nm }, next: nextPos };
+            }
+        }
+        if (!inner || !isNameStart(inner[0]) || !inner.split('').every(isNameChar)) {
             // ${VAR:=default} etc. still raw text
-            return { part: { kind: 'Text', text: input.slice(i, end + 1) }, next: end + 1 };
+            return { part: { kind: 'Text', text: input.slice(i, end + 1) }, next: nextPos };
         }
-        return { part: { kind: 'Var', name }, next: end + 1 };
+        return { part: { kind: 'Var', name: inner }, next: nextPos };
     }
     // $((...)) arithmetic expansion — distinct from `$( (cmd) )` (space after
     // the first paren is command substitution of a grouped body).
@@ -350,8 +460,8 @@ function readDollar(input, i) {
             len++;
         return { part: { kind: 'Var', name: input.slice(j, j + len) }, next: j + len };
     }
-    // special: $? $$ $0-$9 — kept as symbolic Var; the translator maps them
-    if ('?$_'.includes(input[j]) || /[0-9]/.test(input[j])) {
+    // special: $? $$ $0-$9 $# $@ $* — kept as symbolic Var; the translator maps them
+    if ('?$_#@*'.includes(input[j]) || /[0-9]/.test(input[j])) {
         return { part: { kind: 'Var', name: input[j] }, next: j + 1 };
     }
     return null;
@@ -578,6 +688,76 @@ function pendingPatternOp(args) {
     }
     return null;
 }
+/** Unquoted `(` / `)` net depth in a word (quoted / escaped parens ignored). */
+function unquotedParenDelta(w) {
+    let d = 0;
+    for (const p of w) {
+        if (p.kind !== 'Text' || p.escaped)
+            continue;
+        for (const c of p.text) {
+            if (c === '(')
+                d++;
+            else if (c === ')')
+                d--;
+        }
+    }
+    return d;
+}
+function startsWithUnquotedOpenParen(w) {
+    if (w.length === 0)
+        return false;
+    const p = w[0];
+    return p.kind === 'Text' && !p.escaped && p.text.startsWith('(');
+}
+/** `NAME+=` (scalar or array append) — out of scope for C-2. */
+function isAppendAssignment(w) {
+    let s = '';
+    for (const p of w) {
+        if (p.kind === 'Text' && !p.escaped)
+            s += p.text;
+        else
+            break;
+        if (/^[A-Za-z_][A-Za-z0-9_]*\+=/.test(s))
+            return true;
+        if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(s))
+            return false;
+    }
+    return /^[A-Za-z_][A-Za-z0-9_]*\+=/.test(s);
+}
+function cloneWord(w) {
+    return w.map((p) => {
+        if (p.kind === 'Text' || p.kind === 'SingleQuoted')
+            return { ...p };
+        if (p.kind === 'DoubleQuoted')
+            return { kind: 'DoubleQuoted', parts: p.parts.slice() };
+        return p;
+    });
+}
+/** Strip the opening `(` and closing `)` that wrap an array assignment value. */
+function stripArrayParens(words) {
+    if (words.length === 0)
+        return [];
+    const ws = words.map(cloneWord);
+    const first = ws[0];
+    if (first.length > 0 && first[0].kind === 'Text' && first[0].text.startsWith('(')) {
+        first[0] = { kind: 'Text', text: first[0].text.slice(1), escaped: first[0].escaped };
+        if (first[0].text === '')
+            first.shift();
+    }
+    const last = ws[ws.length - 1];
+    for (let i = last.length - 1; i >= 0; i--) {
+        const p = last[i];
+        if (p.kind === 'Text' && !p.escaped && p.text.endsWith(')')) {
+            const trimmed = p.text.slice(0, -1);
+            if (trimmed === '')
+                last.splice(i, 1);
+            else
+                last[i] = { kind: 'Text', text: trimmed, escaped: p.escaped };
+            break;
+        }
+    }
+    return ws.filter((w) => w.length > 0);
+}
 /* ------------------------------------------------------------------ */
 /* Parser                                                              */
 /* ------------------------------------------------------------------ */
@@ -587,17 +767,44 @@ export function parseCommand(input) {
     const peek = () => tokens[pos];
     const next = () => tokens[pos++];
     const isListSep = (o) => o === ';' || o === '\n';
+    const isAmpWord = (t) => (!!t && t.type === 'OP' && t.op === '&') ||
+        (!!t && t.type === 'WORD' && !!t.parts && isUnquotedLiteral(t.parts, '&'));
+    const isCaseFallthrough = () => {
+        const t = peek();
+        if (t.type !== 'OP')
+            return false;
+        return (t.op === ';' || t.op === ';;') && isAmpWord(tokens[pos + 1]);
+    };
+    const throwUnexpectedDsemi = () => {
+        throw new FauxnixParseError("fauxnix: syntax error near unexpected token `;;'");
+    };
+    const throwCaseFallthrough = () => {
+        throw new FauxnixParseError('fauxnix: case fallthrough (;& / ;;&) is not supported; use ;; (no fallthrough) or duplicate the body');
+    };
     /** Consume `;` / newline / `&&` / `||`. Trailing `&&`/`||` and `;;` fail loud (bash). */
     const consumeListOp = (stops) => {
         const t = peek();
         if (t.type !== 'OP')
             return null;
+        if (t.op === '&') {
+            // inside a case arm, `;&` / `;;&` is fallthrough — report that, not background
+            if (stops && stops.has(';;'))
+                throwCaseFallthrough();
+            throw new FauxnixParseError(BACKGROUND_MSG);
+        }
+        if (t.op === ';;') {
+            if (stops && stops.has(';;'))
+                return null;
+            throwUnexpectedDsemi();
+        }
         if (!(t.op === '&&' || t.op === '||' || isListSep(t.op)))
             return null;
         if (t.op === ';') {
+            if (stops && stops.has(';;') && isAmpWord(tokens[pos + 1]))
+                return null;
             next();
-            if (peek().type === 'OP' && peek().op === ';') {
-                throw new FauxnixParseError("fauxnix: syntax error near unexpected token `;;'");
+            if (peek().type === 'OP' && (peek().op === ';' || peek().op === ';;')) {
+                throwUnexpectedDsemi();
             }
             return ';';
         }
@@ -627,16 +834,20 @@ export function parseCommand(input) {
         const segments = [];
         let op = ';';
         while (peek().type === 'OP' && isListSep(peek().op)) {
-            if (peek().op === ';' && tokens[pos + 1]?.type === 'OP' && tokens[pos + 1]?.op === ';') {
-                throw new FauxnixParseError("fauxnix: syntax error near unexpected token `;;'");
+            if (peek().op === ';' && tokens[pos + 1]?.type === 'OP' && (tokens[pos + 1]?.op === ';' || tokens[pos + 1]?.op === ';;')) {
+                throwUnexpectedDsemi();
             }
             next();
         }
         while (peek().type !== 'EOF') {
+            if (peek().type === 'OP' && peek().op === ';;')
+                throwUnexpectedDsemi();
             const pipeline = parsePipeline();
             segments.push({ pipeline, op });
             const nextOp = consumeListOp();
             if (nextOp === null) {
+                if (peek().type === 'OP' && peek().op === ';;')
+                    throwUnexpectedDsemi();
                 if (peek().type === 'EOF')
                     break;
                 throw new FauxnixParseError('fauxnix: unexpected token after pipeline');
@@ -653,18 +864,43 @@ export function parseCommand(input) {
             const kw = peekKw();
             if (kw === 'if') {
                 if (commands.length > 0) {
-                    throw new FauxnixParseError('fauxnix: if in a pipeline is not supported');
+                    throw new FauxnixParseError(IF_IN_PIPELINE_MSG);
                 }
                 commands.push(parseIf());
             }
             else if (kw === 'for') {
                 if (commands.length > 0) {
-                    throw new FauxnixParseError('fauxnix: for in a pipeline is not supported');
+                    throw new FauxnixParseError(FOR_IN_PIPELINE_MSG);
                 }
                 commands.push(parseFor());
             }
+            else if (kw === 'while') {
+                if (commands.length > 0) {
+                    throw new FauxnixParseError('fauxnix: while in a pipeline is not supported');
+                }
+                commands.push(parseWhile());
+            }
+            else if (kw === 'until') {
+                if (commands.length > 0) {
+                    throw new FauxnixParseError('fauxnix: until in a pipeline is not supported');
+                }
+                commands.push(parseUntil());
+            }
+            else if (kw === 'case') {
+                if (commands.length > 0) {
+                    throw new FauxnixParseError('fauxnix: case in a pipeline is not supported');
+                }
+                commands.push(parseCase());
+            }
+            else if (kw === 'function') {
+                throw new FauxnixParseError(FUNCTION_MSG);
+            }
             else {
-                commands.push(parseSimple());
+                const cmd = parseSimple();
+                if (cmd.kind === 'SimpleCommand' && cmd.name && isFunctionDef(cmd)) {
+                    throw new FauxnixParseError(FUNCTION_MSG);
+                }
+                commands.push(cmd);
             }
             const t = peek();
             if (t.type === 'OP' && t.op === '|') {
@@ -691,7 +927,11 @@ export function parseCommand(input) {
             s === 'in' ||
             s === 'do' ||
             s === 'done' ||
-            s === 'while') {
+            s === 'while' ||
+            s === 'until' ||
+            s === 'case' ||
+            s === 'esac' ||
+            s === 'function') {
             return s;
         }
         return null;
@@ -707,23 +947,34 @@ export function parseCommand(input) {
         const segments = [];
         let op = ';';
         while (peek().type === 'OP' && isListSep(peek().op)) {
-            if (peek().op === ';' && tokens[pos + 1]?.type === 'OP' && tokens[pos + 1]?.op === ';') {
-                throw new FauxnixParseError("fauxnix: syntax error near unexpected token `;;'");
+            if (peek().op === ';' && tokens[pos + 1]?.type === 'OP' && (tokens[pos + 1]?.op === ';' || tokens[pos + 1]?.op === ';;')) {
+                throwUnexpectedDsemi();
             }
             next();
         }
         while (peek().type !== 'EOF') {
+            if (stop.has(';;') && isCaseFallthrough())
+                break;
             const kw = peekKw();
             if (kw && stop.has(kw))
                 break;
+            const stopOp = peek();
+            if (stopOp.type === 'OP' && stopOp.op && stop.has(stopOp.op))
+                break;
+            if (stopOp.type === 'OP' && stopOp.op === ';;')
+                throwUnexpectedDsemi();
             const pipeline = parsePipeline();
             segments.push({ pipeline, op });
+            if (stop.has(';;') && isCaseFallthrough())
+                break;
             const nextOp = consumeListOp(stop);
             if (nextOp === null)
                 break;
             op = nextOp;
         }
         if (segments.length === 0) {
+            if (stop.has(';;'))
+                return { kind: 'CommandList', segments: [] };
             throw new FauxnixParseError('fauxnix: empty command');
         }
         return { kind: 'CommandList', segments };
@@ -761,6 +1012,9 @@ export function parseCommand(input) {
             throw new FauxnixParseError('fauxnix: `for` expected a name');
         }
         const name = wordToString(nt.parts);
+        if (name.startsWith('((')) {
+            throw new FauxnixParseError(CSTYLE_FOR_MSG);
+        }
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || !isUnquotedLiteral(nt.parts, name)) {
             throw new FauxnixParseError('fauxnix: `for` name must be an identifier');
         }
@@ -784,6 +1038,92 @@ export function parseCommand(input) {
         expectKw('done');
         return { kind: 'For', name, words, body, redirects: [] };
     };
+    const parseWhile = () => parseWhileLoop(false);
+    const parseUntil = () => parseWhileLoop(true);
+    const parseWhileLoop = (until) => {
+        expectKw(until ? 'until' : 'while');
+        const test = parseListUntil(['do']);
+        expectKw('do');
+        const body = parseListUntil(['done']);
+        expectKw('done');
+        return { kind: 'While', until, test, body, redirects: [] };
+    };
+    const skipCaseSeps = () => {
+        while (peek().type === 'OP' && isListSep(peek().op)) {
+            if (peek().op === ';' && isAmpWord(tokens[pos + 1]))
+                break;
+            next();
+        }
+    };
+    /** Strip a trailing unquoted `)` that closes a case pattern list. */
+    const stripTrailingUnquotedParen = (w) => {
+        if (w.length === 0)
+            return null;
+        const last = w[w.length - 1];
+        if (last.kind !== 'Text' || last.escaped || !last.text.endsWith(')'))
+            return null;
+        const rest = last.text.slice(0, -1);
+        if (rest.length === 0)
+            return w.slice(0, -1);
+        return [...w.slice(0, -1), { kind: 'Text', text: rest, escaped: last.escaped }];
+    };
+    const parseCasePatterns = () => {
+        const patterns = [];
+        for (;;) {
+            while (peek().type === 'OP' && (peek().op === '|' || peek().op === '\n'))
+                next();
+            if (peekKw() === 'esac') {
+                throw new FauxnixParseError("fauxnix: expected `)'");
+            }
+            const t = peek();
+            if (t.type !== 'WORD' || !t.parts) {
+                throw new FauxnixParseError('fauxnix: `case` expected a pattern');
+            }
+            const stripped = stripTrailingUnquotedParen(t.parts);
+            if (stripped !== null) {
+                next();
+                if (stripped.length > 0)
+                    patterns.push(stripped);
+                if (patterns.length === 0) {
+                    throw new FauxnixParseError('fauxnix: `case` expected a pattern');
+                }
+                return patterns;
+            }
+            patterns.push(t.parts);
+            next();
+        }
+    };
+    const parseCase = () => {
+        expectKw('case');
+        skipCaseSeps();
+        const wt = peek();
+        if (wt.type !== 'WORD' || !wt.parts) {
+            throw new FauxnixParseError('fauxnix: `case` expected a word');
+        }
+        const word = wt.parts;
+        next();
+        skipCaseSeps();
+        expectKw('in');
+        const arms = [];
+        skipCaseSeps();
+        while (peek().type !== 'EOF' && peekKw() !== 'esac') {
+            if (isCaseFallthrough())
+                throwCaseFallthrough();
+            const patterns = parseCasePatterns();
+            const body = parseListUntil(['esac', ';;']);
+            if (isCaseFallthrough())
+                throwCaseFallthrough();
+            if (peek().type === 'OP' && peek().op === ';;') {
+                next();
+                if (isAmpWord(peek()))
+                    throwCaseFallthrough();
+            }
+            arms.push({ patterns, body });
+            skipCaseSeps();
+        }
+        expectKw('esac');
+        return { kind: 'Case', word, arms, redirects: [] };
+    };
     const parseSimple = () => {
         const assignments = [];
         let redirects = [];
@@ -804,6 +1144,7 @@ export function parseCommand(input) {
                 (t.op === '&&' ||
                     t.op === '||' ||
                     t.op === '|' ||
+                    t.op === '&' ||
                     t.op === '>' ||
                     t.op === '<' ||
                     t.op === '>>' ||
@@ -817,7 +1158,8 @@ export function parseCommand(input) {
                 // Glue `|` onto the surrounding words so `=~ ^a|z$`,
                 // `=~ (a | b)c`, and `== @(x | y)` stay one operand. A
                 // spaced `|` outside an open regex / extglob group is a
-                // syntax error (bash).
+                // syntax error (bash). Tight `&` inside an open `=~ (…)`
+                // group stays in the regex, not a background job.
                 const last = args.length ? args[args.length - 1] : null;
                 const lastIsEqTilde = last !== null && isUnquotedLiteral(last, '=~');
                 const prevIsEqTilde = args.length >= 2 && isUnquotedLiteral(args[args.length - 2], '=~');
@@ -828,7 +1170,18 @@ export function parseCommand(input) {
                     pendingPatternOp(args) === '==' &&
                     unmatchedExtglob(last);
                 const inRe = lastIsEqTilde || prevIsEqTilde || openRe;
-                if (t.op === '|' || ((inRe || openExt) && t.tightLeft && t.op === '||')) {
+                if (t.op === '&') {
+                    if (!(openRe && last && t.tightLeft)) {
+                        throw new FauxnixParseError("fauxnix: [[: syntax error near unexpected token `&'");
+                    }
+                    args[args.length - 1] = [...last, { kind: 'Text', text: '&' }];
+                    const n = peek();
+                    if (n.type === 'WORD' && n.tightLeft && n.parts) {
+                        next();
+                        args[args.length - 1] = [...args[args.length - 1], ...n.parts];
+                    }
+                }
+                else if (t.op === '|' || ((inRe || openExt) && t.tightLeft && t.op === '||')) {
                     if (t.op === '|' &&
                         !lastIsEqTilde &&
                         !(prevIsEqTilde && t.tightLeft) &&
@@ -895,10 +1248,33 @@ export function parseCommand(input) {
                 break;
             const word = t.parts;
             // assignment prefix before command name?
+            if (name === null && isAppendAssignment(word)) {
+                throw new FauxnixParseError('fauxnix: `+=` append is not supported; use `A=(${A[@]} x)` or `A=(x y)` instead');
+            }
             if (name === null && isAssignment(word)) {
                 next();
                 const split = splitAssignment(word);
                 if (split) {
+                    if (startsWithUnquotedOpenParen(split.value)) {
+                        const elems = [split.value];
+                        let depth = unquotedParenDelta(split.value);
+                        while (depth > 0 && peek().type === 'WORD' && peek().parts) {
+                            const nxt = peek().parts;
+                            elems.push(nxt);
+                            depth += unquotedParenDelta(nxt);
+                            next();
+                        }
+                        if (depth > 0) {
+                            throw new FauxnixParseError('fauxnix: unclosed array assignment; close with `)` or use A=value for a scalar');
+                        }
+                        const values = stripArrayParens(elems);
+                        assignments.push({
+                            name: split.name,
+                            value: values.length > 0 ? values[0] : [],
+                            values,
+                        });
+                        continue;
+                    }
                     assignments.push(split);
                     continue;
                 }
@@ -965,6 +1341,9 @@ export function parseCommand(input) {
             if (assignments.length > 0) {
                 return { kind: 'SimpleCommand', assignments, name: null, args: [], redirects };
             }
+            if (peek().type === 'OP' && peek().op === '&') {
+                throw new FauxnixParseError(BACKGROUND_MSG);
+            }
             throw new FauxnixParseError('fauxnix: expected a command');
         }
         if (isUnquotedLiteral(name, '[[')) {
@@ -1061,6 +1440,16 @@ export function parseCommand(input) {
     }
     return parseList();
 }
+function isFunctionDef(cmd) {
+    if (!cmd.name)
+        return false;
+    const n = wordToString(cmd.name);
+    if (!isUnquotedLiteral(cmd.name, n))
+        return false;
+    if (/^[A-Za-z_][A-Za-z0-9_]*\(\)$/.test(n))
+        return true;
+    return cmd.args.length > 0 && isUnquotedLiteral(cmd.args[0], '()');
+}
 function isRedirectOp(op) {
     if (!op)
         return false;

package/dist/registry.d.ts

@@ -99,6 +99,8 @@ export interface CommandSpec {
     dispatch?: 'translated' | 'native' | 'dynamic';
     /** GNU usage/syntax exit (grep uses 2; cp/mv/rm use 1). */
     usageExit?: number;
+    /** First non-option operand ends option scanning (echo/printf). */
+    leadingOptions?: boolean;
     handler: Handler;
 }
 /** Register a spec'd command. Unknown/unsupported options become GNU-style usage errors. */

package/dist/registry.js

@@ -197,7 +197,8 @@ export function specsMarkdown() {
     for (const spec of registeredSpecs()) {
         lines.push('## `' + spec.names.join('` / `') + '`');
         lines.push('');
-        lines.push('Effects: ' + spec.effects.map((e) => '`' + e + '`').join(', '));
+        lines.push('Effects: ' +
+            (spec.effects.length ? spec.effects.map((e) => '`' + e + '`').join(', ') : 'none'));
         lines.push('');
         if (!spec.options.length) {
             lines.push('No options declared.');
@@ -319,6 +320,8 @@ export function specOptionError(spec, args, cmdName) {
             i++;
             continue;
         }
+        if (spec.leadingOptions)
+            onlyOperands = true;
         i++;
     }
     return null;