#syntax package

#Key types and functions

#Quick start

///|
test {
  let pos = @errors.Position::new("<test>", 1, 1)
  let stmt = @syntax.Stmt::SPass(pos)
  let file = @syntax.File::new("<test>", [stmt])
  assert_eq(file.path(), "<test>")
  assert_eq(file.stmts().length(), 1)
}

///|
test {
  let pos = @errors.Position::new("<e>", 1, 1)
  let lhs = @syntax.Expr::EIdent("x", pos)
  let rhs = @syntax.Expr::EIdent("y", pos)
  let expr = @syntax.Expr::EBinary(lhs, @syntax.BinaryOp::OpAdd, rhs, pos)
  let names : Array[String] = []
  @syntax.walk_expr(expr, fn(node) {
    match node {
      Some(@syntax.Node::NExpr(@syntax.Expr::EIdent(name, _))) =>
        names.push(name)
      _ => ()
    }
    true
  })
  assert_true(names == ["x", "y"])
}

#Error-position anchoring policy

#Position accessors

• syntax.start(e) — walks into EBinary, ECall, ESlice, EIndex, and EDot sub-expressions to reach the leftmost token of a compound expression. Use this whenever the error should point at the beginning of a possibly-compound expression (LHS of assignments, misplaced arguments).
• expr_pos(e) — returns the position stored in the node's own slot (operator, opening bracket, or other delimiter). Use this when the error is about the operator or delimiter itself rather than an operand.
• Parser::scanner_error(msg) — uses scanner.position(), which is one past the current token. Use this for unexpected-token parse errors that must match starlark-go's scanner cursor convention.
• set_pos(colon) in internal/compile — dict-literal and dict-comprehension key errors use a different mechanism: the compiler calls set_pos(colon_pos) before emitting the dict-insertion opcode (SetDictUniq / SetDict), recording the colon as the error anchor. The error itself is raised at runtime by the eval package using that recorded position. Both EDict pairs and EDictComp store a colon_pos; compile uses it in both code paths.

#Adding a new anchoring site

1. Identify which rule class the new error falls into (table above).
2. Choose the matching mechanism (syntax.start, expr_pos, scanner_error, or set_pos in compile).
3. Add a conformance test that checks the reported column against the expected source position so regressions are caught automatically.

#API reference

#Functions

#File

#AST node enums

///|
pub(all) enum Expr {
  EIdent(String, @errors.Position)
  ELiteral(LiteralVal, @errors.Position)
  EUnary(UnaryOp, Expr, @errors.Position)
  EBinary(Expr, BinaryOp, Expr, @errors.Position)
  ECond(Expr, Expr, Expr, @errors.Position) // cond, then, else (surface: then if cond else else)
  EIndex(Expr, Expr, @errors.Position) // a[i]
  ESlice(Expr, Expr?, Expr?, Expr?, @errors.Position) // a[start:end:step]
  EDot(Expr, String, @errors.Position) // x.attr
  ECall(Expr, Array[Arg], @errors.Position) // f(args…)
  EList(Array[Expr], @errors.Position)
  ETuple(Array[Expr], @errors.Position)
  EDict(Array[(Expr, Expr, @errors.Position)], @errors.Position) // (key, val, colon_pos)
  ESet(Array[Expr], @errors.Position)
  ELambda(Array[Param], Expr, @errors.Position)
  EListComp(Expr, Array[CompClause], @errors.Position)
  ESetComp(Expr, Array[CompClause], @errors.Position)
  EDictComp(Expr, Expr, Array[CompClause], @errors.Position, @errors.Position) // (key, val, clauses, colon_pos, brace_pos)
}

///|
pub(all) enum Stmt {
  SExpr(Expr)
  SAssign(Expr, Expr, @errors.Position)
  SAugAssign(Expr, AugOp, Expr, @errors.Position)
  SIf(Expr, Array[Stmt], Array[Stmt], @errors.Position)
  SFor(Expr, Expr, Array[Stmt], @errors.Position)
  SWhile(Expr, Array[Stmt], @errors.Position)
  SDef(String, Array[Param], Array[Stmt], @errors.Position)
  SReturn(Expr?, @errors.Position)
  SBreak(@errors.Position)
  SContinue(@errors.Position)
  SPass(@errors.Position)
  SLoad(String, Array[(String, String, @errors.Position)], @errors.Position)
}

///|
pub(all) enum Param {
  ParamIdent(String, @errors.Position) // x
  ParamDefault(String, Expr, @errors.Position) // x=expr
  ParamStarBare(@errors.Position) // *
  ParamStarIdent(String, @errors.Position) // *args
  ParamKwIdent(String, @errors.Position) // **kwargs
}

///|
pub(all) enum Arg {
  ArgPos(Expr) // positional
  ArgKw(String, Expr, @errors.Position) // name=expr
  ArgStarArgs(Expr) // *args
  ArgKwArgs(Expr) // **kwargs
}

///|
pub(all) enum CompClause {
  ClauseFor(Expr, Expr, @errors.Position) // for target in iterable
  ClauseIf(Expr, @errors.Position) // if guard
}

///|
pub(all) enum LiteralVal {
  LitNone
  LitBool(Bool)
  LitInt(BigInt)
  LitFloat(Double)
  LitString(String)
  LitBytes(Bytes)
}

///|
pub(all) enum BinaryOp {
  OpAdd
  OpSub
  OpMul
  OpDiv
  OpFloorDiv
  OpMod
  OpBitAnd
  OpBitOr
  OpBitXor
  OpLShift
  OpRShift
  OpEq
  OpNe
  OpLt
  OpLe
  OpGt
  OpGe
  OpIn
  OpNotIn
  OpAnd
  OpOr
}

///|
pub(all) enum UnaryOp {
  OpPlus
  OpMinus
  OpBitNot
  OpNot
}

///|
pub(all) enum AugOp {
  AugAdd
  AugSub
  AugMul
  AugDiv
  AugFloorDiv
  AugMod
  AugBitAnd
  AugBitOr
  AugBitXor
  AugLShift
  AugRShift
}

// Visitor wrapper passed to walk_*; one variant per node kind.

///|
pub(all) enum Node {
  NFile(File)
  NStmt(Stmt)
  NExpr(Expr)
  NParam(Param)
  NArg(Arg)
  NCompClause(CompClause)
}

#walk_file example

///|
test {
  let pos = @errors.Position::new("<walk>", 1, 1)
  let lhs = @syntax.Expr::EIdent("x", pos)
  let rhs = @syntax.Expr::EIdent("y", pos)
  let expr = @syntax.Expr::EBinary(lhs, @syntax.BinaryOp::OpAdd, rhs, pos)
  let stmt = @syntax.Stmt::SExpr(expr)
  let file = @syntax.File::new("<walk>", [stmt])
  let idents : Array[String] = []
  @syntax.walk_file(file, fn(node) {
    match node {
      Some(@syntax.Node::NExpr(@syntax.Expr::EIdent(name, _))) =>
        idents.push(name)
      _ => ()
    }
    true
  })
  assert_true(idents.contains("x"))
  assert_true(idents.contains("y"))
}

#expr_pos example

///|
test {
  let pos = @errors.Position::new("<expr>", 3, 5)
  let expr = @syntax.Expr::EIdent("a", pos)
  let got = @syntax.expr_pos(expr)
  assert_eq(got.filename(), "<expr>")
  assert_eq(got.line(), 3)
}