@taliesinb/mash 0.0.0-stage → 0.1.0

package/src/parser/ast.ts

@@ -0,0 +1,472 @@
+/**
+ * The mash AST. Every node carries a numeric `id` (unique within one parse,
+ * assigned in source order) and a `span` of UTF-16 offsets into the parsed
+ * source, so runtime trace events, static-analysis findings and UI
+ * highlighting can all refer to exact source ranges.
+ *
+ * Design notes:
+ * - Trivial wrappers are collapsed: a `Pipeline` node exists only for two or
+ *   more stages (or a negated / timed one), an `AndOr` only for two or more
+ *   pipelines. A statement's `command` may therefore be any `Command`.
+ * - Redirections live on the command they apply to (simple or compound), as
+ *   in the bash grammar.
+ * - Words keep their quoting structure (`WordPart`s) so expansion, globbing
+ *   and static analysis can tell quoted from unquoted text.
+ */
+
+export interface Span {
+  /** Inclusive start offset into the source. */
+  start: number
+  /** Exclusive end offset into the source. */
+  end: number
+}
+
+interface NodeBase {
+  id: number
+  span: Span
+}
+
+// ---------------------------------------------------------------------------
+// Script and statements
+// ---------------------------------------------------------------------------
+
+export interface Script extends NodeBase {
+  type: 'Script'
+  body: Stmt[]
+  /**
+   * With `parse(src, { partial: true })`: the syntax error that stopped
+   * parsing. `body` then holds the complete statements on lines before it —
+   * what bash, reading line by line, would run before reporting the error.
+   */
+  error?: import('./parser.ts').ParseError
+  /**
+   * Comments in source order (`#` to end of line, without the newline). Not
+   * part of the program; kept for the pretty-printer. Comments inside
+   * backquotes have approximate spans.
+   */
+  comments?: Comment[]
+}
+
+export interface Comment {
+  span: Span
+  text: string
+}
+
+/** One list element, terminated by `;`, `&`, a newline, or the end of its list. */
+export interface Stmt extends NodeBase {
+  type: 'Stmt'
+  command: Command
+  /** Terminated by `&`: run asynchronously. */
+  background: boolean
+}
+
+export type Command =
+  | SimpleCommand
+  | Pipeline
+  | AndOr
+  | Subshell
+  | Group
+  | If
+  | Loop
+  | For
+  | ArithFor
+  | Select
+  | Case
+  | FunctionDef
+  | ArithCommand
+  | CondCommand
+
+export type CompoundCommand = Subshell | Group | If | Loop | For | ArithFor | Select | Case | ArithCommand | CondCommand
+
+export interface Pipeline extends NodeBase {
+  type: 'Pipeline'
+  stages: Command[]
+  /** `pipeStderr[i]`: the pipe after stage i is `|&`. Length `stages.length - 1`. */
+  pipeStderr: boolean[]
+  /** Prefixed by `!`. */
+  negated: boolean
+  /** Prefixed by the `time` keyword. */
+  timed: boolean
+}
+
+export interface AndOr extends NodeBase {
+  type: 'AndOr'
+  /** Two or more items. */
+  items: Command[]
+  /** `ops[i]` joins `items[i]` and `items[i+1]`. */
+  ops: ('&&' | '||')[]
+}
+
+export interface SimpleCommand extends NodeBase {
+  type: 'SimpleCommand'
+  /** Prefix assignments (`A=1 B=2 cmd`), or a bare assignment statement. */
+  assigns: Assign[]
+  /**
+   * Command name and arguments. `Assign` entries appear only after a literal
+   * declaration builtin (`declare`, `local`, `export`, `readonly`, `typeset`),
+   * e.g. `local -a xs=(1 2)`.
+   */
+  words: (Word | Assign)[]
+  redirs: Redirect[]
+}
+
+// ---------------------------------------------------------------------------
+// Compound commands
+// ---------------------------------------------------------------------------
+
+export interface Subshell extends NodeBase {
+  type: 'Subshell'
+  body: Stmt[]
+  redirs: Redirect[]
+}
+
+export interface Group extends NodeBase {
+  type: 'Group'
+  body: Stmt[]
+  redirs: Redirect[]
+}
+
+export interface IfClause {
+  cond: Stmt[]
+  body: Stmt[]
+}
+
+export interface If extends NodeBase {
+  type: 'If'
+  clauses: IfClause[]
+  elseBody: Stmt[] | null
+  redirs: Redirect[]
+}
+
+export interface Loop extends NodeBase {
+  type: 'Loop'
+  kind: 'while' | 'until'
+  cond: Stmt[]
+  body: Stmt[]
+  redirs: Redirect[]
+}
+
+export interface For extends NodeBase {
+  type: 'For'
+  variable: string
+  /** `null` when the `in` clause is absent (iterate over "$@"). */
+  items: Word[] | null
+  body: Stmt[]
+  redirs: Redirect[]
+}
+
+export interface ArithFor extends NodeBase {
+  type: 'ArithFor'
+  init: ArithExpr | null
+  cond: ArithExpr | null
+  step: ArithExpr | null
+  body: Stmt[]
+  redirs: Redirect[]
+}
+
+export interface Select extends NodeBase {
+  type: 'Select'
+  variable: string
+  items: Word[] | null
+  body: Stmt[]
+  redirs: Redirect[]
+}
+
+export interface CaseItem extends NodeBase {
+  type: 'CaseItem'
+  patterns: Word[]
+  body: Stmt[]
+  /** `;;` stop, `;&` fall through, `;;&` test the next patterns. */
+  terminator: ';;' | ';&' | ';;&'
+}
+
+export interface Case extends NodeBase {
+  type: 'Case'
+  word: Word
+  items: CaseItem[]
+  redirs: Redirect[]
+}
+
+export interface FunctionDef extends NodeBase {
+  type: 'FunctionDef'
+  name: string
+  body: CompoundCommand
+}
+
+export interface ArithCommand extends NodeBase {
+  type: 'ArithCommand'
+  expr: ArithExpr
+  redirs: Redirect[]
+}
+
+export interface CondCommand extends NodeBase {
+  type: 'CondCommand'
+  expr: CondExpr
+  redirs: Redirect[]
+}
+
+// ---------------------------------------------------------------------------
+// Assignments and redirections
+// ---------------------------------------------------------------------------
+
+export interface ArrayElem {
+  /** `[key]=value` form; key is a word (assoc) or arithmetic text (indexed), resolved at runtime. */
+  index: Word | null
+  value: Word
+}
+
+export interface ArrayLiteral extends NodeBase {
+  type: 'ArrayLiteral'
+  elems: ArrayElem[]
+}
+
+export interface Assign extends NodeBase {
+  type: 'Assign'
+  name: string
+  /** `name[index]=...`; the raw subscript as a word (expanded at runtime). */
+  index: Word | null
+  /** `+=` */
+  append: boolean
+  /** `null` for `name=` with nothing after (empty string) or for bare `declare name`. */
+  value: Word | ArrayLiteral | null
+}
+
+export type RedirectOp =
+  | '<' | '>' | '>>' | '>|' | '<>'
+  | '<&' | '>&'
+  | '&>' | '&>>'
+  | '<<' | '<<-' | '<<<'
+
+export interface HereDoc {
+  delimiter: string
+  /** The delimiter was quoted: the body is literal (no expansions). */
+  quoted: boolean
+  /** The body, as a word. For unquoted delimiters it carries expansions. */
+  body: Word
+}
+
+export interface Redirect extends NodeBase {
+  type: 'Redirect'
+  op: RedirectOp
+  /** Explicit fd number (`2>`), or null for the operator's default. */
+  fd: number | null
+  /** `{name}>file`: allocate an fd and store it in variable `name`. */
+  fdVar: string | null
+  /** The file, fd number (`>&2`), `-` (close), or here-string word. For heredocs, the delimiter word. */
+  target: Word
+  heredoc: HereDoc | null
+}
+
+// ---------------------------------------------------------------------------
+// Words
+// ---------------------------------------------------------------------------
+
+export interface Word extends NodeBase {
+  type: 'Word'
+  parts: WordPart[]
+}
+
+export type WordPart =
+  | Lit
+  | SglQuoted
+  | Escaped
+  | DblQuoted
+  | ParamExp
+  | CmdSubst
+  | ArithExp
+  | ProcSubst
+
+/** Unquoted literal text. Glob, brace and tilde expansion apply to it. */
+export interface Lit extends NodeBase {
+  type: 'Lit'
+  value: string
+}
+
+/** `'...'` or, with `ansi`, `$'...'` (value already decoded). */
+export interface SglQuoted extends NodeBase {
+  type: 'SglQuoted'
+  value: string
+  ansi: boolean
+}
+
+/** A backslash-escaped character outside double quotes (`\*`). */
+export interface Escaped extends NodeBase {
+  type: 'Escaped'
+  value: string
+}
+
+/** `"..."`: inner parts are Lit (quoted text), ParamExp, CmdSubst, ArithExp. */
+export interface DblQuoted extends NodeBase {
+  type: 'DblQuoted'
+  parts: WordPart[]
+  /** `$"..."` locale string (treated as plain double quotes). */
+  locale: boolean
+}
+
+export type ParamOp =
+  | { kind: 'default' | 'assign' | 'error' | 'alternative'; colon: boolean; word: Word | null }
+  | { kind: 'removePrefix' | 'removeSuffix'; longest: boolean; pattern: Word }
+  | { kind: 'replace'; mode: 'first' | 'all' | 'prefix' | 'suffix'; pattern: Word; replacement: Word | null }
+  | { kind: 'case'; upper: boolean; all: boolean; pattern: Word | null }
+  | { kind: 'substring'; offset: ArithExpr; length: ArithExpr | null }
+  | { kind: 'transform'; operator: string }
+
+export interface ParamExp extends NodeBase {
+  type: 'ParamExp'
+  /** `$x` (true) vs `${x}` (false). */
+  short: boolean
+  /** Variable name, positional digit(s), or special parameter (`@ * # ? - $ ! 0`). */
+  name: string
+  /** `${a[i]}`: subscript word; `@`/`*` subscripts are represented literally. */
+  index: Word | null
+  /** `${#x}` */
+  length: boolean
+  /** `${!x}` indirection; with index `@`/`*` it means "keys of array". */
+  indirect: boolean
+  /** `${!prefix*}` / `${!prefix@}`: names of variables with this prefix. */
+  prefixNames: '*' | '@' | null
+  op: ParamOp | null
+}
+
+export interface CmdSubst extends NodeBase {
+  type: 'CmdSubst'
+  body: Stmt[]
+  backquote: boolean
+}
+
+export interface ArithExp extends NodeBase {
+  type: 'ArithExp'
+  expr: ArithExpr
+}
+
+export interface ProcSubst extends NodeBase {
+  type: 'ProcSubst'
+  direction: '<' | '>'
+  body: Stmt[]
+}
+
+// ---------------------------------------------------------------------------
+// Arithmetic
+// ---------------------------------------------------------------------------
+
+export type ArithExpr =
+  | ArithNum
+  | ArithVar
+  | ArithWord
+  | ArithUnary
+  | ArithBinary
+  | ArithAssign
+  | ArithTernary
+  | ArithIncDec
+  | ArithGroup
+
+export interface ArithNum extends NodeBase {
+  type: 'ArithNum'
+  /** Source text (`0x1f`, `8#17`, `42`). */
+  text: string
+}
+
+export interface ArithVar extends NodeBase {
+  type: 'ArithVar'
+  name: string
+  index: ArithExpr | null
+}
+
+/** A `$`-expansion inside arithmetic; bash expands it textually before evaluation. */
+export interface ArithWord extends NodeBase {
+  type: 'ArithWord'
+  word: Word
+}
+
+export interface ArithUnary extends NodeBase {
+  type: 'ArithUnary'
+  op: '-' | '+' | '!' | '~'
+  operand: ArithExpr
+}
+
+export type ArithBinaryOp =
+  | '+' | '-' | '*' | '/' | '%' | '**'
+  | '<<' | '>>' | '&' | '|' | '^'
+  | '<' | '>' | '<=' | '>=' | '==' | '!='
+  | '&&' | '||' | ','
+
+export interface ArithBinary extends NodeBase {
+  type: 'ArithBinary'
+  op: ArithBinaryOp
+  left: ArithExpr
+  right: ArithExpr
+}
+
+export interface ArithAssign extends NodeBase {
+  type: 'ArithAssign'
+  op: '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '<<=' | '>>=' | '&=' | '|=' | '^='
+  target: ArithVar
+  value: ArithExpr
+}
+
+export interface ArithTernary extends NodeBase {
+  type: 'ArithTernary'
+  cond: ArithExpr
+  then: ArithExpr
+  else: ArithExpr
+}
+
+export interface ArithIncDec extends NodeBase {
+  type: 'ArithIncDec'
+  op: '++' | '--'
+  prefix: boolean
+  target: ArithVar
+}
+
+export interface ArithGroup extends NodeBase {
+  type: 'ArithGroup'
+  expr: ArithExpr
+}
+
+// ---------------------------------------------------------------------------
+// [[ conditional expressions ]]
+// ---------------------------------------------------------------------------
+
+export type CondExpr = CondWord | CondUnary | CondBinary | CondNot | CondAndOr | CondGroup
+
+export interface CondWord extends NodeBase {
+  type: 'CondWord'
+  word: Word
+}
+
+export interface CondUnary extends NodeBase {
+  type: 'CondUnary'
+  /** `-f`, `-d`, `-z`, `-n`, `-v`, ... */
+  op: string
+  operand: Word
+}
+
+export interface CondBinary extends NodeBase {
+  type: 'CondBinary'
+  /** `==`, `=`, `!=`, `=~`, `<`, `>`, `-eq`, `-nt`, ... */
+  op: string
+  left: Word
+  right: Word
+}
+
+export interface CondNot extends NodeBase {
+  type: 'CondNot'
+  operand: CondExpr
+}
+
+export interface CondAndOr extends NodeBase {
+  type: 'CondAndOr'
+  op: '&&' | '||'
+  left: CondExpr
+  right: CondExpr
+}
+
+export interface CondGroup extends NodeBase {
+  type: 'CondGroup'
+  expr: CondExpr
+}
+
+export type Node =
+  | Script | Stmt | Command | CaseItem | Assign | ArrayLiteral | Redirect | Word | WordPart | ArithExpr | CondExpr
+
+export const DECL_BUILTINS: ReadonlySet<string> = new Set(['declare', 'typeset', 'local', 'export', 'readonly'])