@starpak/lang 0.0.0-stage → 0.1.3

package/src/ast.ts

@@ -0,0 +1,467 @@
+/**
+ * Spak Lang - AST definitions
+ *
+ * Every node is a discriminated union member with a `kind` field and a
+ * 1-based `loc` position pointing at the first token of the node.
+ */
+
+export interface Position {
+  line: number
+  column: number
+}
+
+export interface NodeBase {
+  loc: Position
+}
+
+/* ------------------------------------------------------------------ */
+/* Types                                                               */
+/* ------------------------------------------------------------------ */
+
+export type TypeAnn =
+  | NamedType
+  | ArrayType
+  | DictType
+  | RecordType
+  | UnionType
+  | FnType
+  | OptionalType
+
+export interface NamedType extends NodeBase {
+  kind: 'named'
+  name: string
+}
+
+export interface ArrayType extends NodeBase {
+  kind: 'array'
+  element: TypeAnn
+}
+
+/** `{ string: number }` */
+export interface DictType extends NodeBase {
+  kind: 'dict'
+  key: TypeAnn
+  value: TypeAnn
+}
+
+/** `{ x: number, y: number }` */
+export interface RecordType extends NodeBase {
+  kind: 'record'
+  fields: TypeField[]
+}
+
+export interface TypeField {
+  name: string
+  type: TypeAnn
+}
+
+export interface UnionType extends NodeBase {
+  kind: 'union'
+  types: TypeAnn[]
+}
+
+export interface FnType extends NodeBase {
+  kind: 'fn'
+  params: TypeAnn[]
+  returns: TypeAnn
+}
+
+export interface OptionalType extends NodeBase {
+  kind: 'optional'
+  type: TypeAnn
+  /** Alias of `type`, kept for consumers that expect the `inner` spelling. */
+  inner?: TypeAnn
+}
+
+/* ------------------------------------------------------------------ */
+/* Common pieces                                                       */
+/* ------------------------------------------------------------------ */
+
+export interface Decorator extends NodeBase {
+  kind: 'Decorator'
+  name: string
+  args: Expr[]
+}
+
+export interface Param {
+  name: string
+  type?: TypeAnn
+  default?: Expr
+  rest?: boolean
+}
+
+export interface VarName {
+  name: string
+  type?: TypeAnn
+}
+
+export interface ElifBranch {
+  cond: Expr
+  body: Block
+}
+
+export interface MatchArm extends NodeBase {
+  patterns: Expr[]
+  guard?: Expr
+  body: Block
+}
+
+export interface ImportClause {
+  name: string
+  alias?: string
+}
+
+export interface TableField {
+  key?: Expr
+  value: Expr
+}
+
+/** Entry of a table destructuring pattern: `{ x }`, `{ a = alias }`, `{ a = 1 }`. */
+export interface TablePatternEntry {
+  /** Key read from the source table. */
+  key: string
+  /** Variable the value is bound to when renamed (`{ a = first }`), else `key`. */
+  target?: string
+  /** Default value used when the key is absent. */
+  default?: Expr
+}
+
+/** Destructuring pattern, only valid as an assignment target. */
+export type Pattern = TablePattern | ArrayPattern
+
+export interface TablePattern extends NodeBase {
+  kind: 'TablePattern'
+  entries: TablePatternEntry[]
+}
+
+export interface ArrayPattern extends NodeBase {
+  kind: 'ArrayPattern'
+  elements: string[]
+}
+
+/* ------------------------------------------------------------------ */
+/* Statements                                                          */
+/* ------------------------------------------------------------------ */
+
+export type Statement =
+  | VarDecl
+  | Assign
+  | FnDecl
+  | ClassDecl
+  | IfStmt
+  | UnlessStmt
+  | WhileStmt
+  | RepeatStmt
+  | ForNumeric
+  | ForIn
+  | ReturnStmt
+  | BreakStmt
+  | ContinueStmt
+  | MatchStmt
+  | TryStmt
+  | ImportDecl
+  | ExportDecl
+  | ExportDefault
+  | TypeAliasDecl
+  | ThrowStmt
+  | SpawnStmt
+  | ExprStmt
+
+export interface Program extends NodeBase {
+  kind: 'Program'
+  body: Statement[]
+}
+
+export interface Block extends NodeBase {
+  kind: 'Block'
+  body: Statement[]
+}
+
+export interface VarDecl extends NodeBase {
+  kind: 'VarDecl'
+  names: VarName[]
+  values: Expr[]
+  scope: 'local' | 'global' | 'const'
+  export?: boolean
+  /** Doc comment (`---`) directly above the declaration. */
+  doc?: string
+  /** Member decorators, only used inside a class body. */
+  decorators?: Decorator[]
+}
+
+export interface Assign extends NodeBase {
+  kind: 'Assign'
+  targets: Array<Expr | Pattern>
+  values: Expr[]
+}
+
+export interface FnDecl extends NodeBase {
+  kind: 'FnDecl'
+  name: string
+  /** Receiver of `fn Point:len()`, i.e. `Point`. */
+  receiver?: string
+  params: Param[]
+  returnType?: TypeAnn
+  body?: Block
+  exprBody?: Expr
+  isMethod: boolean
+  decorators: Decorator[]
+  async?: boolean
+  /** Doc comment (`---`) directly above the declaration. */
+  doc?: string
+}
+
+export interface ClassDecl extends NodeBase {
+  kind: 'ClassDecl'
+  name: string
+  superClass?: string
+  members: Array<FnDecl | VarDecl>
+  decorators: Decorator[]
+  /** Doc comment (`---`) directly above the declaration. */
+  doc?: string
+}
+
+export interface IfStmt extends NodeBase {
+  kind: 'IfStmt'
+  cond: Expr
+  then: Block
+  elifs: ElifBranch[]
+  else?: Block
+}
+
+export interface UnlessStmt extends NodeBase {
+  kind: 'UnlessStmt'
+  cond: Expr
+  body: Block
+}
+
+export interface WhileStmt extends NodeBase {
+  kind: 'WhileStmt'
+  cond: Expr
+  body: Block
+}
+
+export interface RepeatStmt extends NodeBase {
+  kind: 'RepeatStmt'
+  body: Block
+  cond: Expr
+}
+
+export interface ForNumeric extends NodeBase {
+  kind: 'ForNumeric'
+  varName: string
+  from: Expr
+  to: Expr
+  step?: Expr
+  inclusive: boolean
+  body: Block
+}
+
+export interface ForIn extends NodeBase {
+  kind: 'ForIn'
+  vars: string[]
+  iter: Expr
+  body: Block
+}
+
+export interface ReturnStmt extends NodeBase {
+  kind: 'ReturnStmt'
+  values: Expr[]
+}
+
+export interface BreakStmt extends NodeBase {
+  kind: 'BreakStmt'
+}
+
+export interface ContinueStmt extends NodeBase {
+  kind: 'ContinueStmt'
+}
+
+export interface MatchStmt extends NodeBase {
+  kind: 'MatchStmt'
+  subject: Expr
+  arms: MatchArm[]
+  elseBody?: Block
+}
+
+export interface TryStmt extends NodeBase {
+  kind: 'TryStmt'
+  body: Block
+  catchVar?: string
+  catchType?: TypeAnn
+  catchBody?: Block
+  finallyBody?: Block
+}
+
+/** Surface form of an import; keeps `import { a }` distinct from `import a`. */
+export type ImportForm = 'named' | 'default' | 'namespace' | 'side-effect'
+
+export interface ImportDecl extends NodeBase {
+  kind: 'ImportDecl'
+  clauses: ImportClause[]
+  source: string
+  /**
+   * Parsed surface form. Older hand-built ASTs may omit it; the emitter then
+   * falls back to inferring the form from the clauses.
+   */
+  form?: ImportForm
+  /** Doc comment (`---`) directly above the declaration. */
+  doc?: string
+}
+
+export interface ExportDecl extends NodeBase {
+  kind: 'ExportDecl'
+  declaration: Statement
+  /** Doc comment (`---`) directly above the declaration. */
+  doc?: string
+}
+
+export interface ExportDefault extends NodeBase {
+  kind: 'ExportDefault'
+  expr: Expr
+}
+
+export interface TypeAliasDecl extends NodeBase {
+  kind: 'TypeAliasDecl'
+  name: string
+  type: TypeAnn
+  /** Doc comment (`---`) directly above the declaration. */
+  doc?: string
+}
+
+export interface ThrowStmt extends NodeBase {
+  kind: 'ThrowStmt'
+  value: Expr
+}
+
+export interface SpawnStmt extends NodeBase {
+  kind: 'SpawnStmt'
+  value: Expr
+}
+
+export interface ExprStmt extends NodeBase {
+  kind: 'ExprStmt'
+  expr: Expr
+}
+
+/* ------------------------------------------------------------------ */
+/* Expressions                                                         */
+/* ------------------------------------------------------------------ */
+
+export type Expr =
+  | NumberLit
+  | StringLit
+  | BoolLit
+  | NilLit
+  | Ident
+  | SelfExpr
+  | Member
+  | Index
+  | Call
+  | Binary
+  | Unary
+  | Table
+  | FunctionExpr
+  | Range
+  | AwaitExpr
+  | Spread
+
+export interface NumberLit extends NodeBase {
+  kind: 'NumberLit'
+  value: number
+}
+
+export interface StringLit extends NodeBase {
+  kind: 'StringLit'
+  value: string
+  multiline?: boolean
+  fstring?: boolean
+  /** Interpolated segments of an f-string; plain strings and parsed expressions. */
+  parts?: Array<string | Expr>
+}
+
+export interface BoolLit extends NodeBase {
+  kind: 'BoolLit'
+  value: boolean
+}
+
+export interface NilLit extends NodeBase {
+  kind: 'NilLit'
+}
+
+export interface Ident extends NodeBase {
+  kind: 'Ident'
+  name: string
+}
+
+export interface SelfExpr extends NodeBase {
+  kind: 'SelfExpr'
+}
+
+export interface Member extends NodeBase {
+  kind: 'Member'
+  object: Expr
+  property: string
+  optional?: boolean
+}
+
+export interface Index extends NodeBase {
+  kind: 'Index'
+  object: Expr
+  index: Expr
+  isRange?: boolean
+}
+
+export interface Call extends NodeBase {
+  kind: 'Call'
+  callee: Expr
+  args: Expr[]
+  isMethod?: boolean
+}
+
+export interface Binary extends NodeBase {
+  kind: 'Binary'
+  op: string
+  left: Expr
+  right: Expr
+}
+
+export interface Unary extends NodeBase {
+  kind: 'Unary'
+  op: string
+  argument: Expr
+}
+
+export interface Table extends NodeBase {
+  kind: 'Table'
+  fields: TableField[]
+}
+
+export interface FunctionExpr extends NodeBase {
+  kind: 'FunctionExpr'
+  params: Param[]
+  returnType?: TypeAnn
+  body?: Block
+  exprBody?: Expr
+  async?: boolean
+}
+
+export interface Range extends NodeBase {
+  kind: 'Range'
+  from: Expr
+  to: Expr
+  inclusive: boolean
+}
+
+export interface AwaitExpr extends NodeBase {
+  kind: 'AwaitExpr'
+  argument: Expr
+}
+
+/** `f(a, ...rest, ...)`; `argument` is absent for a bare spread. */
+export interface Spread extends NodeBase {
+  kind: 'Spread'
+  argument?: Expr
+}
+
+export type Node = Program | Statement | Expr | Decorator | Pattern