tarsec 0.4.6 → 0.5.0

package/README.md

@@ -36,6 +36,7 @@ parser("hello there"); // failure
 ## Learning tarsec
 - [A five minute introduction](/tutorials/5-minute-intro.md)
 - [The three building blocks in tarsec](/tutorials/three-building-blocks.md)
+- [Lexemes: your grammar's token vocabulary](/tutorials/lexemes.md)
 - [API reference](https://egonschiele.github.io/tarsec/)
 
 ## Features

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from "./types.js";
 export * from "./tarsecError.js";
 export * from "./position.js";
 export * from "./rightmostFailure.js";
+export * from "./lexeme.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export * from "./types.js";
 export * from "./tarsecError.js";
 export * from "./position.js";
 export * from "./rightmostFailure.js";
+export * from "./lexeme.js";

package/dist/lexeme.d.ts

@@ -0,0 +1,71 @@
+import { CharPredicate } from "./parsers.js";
+import { CaptureParser, Parser, PlainObject } from "./types.js";
+/** Configuration for `makeLexemes`. */
+export type LexemeConfig = {
+    /** Characters eaten after every lexeme, e.g. " \t". */
+    whitespace: string;
+    /** Line-comment marker (e.g. "#" or "//"); comments are eaten as whitespace,
+     * up to but NOT including the newline (newlines may be significant). */
+    lineComment?: string;
+    /** When true, `\` followed by a newline is also eaten as whitespace. */
+    lineContinuation?: boolean;
+    /** Charset or predicate for an identifier's first character.
+     * Defaults to letters and "_". */
+    identStart?: string | CharPredicate;
+    /** Charset or predicate for subsequent identifier characters.
+     * Defaults to letters, digits, and "_". */
+    identRest?: string | CharPredicate;
+    /** Words `identifier` refuses to match (and `keyword` accepts). */
+    keywords?: string[];
+    /** Charset or predicate for characters that can appear in operators.
+     * `operator` uses it for longest-match rejection: `operator("<")` refuses
+     * to match the front of `<=`. Defaults to common symbol characters. */
+    operatorChars?: string | CharPredicate;
+};
+export type Lexemes = {
+    /** Whitespace/comment skipper as a parser. Always succeeds. Use once at the
+     * top of a grammar to eat leading whitespace; lexemes handle the rest. */
+    whitespace: Parser<null>;
+    /** Whitespace/comment skipper as a total function: returns the input with
+     * leading whitespace removed. Handy where a parser result would force
+     * callers to handle a failure that cannot happen. */
+    skipWhitespace: (input: string) => string;
+    /** Run a parser, then eat trailing whitespace/comments. Capture-preserving. */
+    lexeme: {
+        <T, C extends PlainObject>(parser: CaptureParser<T, C>): CaptureParser<T, C>;
+        <T>(parser: Parser<T>): Parser<T>;
+    };
+    /** `lexeme(str(s))` — match a literal, eat trailing whitespace. */
+    symbol: <const S extends string>(s: S) => Parser<S>;
+    /** Match an identifier (per identStart/identRest), rejecting keywords. */
+    identifier: Parser<string>;
+    /** Match `s` only when not followed by an identRest character, so
+     * `keyword("if")` rejects "ifx". */
+    keyword: (s: string) => Parser<string>;
+    /** Match `s` only when not followed by an operator character, so
+     * `operator("<")` rejects the front of "<=". The symbolic counterpart
+     * of `keyword`. */
+    operator: (s: string) => Parser<string>;
+    /** Run a parser between "(" and ")", whitespace handled. Returns the
+     * inner result. */
+    parens: <T>(parser: Parser<T>) => Parser<T>;
+    /** Like `parens`, with "[" and "]". */
+    brackets: <T>(parser: Parser<T>) => Parser<T>;
+    /** Like `parens`, with "{" and "}". */
+    braces: <T>(parser: Parser<T>) => Parser<T>;
+    /** Zero or more of `parser`, separated by commas. */
+    commaSep: <T>(parser: Parser<T>) => Parser<T[]>;
+    /** One or more of `parser`, separated by commas. */
+    commaSep1: <T>(parser: Parser<T>) => Parser<T[]>;
+};
+/**
+ * Build a set of lexeme helpers: ordinary parsers that handle whitespace,
+ * comments, and keywords in one place. This is a *scannerless* lexeme layer
+ * (like Parsec's `makeTokenParser`), not a lexer — there is no separate pass
+ * and no token array.
+ *
+ * The discipline: every token-shaped parser eats its own *trailing*
+ * whitespace; eat *leading* whitespace once at the top with `whitespace`
+ * (or `skipWhitespace`).
+ */
+export declare function makeLexemes(config: LexemeConfig): Lexemes;

package/dist/lexeme.js

@@ -0,0 +1,130 @@
+import { sepBy, sepBy1, seq } from "./combinators.js";
+import { compileCharPredicate, str } from "./parsers.js";
+import { trace } from "./trace.js";
+import { recordFailure } from "./rightmostFailure.js";
+import { failure, success, } from "./types.js";
+const LETTERS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const DIGITS = "0123456789";
+const OPERATOR_CHARS = "+-*/<>=!&|^%~?:.";
+const BACKSLASH_CODE = 0x5c;
+const NEWLINE = "\n";
+/**
+ * Build a set of lexeme helpers: ordinary parsers that handle whitespace,
+ * comments, and keywords in one place. This is a *scannerless* lexeme layer
+ * (like Parsec's `makeTokenParser`), not a lexer — there is no separate pass
+ * and no token array.
+ *
+ * The discipline: every token-shaped parser eats its own *trailing*
+ * whitespace; eat *leading* whitespace once at the top with `whitespace`
+ * (or `skipWhitespace`).
+ */
+export function makeLexemes(config) {
+    var _a, _b, _c, _d;
+    const isWhitespaceChar = compileCharPredicate(config.whitespace);
+    // Treat an empty marker as absent: `startsWith("", i)` is always true, so
+    // "" would make the comment branch loop forever at a newline.
+    const commentMarker = config.lineComment || undefined;
+    const allowContinuation = config.lineContinuation === true;
+    const skipWhitespace = (input) => {
+        let index = 0;
+        const length = input.length;
+        // Terminates: every branch either advances `index` or breaks.
+        while (index < length) {
+            if (isWhitespaceChar(input.charCodeAt(index))) {
+                index++;
+                continue;
+            }
+            if (allowContinuation &&
+                input.charCodeAt(index) === BACKSLASH_CODE &&
+                input[index + 1] === NEWLINE) {
+                index += 2;
+                continue;
+            }
+            if (commentMarker !== undefined && input.startsWith(commentMarker, index)) {
+                const newlineIndex = input.indexOf(NEWLINE, index);
+                if (newlineIndex === -1) {
+                    index = length;
+                }
+                else {
+                    index = newlineIndex; // stop AT the newline, don't consume it
+                }
+                continue;
+            }
+            break;
+        }
+        return input.slice(index);
+    };
+    const whitespace = trace("lexeme:whitespace", (input) => success(null, skipWhitespace(input)));
+    const lexeme = ((parser) => (input) => {
+        const result = parser(input);
+        if (!result.success)
+            return result;
+        return Object.assign(Object.assign({}, result), { rest: skipWhitespace(result.rest) });
+    });
+    const symbol = (s) => lexeme(str(s));
+    const isIdentStart = compileCharPredicate((_a = config.identStart) !== null && _a !== void 0 ? _a : LETTERS + "_");
+    const isIdentRest = compileCharPredicate((_b = config.identRest) !== null && _b !== void 0 ? _b : LETTERS + DIGITS + "_");
+    const keywordSet = new Set((_c = config.keywords) !== null && _c !== void 0 ? _c : []);
+    const identifier = lexeme(trace("lexeme:identifier", (input) => {
+        if (input.length === 0 || !isIdentStart(input.charCodeAt(0))) {
+            recordFailure(input, "an identifier");
+            return failure("expected an identifier", input);
+        }
+        let end = 1;
+        // Terminates: `end` strictly increases toward input.length.
+        while (end < input.length && isIdentRest(input.charCodeAt(end)))
+            end++;
+        const name = input.slice(0, end);
+        if (keywordSet.has(name)) {
+            recordFailure(input, "an identifier");
+            return failure(`expected an identifier, got keyword ${name}`, input);
+        }
+        return success(name, input.slice(end));
+    }));
+    /** Match `s` as a whole token: it must not be followed by a character
+     * from `continuationChars`, so a shorter token never steals the front of
+     * a longer one. Shared by `keyword` (identifier characters) and
+     * `operator` (operator characters). */
+    function wholeToken(kind, s, isContinuation) {
+        return lexeme(trace(`lexeme:${kind}(${s})`, (input) => {
+            if (!input.startsWith(s)) {
+                recordFailure(input, `${kind} ${s}`);
+                return failure(`expected ${kind} ${s}`, input);
+            }
+            const followingCode = input.charCodeAt(s.length);
+            // charCodeAt returns NaN past the end of input; NaN fails the
+            // predicate, so a token at end-of-input matches.
+            if (!Number.isNaN(followingCode) && isContinuation(followingCode)) {
+                recordFailure(input, `${kind} ${s}`);
+                return failure(`expected ${kind} ${s}`, input);
+            }
+            return success(s, input.slice(s.length));
+        }));
+    }
+    const keyword = (s) => wholeToken("keyword", s, isIdentRest);
+    const isOperatorChar = compileCharPredicate((_d = config.operatorChars) !== null && _d !== void 0 ? _d : OPERATOR_CHARS);
+    const operator = (s) => wholeToken("operator", s, isOperatorChar);
+    function delimited(open, close, parser) {
+        return seq([symbol(open), parser, symbol(close)], (results) => results[1]);
+    }
+    const parens = (parser) => delimited("(", ")", parser);
+    const brackets = (parser) => delimited("[", "]", parser);
+    const braces = (parser) => delimited("{", "}", parser);
+    const comma = symbol(",");
+    const commaSep = (parser) => sepBy(comma, parser);
+    const commaSep1 = (parser) => sepBy1(comma, parser);
+    return {
+        whitespace,
+        skipWhitespace,
+        lexeme,
+        symbol,
+        identifier,
+        keyword,
+        operator,
+        parens,
+        brackets,
+        braces,
+        commaSep,
+        commaSep1,
+    };
+}

package/dist/parsers/bash/commands.d.ts

@@ -0,0 +1,11 @@
+import { Parser, ParserResult } from "../../types.js";
+import { Assignment, Command, Redirect } from "./types.js";
+/** `> file`, `2>&1`, `<<< "$str"`, ... The file descriptor must be
+ * attached to the operator (`2>` redirects fd 2; `2 >` is an argument). */
+export declare const redirectParser: Parser<Redirect>;
+/** `name=value`, `name=`, or `name="$x"y` — value is a full word. */
+export declare const assignmentParser: Parser<Assignment>;
+/** Any single command: simple, compound (with trailing redirects), or a
+ * function definition. Declared as a function so the words/lists/commands
+ * module cycle is safe under any import order. */
+export declare function commandParser(input: string): ParserResult<Command>;

package/dist/parsers/bash/commands.js

@@ -0,0 +1,197 @@
+/** Commands: redirects, assignments, simple commands, compound commands,
+ * and function definitions. */
+import { lazy, many, many1, many1WithJoin, map, not, optional, or, peek, seq, } from "../../combinators.js";
+import { char, oneOf, str } from "../../parsers.js";
+import { trace } from "../../trace.js";
+import { failure, success } from "../../types.js";
+import { bashLexemes, groupClose, groupOpen, linebreak, newlineToken, wordBoundary, } from "./lexemes.js";
+import { list0 as list0Import, list1 as list1Import, list1WithEnd as list1WithEndImport, } from "./lists.js";
+import { commandWord as commandWordImport, identifierRun as identifierRunImport, parenBody as parenBodyImport, wordParser as wordParserImport, } from "./words.js";
+const L = bashLexemes;
+// The words/lists/commands modules form an import cycle. Deferring every
+// cross-module reference to parse time (via lazy) keeps the cycle safe
+// regardless of module evaluation order or transform.
+const list0 = lazy(() => list0Import);
+const list1 = lazy(() => list1Import);
+const commandWord = lazy(() => commandWordImport);
+const identifierRun = lazy(() => identifierRunImport);
+const parenBody = lazy(() => parenBodyImport);
+const wordParser = lazy(() => wordParserImport);
+const list1WithEnd = lazy(() => list1WithEndImport);
+// ---------------------------------------------------------------------------
+// Redirects and assignments
+// ---------------------------------------------------------------------------
+// Longest first, so ">>" wins over ">". The bare "<" refuses a following
+// "<" so heredocs (unsupported) stay unparsed rather than half-parsed.
+const redirectOp = or(str("&>>"), str("&>"), str(">>"), str(">|"), str(">&"), str("<<<"), str("<&"), str("<>"), str(">"), seq([str("<"), not(char("<"))], (results) => results[0]));
+const fileDescriptor = many1WithJoin(oneOf("0123456789"));
+/** `> file`, `2>&1`, `<<< "$str"`, ... The file descriptor must be
+ * attached to the operator (`2>` redirects fd 2; `2 >` is an argument). */
+export const redirectParser = trace("bash:redirect", seq([optional(fileDescriptor), L.lexeme(redirectOp), wordParser], (results) => ({
+    tag: "redirect",
+    fd: results[0] === null ? null : parseInt(results[0], 10),
+    op: results[1],
+    target: results[2],
+})));
+/** `name=value`, `name=`, or `name="$x"y` — value is a full word. */
+export const assignmentParser = L.lexeme(trace("bash:assignment", seq([identifierRun, str("="), optional(wordParser)], (results) => ({
+    tag: "assignment",
+    name: results[0],
+    value: results[2],
+}))));
+// ---------------------------------------------------------------------------
+// Simple commands
+// ---------------------------------------------------------------------------
+const prefixItem = or(assignmentParser, redirectParser);
+function buildSimpleCommand(prefix, first, rest) {
+    const assignments = prefix.filter((item) => item.tag === "assignment");
+    const redirects = [
+        ...prefix.filter((item) => item.tag === "redirect"),
+        ...rest.filter((item) => item.tag === "redirect"),
+    ];
+    const words = [
+        ...(first === null ? [] : [first]),
+        ...rest.filter((item) => item.tag === "word"),
+    ];
+    return { tag: "simpleCommand", assignments, words, redirects };
+}
+// "At least one of prefix/word" expressed as the two valid shapes.
+const simpleCommandParser = trace("bash:simpleCommand", or(seq([many(prefixItem), commandWord, many(or(redirectParser, wordParser))], (results) => buildSimpleCommand(results[0], results[1], results[2])), seq([many1(prefixItem)], (results) => buildSimpleCommand(results[0], null, []))));
+// ---------------------------------------------------------------------------
+// Compound commands
+// ---------------------------------------------------------------------------
+const elifClause = seq([L.keyword("elif"), list1, L.keyword("then"), list1], (results) => ({ cond: results[1], thenBody: results[3] }));
+const elseClause = seq([L.keyword("else"), list1], (results) => results[1]);
+const ifParser = seq([
+    L.keyword("if"), list1,
+    L.keyword("then"), list1,
+    many(elifClause),
+    optional(elseClause),
+    L.keyword("fi"),
+], (results) => ({
+    tag: "if",
+    cond: results[1],
+    thenBody: results[3],
+    elifs: results[4],
+    elseBody: results[5],
+    redirects: [],
+}));
+const loopParser = seq([
+    or(L.keyword("while"), L.keyword("until")), list1,
+    L.keyword("do"), list1, L.keyword("done"),
+], (results) => ({
+    tag: "loop",
+    kind: results[0],
+    cond: results[1],
+    body: results[3],
+    redirects: [],
+}));
+const forParser = seq([
+    L.keyword("for"), L.identifier,
+    optional(seq([L.keyword("in"), many(wordParser)], (results) => results[1])),
+    optional(or(L.operator(";"), newlineToken)),
+    linebreak,
+    L.keyword("do"), list1, L.keyword("done"),
+], (results) => ({
+    tag: "for",
+    variable: results[1],
+    words: results[2],
+    body: results[6],
+    redirects: [],
+}));
+// Patterns via explicit seq/many: sepBy1 silently swallows a trailing
+// separator when the next parse fails, which would hide a real error.
+const casePatterns = seq([
+    wordParser,
+    many(seq([L.operator("|"), wordParser], (results) => results[1])),
+], (results) => [results[0], ...results[1]]);
+// Every item needs `;;` (or `;&` / `;;&`) unless `esac` follows directly.
+const caseTerminator = or(seq([or(L.operator(";;&"), L.operator(";;"), L.operator(";&")), linebreak], (results) => results[0]), map(peek(L.keyword("esac")), () => null));
+// Without a leading `(`, a bare `esac` cannot start a pattern — it ends
+// the case statement (bash rejects `case x in esac) ...`).
+const bareEsac = seq([str("esac"), wordBoundary], () => "esac");
+const caseItemStart = or(seq([L.symbol("("), casePatterns], (results) => results[1]), seq([not(bareEsac), casePatterns], (results) => results[1]));
+const caseItemParser = seq([caseItemStart, L.symbol(")"), list0, caseTerminator], (results) => ({
+    patterns: results[0],
+    body: results[2],
+    terminator: results[3],
+}));
+const caseParser = seq([
+    L.keyword("case"), wordParser, L.keyword("in"), linebreak,
+    many(caseItemParser),
+    L.keyword("esac"),
+], (results) => ({
+    tag: "case",
+    subject: results[1],
+    items: results[4],
+    redirects: [],
+}));
+const arithmeticCommand = L.lexeme(seq([str("(("), parenBody, str("))")], (results) => ({
+    tag: "arithmeticCommand",
+    expression: results[1],
+    redirects: [],
+})));
+const subshellParser = seq([L.symbol("("), list1, L.symbol(")")], (results) => ({
+    tag: "subshell",
+    body: results[1],
+    redirects: [],
+}));
+/** Can `}` directly follow this command, as it can in bash? True for a
+ * compound command with no trailing redirects (`{ { echo a; } }`), and
+ * for a function definition whose body qualifies. A redirect re-enters
+ * word context (`{ { cat; } > log }` is rejected by bash), and `(( ))`
+ * does not qualify. */
+function closesGroup(command) {
+    if (command.tag === "functionDef")
+        return closesGroup(command.body);
+    const isCompound = command.tag === "if" ||
+        command.tag === "loop" ||
+        command.tag === "for" ||
+        command.tag === "case" ||
+        command.tag === "subshell" ||
+        command.tag === "group";
+    return isCompound && command.redirects.length === 0;
+}
+function endsAtCommandPosition({ list, endedWithSeparator }) {
+    if (endedWithSeparator)
+        return true;
+    const lastItem = list.items[list.items.length - 1];
+    const andOr = lastItem.command;
+    const lastPipeline = andOr.rest.length > 0 ? andOr.rest[andOr.rest.length - 1].pipeline : andOr.first;
+    return closesGroup(lastPipeline.commands[lastPipeline.commands.length - 1]);
+}
+// `}` is a reserved word, recognized only at command position: the group
+// body must end with a separator or a bare compound command. Without this
+// check, `{ echo a }` would fail OPEN (bash treats that `}` as an
+// argument to echo and rejects the unterminated group).
+const groupParser = (input) => {
+    const result = seq([groupOpen, list1WithEnd, groupClose], (results) => results[1])(input);
+    if (!result.success)
+        return result;
+    if (!endsAtCommandPosition(result.result)) {
+        return failure("expected ; & or newline before }", input);
+    }
+    return success({ tag: "group", body: result.result.list, redirects: [] }, result.rest);
+};
+const compoundParser = or(ifParser, loopParser, forParser, caseParser, arithmeticCommand, subshellParser, groupParser);
+const compoundWithRedirects = seq([compoundParser, many(redirectParser)], (results) => (Object.assign(Object.assign({}, results[0]), { redirects: results[1] })));
+const functionParens = seq([L.symbol("("), L.symbol(")")], () => "()");
+// "Needs `function` or `()`" expressed as the two valid shapes. The body
+// must be a compound command (bash rejects `f() echo hi` and nested
+// definitions like `f() g() { :; }`); trailing redirects are allowed.
+const functionDefParser = or(seq([L.keyword("function"), L.identifier, optional(functionParens), linebreak, compoundWithRedirects], (results) => ({
+    tag: "functionDef",
+    name: results[1],
+    body: results[4],
+})), seq([L.identifier, functionParens, linebreak, compoundWithRedirects], (results) => ({
+    tag: "functionDef",
+    name: results[0],
+    body: results[3],
+})));
+const commandParserImpl = trace("bash:command", or(compoundWithRedirects, functionDefParser, simpleCommandParser));
+/** Any single command: simple, compound (with trailing redirects), or a
+ * function definition. Declared as a function so the words/lists/commands
+ * module cycle is safe under any import order. */
+export function commandParser(input) {
+    return commandParserImpl(input);
+}

package/dist/parsers/bash/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A fail-closed bash parser: a deliberately smaller bash syntax that is
+ * either parsed correctly or rejected with a parse error — never silently
+ * mis-parsed. Intended for contexts where acting on a wrong parse is
+ * worse than rejecting a valid script.
+ *
+ * Soundness comes from two structural rules plus explicit cuts:
+ *
+ * 1. Separators between commands are MANDATORY (`;`, `&`, or newline),
+ *    so text left over by a construct becomes a parse error instead of a
+ *    phantom second command.
+ * 2. No permissive fallbacks: a `$`, backtick, or `{`/`}` that isn't part
+ *    of a supported construct fails the parse instead of degrading to a
+ *    literal.
+ *
+ * Supported: words with single/double quoting, escapes, `$var`, `${...}`,
+ * recursive `$(...)`, `$((...))`; assignments; redirects (fd prefixes,
+ * `2>&1`, `>&2`, `<<<`); pipelines with `!`; `&&`/`||`; `&` background;
+ * `;`/newline separators; comments and line continuations; `if`/`elif`/
+ * `else`, `while`/`until`, `for`, `case`, subshells, `{ }` groups,
+ * `(( ))`, and both function-definition styles.
+ *
+ * Deliberately UNSUPPORTED (valid bash, rejected here — fail closed):
+ * arrays `x=(...)`, append `x+=`, ANSI-C `$'...'` / locale `$"..."`,
+ * backtick substitution (use `$()`), `[[ ]]` (its `]]` delimiter can
+ * appear inside quoted operands, so scanning for it is unsound; `[` is an
+ * ordinary command and still works), brace expansion `{a,b}` and literal
+ * `{`/`}` in words (quote them), bare `$` (write `\$` or '$'), heredocs,
+ * process substitution `<()`, `select`/`coproc`/`time`.
+ *
+ * Kept as RAW TEXT (delimiters are sound, contents are not interpreted):
+ * `${...}` (balanced braces), `$((...))` and `((...))` (balanced parens —
+ * quotes are not delimiters in bash arithmetic).
+ *
+ * Out of scope by design, as in bash's own parser: glob (`*`, `?`) and
+ * tilde expansion happen after parsing; consumers see the literal word
+ * text and decide for themselves.
+ *
+ * For error positions, use the standard tarsec flow:
+ *
+ * ```ts
+ * setInputStr(input);
+ * resetRightmostFailure();
+ * const result = bashParser(input);
+ * if (!result.success) console.log(getErrorMessage());
+ * ```
+ */
+export * from "./types.js";
+export * from "./lexemes.js";
+export * from "./words.js";
+export * from "./commands.js";
+export * from "./lists.js";
+import { Parser } from "../../types.js";
+import { List } from "./types.js";
+/** Parse a whole script (or any command list) to a `List`. Fails unless
+ * the entire input is consumed. */
+export declare const bashParser: Parser<List>;

package/dist/parsers/bash/index.js

@@ -0,0 +1,58 @@
+/**
+ * A fail-closed bash parser: a deliberately smaller bash syntax that is
+ * either parsed correctly or rejected with a parse error — never silently
+ * mis-parsed. Intended for contexts where acting on a wrong parse is
+ * worse than rejecting a valid script.
+ *
+ * Soundness comes from two structural rules plus explicit cuts:
+ *
+ * 1. Separators between commands are MANDATORY (`;`, `&`, or newline),
+ *    so text left over by a construct becomes a parse error instead of a
+ *    phantom second command.
+ * 2. No permissive fallbacks: a `$`, backtick, or `{`/`}` that isn't part
+ *    of a supported construct fails the parse instead of degrading to a
+ *    literal.
+ *
+ * Supported: words with single/double quoting, escapes, `$var`, `${...}`,
+ * recursive `$(...)`, `$((...))`; assignments; redirects (fd prefixes,
+ * `2>&1`, `>&2`, `<<<`); pipelines with `!`; `&&`/`||`; `&` background;
+ * `;`/newline separators; comments and line continuations; `if`/`elif`/
+ * `else`, `while`/`until`, `for`, `case`, subshells, `{ }` groups,
+ * `(( ))`, and both function-definition styles.
+ *
+ * Deliberately UNSUPPORTED (valid bash, rejected here — fail closed):
+ * arrays `x=(...)`, append `x+=`, ANSI-C `$'...'` / locale `$"..."`,
+ * backtick substitution (use `$()`), `[[ ]]` (its `]]` delimiter can
+ * appear inside quoted operands, so scanning for it is unsound; `[` is an
+ * ordinary command and still works), brace expansion `{a,b}` and literal
+ * `{`/`}` in words (quote them), bare `$` (write `\$` or '$'), heredocs,
+ * process substitution `<()`, `select`/`coproc`/`time`.
+ *
+ * Kept as RAW TEXT (delimiters are sound, contents are not interpreted):
+ * `${...}` (balanced braces), `$((...))` and `((...))` (balanced parens —
+ * quotes are not delimiters in bash arithmetic).
+ *
+ * Out of scope by design, as in bash's own parser: glob (`*`, `?`) and
+ * tilde expansion happen after parsing; consumers see the literal word
+ * text and decide for themselves.
+ *
+ * For error positions, use the standard tarsec flow:
+ *
+ * ```ts
+ * setInputStr(input);
+ * resetRightmostFailure();
+ * const result = bashParser(input);
+ * if (!result.success) console.log(getErrorMessage());
+ * ```
+ */
+export * from "./types.js";
+export * from "./lexemes.js";
+export * from "./words.js";
+export * from "./commands.js";
+export * from "./lists.js";
+import { seq } from "../../combinators.js";
+import { eof } from "../../parsers.js";
+import { list0 } from "./lists.js";
+/** Parse a whole script (or any command list) to a `List`. Fails unless
+ * the entire input is consumed. */
+export const bashParser = seq([list0, eof], (results) => results[0]);

package/dist/parsers/bash/lexemes.d.ts

@@ -0,0 +1,27 @@
+import { Parser } from "../../types.js";
+/** Words that are reserved at command position (and rejected as
+ * identifiers). Includes constructs this parser deliberately does not
+ * support — `select`, `coproc`, `time`, `[[ ]]` — so they fail the parse
+ * instead of parsing as ordinary words. */
+export declare const WORD_RESERVED: string[];
+export declare const bashLexemes: import("../../lexeme.js").Lexemes;
+/** Characters that end a word. `{` and `}` are metacharacters here
+ * (unlike bash) because brace expansion is unsupported: a brace can only
+ * be a group delimiter or quoted. */
+export declare const METACHARACTERS = " \t\n|&;()<>{}";
+/** The next character (unconsumed) would end a word, or input is done. */
+export declare const wordBoundary: Parser<string | null>;
+/** A reserved word as a whole token. Order doesn't matter: each
+ * alternative carries its own boundary check, so `do` cannot steal the
+ * front of `done`. */
+export declare const reservedToken: Parser<string>;
+/** `{`, `}`, and `!` must be followed by whitespace. This is stricter
+ * than bash on purpose: `!(` is extglob syntax (unsupported), not
+ * negation. */
+export declare const groupOpen: Parser<string>;
+export declare const groupClose: Parser<string>;
+export declare const bangToken: Parser<string>;
+/** A significant newline, with trailing blanks and comments skipped. */
+export declare const newlineToken: Parser<"\n">;
+/** Zero or more blank (or comment-only) lines. */
+export declare const linebreak: Parser<"\n"[]>;

package/dist/parsers/bash/lexemes.js

@@ -0,0 +1,44 @@
+/** Lexeme layer and shared tokens for the bash grammar. */
+import { many, or, peek, seq } from "../../combinators.js";
+import { makeLexemes } from "../../lexeme.js";
+import { char, eof, oneOf, str } from "../../parsers.js";
+/** Words that are reserved at command position (and rejected as
+ * identifiers). Includes constructs this parser deliberately does not
+ * support — `select`, `coproc`, `time`, `[[ ]]` — so they fail the parse
+ * instead of parsing as ordinary words. */
+export const WORD_RESERVED = [
+    "if", "then", "elif", "else", "fi",
+    "do", "done", "while", "until", "for", "in",
+    "case", "esac", "function",
+    "select", "coproc", "time", "[[", "]]",
+];
+const RESERVED_TOKENS = [...WORD_RESERVED, "{", "}", "!"];
+export const bashLexemes = makeLexemes({
+    // Newlines are command separators, never skippable whitespace.
+    whitespace: " \t",
+    lineComment: "#",
+    lineContinuation: true,
+    operatorChars: "&|;<>",
+    keywords: WORD_RESERVED,
+});
+/** Characters that end a word. `{` and `}` are metacharacters here
+ * (unlike bash) because brace expansion is unsupported: a brace can only
+ * be a group delimiter or quoted. */
+export const METACHARACTERS = " \t\n|&;()<>{}";
+/** The next character (unconsumed) would end a word, or input is done. */
+export const wordBoundary = or(peek(oneOf(METACHARACTERS)), eof);
+/** A reserved word as a whole token. Order doesn't matter: each
+ * alternative carries its own boundary check, so `do` cannot steal the
+ * front of `done`. */
+export const reservedToken = or(...RESERVED_TOKENS.map((word) => seq([str(word), wordBoundary], (results) => results[0])));
+const whitespaceOrEnd = or(peek(oneOf(" \t\n")), eof);
+/** `{`, `}`, and `!` must be followed by whitespace. This is stricter
+ * than bash on purpose: `!(` is extglob syntax (unsupported), not
+ * negation. */
+export const groupOpen = bashLexemes.lexeme(seq([str("{"), whitespaceOrEnd], () => "{"));
+export const groupClose = bashLexemes.lexeme(seq([str("}"), wordBoundary], () => "}"));
+export const bangToken = bashLexemes.lexeme(seq([str("!"), whitespaceOrEnd], () => "!"));
+/** A significant newline, with trailing blanks and comments skipped. */
+export const newlineToken = bashLexemes.lexeme(char("\n"));
+/** Zero or more blank (or comment-only) lines. */
+export const linebreak = many(newlineToken);

package/dist/parsers/bash/lists.d.ts

@@ -0,0 +1,18 @@
+import { ParserResult } from "../../types.js";
+import { List } from "./types.js";
+/** A parsed list plus whether it ended with an explicit separator —
+ * group parsing needs this to decide whether `}` is at command position. */
+export type ListWithEnd = {
+    list: List;
+    endedWithSeparator: boolean;
+};
+/** A possibly-empty command list. Empty lists are only legal where bash
+ * allows them: the top level, `$()`, and case-item bodies. Declared as a
+ * function so the words/lists/commands module cycle is safe under any
+ * import order. */
+export declare function list0(input: string): ParserResult<List>;
+/** A command list with at least one command — the body of every compound
+ * command, subshell, and group. */
+export declare function list1(input: string): ParserResult<List>;
+/** `list1`, but also reporting whether it ended with a separator. */
+export declare function list1WithEnd(input: string): ParserResult<ListWithEnd>;