ast

Documentation

Overview

Package ast turns tq source into the typed, immutable program AST. It is the covered seam over the lifted ANTLR parser in src/grammar/tq: a custom error listener converts every lexer/parser report into the constants.ErrSyntax sentinel (line/column via With), and the parse-tree walk produces plain value types — a Program of Stages whose embedded expressions keep their ORIGINAL SOURCE TEXT verbatim, because the plan layer rewrites column references by token-span splicing, never by pretty-printing.

Index

• type Assignment
• type Column
  • func ColumnOf(content ColumnContent) Column
• type ColumnContent
• type ColumnSpan
• type Expr
• type ExprInfo
  • func ParseExprInfo(src ExprText) (ExprInfo, error)
• type ExprText
• type Program
  • func ParseProgram(src ProgramText) (Program, error)
• type ProgramText
• type RenamePair
• type SortKey
• type Span
• type Stage
• type Verb

Types

type Assignment

type Assignment struct {
	Name string
	Expr Expr
}

Assignment is one `name = expr` (derive or group aggregate). The name is introduced verbatim — bracket content included — never a positional index: per SPECIFICATION §4 a digits-only name is an (unusual) header name, which stays reachable by position or a later rename.

type Column

type Column struct {
	Name    string
	Index   int
	IsIndex bool
}

Column is one column reference: a 1-based index when IsIndex (digits-only content, SPECIFICATION §4), otherwise a header name. Name always keeps the raw content so error messages can quote what the author wrote.

func ColumnOf

func ColumnOf(content ColumnContent) Column

ColumnOf classifies bracket-free reference content per SPECIFICATION §4: digits-only content is a 1-based column index, anything else a header name. An index too large for int keeps IsIndex with Index 0, which can never resolve (indexes are 1-based), so it surfaces as ErrUnknownColumn at plan.

type ColumnContent

type ColumnContent string

ColumnContent is the text of a column reference without its brackets: the content between `[` and `]`, or a bare stage-position name or integer.

type ColumnSpan

type ColumnSpan struct {
	Col  Column
	Span Span
}

ColumnSpan is one column reference inside an expression: the classified column and the exact span of its `[...]` token, ready for splicing.

type Expr

type Expr struct {
	Src ExprText
}

Expr is one embedded expression, held as its original source text. Column spans and cell-reference rejection are recovered at plan time by re-parsing the text (ParseExprInfo), so parsed and builder-built programs are identical values.

type ExprInfo

type ExprInfo struct {
	Cols    []ColumnSpan
	CellRef string
	Strings []Span
}

ExprInfo is the plan-facing dissection of one expression: every column reference with its token span, every string-literal span (whose bytes must pass through splicing untouched), and the first raw A1/sheet-qualified reference if any (its source text; "" when the expression has none).

func ParseExprInfo

func ParseExprInfo(src ExprText) (ExprInfo, error)

ParseExprInfo re-parses one expression (a stage's stored source text, or a builder-supplied one) and reports its column-reference spans, string-literal spans, and any raw cell reference. A malformed expression — possible only for builder-built programs, since parsed stages store text the grammar already accepted — is constants.ErrSyntax.

type ExprText

type ExprText string

ExprText is the source of one tq expression, exactly as authored.

type Program

type Program struct {
	Stages []Stage
}

Program is a parsed, unplanned pipeline of stages — an immutable value, reusable and safe to share across concurrent runs.

func ParseProgram

func ParseProgram(src ProgramText) (Program, error)

ParseProgram parses a whole tq program into the typed Program AST, or constants.ErrSyntax with line/column detail. There are no partial programs: any report from the lexer or parser fails the parse.

type ProgramText

type ProgramText string

ProgramText is the source of a whole tq program.

type RenamePair

type RenamePair struct {
	To   string
	From Column
}

RenamePair is one `col as name`: the source column reference and the new name, taken verbatim.

type SortKey

type SortKey struct {
	Col          Column
	IsDescending bool
}

SortKey is one sort key: the column and whether `-` reversed it.

type Span

type Span struct {
	Start int
	Stop  int
}

Span is one token's inclusive rune range within its expression source.

type Stage

type Stage struct {
	Verb    Verb
	Columns []Column
	Expr    Expr
	Assigns []Assignment
	Renames []RenamePair
	Keys    []SortKey
	Count   int
}

Stage is one pipeline stage. Only the fields its Verb uses are set: Columns for select/drop/distinct and group keys, Expr for where, Assigns for derive and group aggregates, Renames for rename, Keys for sort, Count for limit/offset.

type Verb

type Verb string

Verb names a pipeline stage; the values are the SPECIFICATION §3 keywords.

const (
	VerbSelect   Verb = "select"
	VerbDrop     Verb = "drop"
	VerbWhere    Verb = "where"
	VerbDerive   Verb = "derive"
	VerbRename   Verb = "rename"
	VerbSort     Verb = "sort"
	VerbDistinct Verb = "distinct"
	VerbLimit    Verb = "limit"
	VerbOffset   Verb = "offset"
	VerbGroup    Verb = "group"
)

The stage verbs, in specification order.