ast

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 19, 2025 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

Package ast defines the Abstract Syntax Tree node types for Buildfile parsing.

The AST captures syntactic structure without interpretation—no evaluation happens during parsing. Each node carries a SourceLocation for precise error reporting with file:line:column format.

Statement Types

All top-level AST nodes implement the Statement interface:

  • Directive: Global directives (.shell:, .parallel:, .default:, .include:)
  • Environment: Environment block (.environment:)
  • Variable: Variable definition (immediate or lazy)
  • Conditional: If/elif/else/end block
  • Target: Target definition with dependencies and recipe
  • Comment: Comment line
  • Blank: Blank line

Design Decisions

BraceExpr nodes remain unresolved during parsing. In target patterns, {name} could be either a capture (pattern matching variable) or a variable interpolation. The parser produces BraceExpr nodes; semantic analysis resolves them based on the symbol table.

Interfaces use unexported marker methods (statementNode(), valuePartNode(), etc.) to enforce interface implementation at compile time while preventing external implementation. This ensures the set of node types is closed.

Optional fields use nil pointers to indicate absence. For example, Environment.Name is nil for the default environment, and Recipe.Directives.Shell is nil when using the global default shell.

Package ast defines the Abstract Syntax Tree node types for Buildfile parsing.

The AST captures the syntactic structure of a Buildfile without interpretation. No evaluation happens during parsing - the AST is a pure representation of the source structure.

Key design decisions:

  • BraceExpr nodes in target patterns remain unresolved during parsing. Semantic analysis resolves them to Capture or Interpolation.
  • All nodes carry SourceLocation for error reporting.
  • Interfaces use marker methods to ensure type safety at compile time.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Blank 

type Blank struct {
	Location SourceLocation
}

Blank represents a blank line.

type BlockCommand 

type BlockCommand struct {
	Lines    [][]CommandPart
	Location SourceLocation
}

BlockCommand represents a block: with multiple lines.

type BraceExpr 

type BraceExpr struct {
	Identifier string
	Location   SourceLocation
}

BraceExpr represents an unresolved {name} in a target pattern. During parsing, we don't know if this is a capture or a variable interpolation. Semantic analysis will resolve this based on the symbol table.

type Buildfile 

type Buildfile struct {
	SourcePath string      // Path to the source file
	Statements []Statement // Top-level statements
}

Buildfile is the root AST node representing an entire Buildfile.

type Command 

type Command interface {
	// contains filtered or unexported methods
}

Command is the interface for recipe commands.

The commandNode() marker method is unexported to prevent external packages from implementing this interface, ensuring a closed set of command types.

Implementers: LineCommand, BlockCommand

type CommandInterpolation 

type CommandInterpolation struct {
	Name     string
	Raw      bool // true for :raw modifier
	Location SourceLocation
}

CommandInterpolation represents a variable interpolation in a command.

type CommandPart 

type CommandPart interface {
	// contains filtered or unexported methods
}

CommandPart is the interface for parts of a command line.

The commandPartNode() marker method is unexported to prevent external packages from implementing this interface, ensuring a closed set of command part types.

Implementers: LiteralCommand, CommandInterpolation

type Comment 

type Comment struct {
	Text     string
	Location SourceLocation
}

Comment represents a comment line.

type Condition 

type Condition interface {
	// contains filtered or unexported methods
}

Condition is the interface for conditional expressions (if/ifdef/ifndef).

The conditionNode() marker method is unexported to prevent external packages from implementing this interface, ensuring a closed set of condition types.

Implementers: EqualsCondition, NotEqualsCondition, DefinedCondition, NotDefinedCondition

type Conditional 

type Conditional struct {
	IfBranch     ConditionalBranch
	ElifBranches []ConditionalBranch
	ElseBody     []Statement // nil if no else clause
	Location     SourceLocation
}

Conditional represents an if/elif/else/end block.

type ConditionalBranch 

type ConditionalBranch struct {
	Condition Condition
	Body      []Statement
}

ConditionalBranch represents a single branch in a conditional.

type DefinedCondition 

type DefinedCondition struct {
	Name string
}

DefinedCondition represents an ifdef check.

type Dependency 

type Dependency struct {
	Segments []PatternSegment
}

Dependency represents a dependency in a target definition.

type Directive 

type Directive struct {
	Kind     DirectiveKind
	Value    *Value
	Location SourceLocation
}

Directive represents a global directive statement (.shell, .parallel, etc.).

func (*Directive) String 

func (d *Directive) String() string

String returns a human-readable representation of the directive.

type DirectiveKind 

type DirectiveKind int

DirectiveKind represents the type of a directive. 

const (
	DirectiveShell DirectiveKind = iota
	DirectiveParallel
	DirectiveDefault
	DirectiveInclude
)

func (DirectiveKind) String 

func (k DirectiveKind) String() string

String returns the string representation of the directive kind.

type Environment 

type Environment struct {
	Name     *string       // nil for default environment
	Runtime  *Runtime      // .using
	Source   *Value        // .source
	Args     *Value        // .args
	Requires []Requirement // .requires
	Location SourceLocation
}

Environment represents an environment block.

func (*Environment) String 

func (e *Environment) String() string

String returns a human-readable representation of the environment.

type EqualsCondition 

type EqualsCondition struct {
	Left  *Value
	Right *Value
}

EqualsCondition represents a == comparison.

type FunctionCall 

type FunctionCall struct {
	Name     FunctionName
	Args     []*Value
	Location SourceLocation
}

FunctionCall represents a function call in a value.

type FunctionName 

type FunctionName int

FunctionName represents a built-in function name. 

const (
	FuncShell FunctionName = iota
	FuncGlob
	FuncBasename
	FuncDirname
	FuncReplace
)

func (FunctionName) String 

func (f FunctionName) String() string

String returns the string representation of the function name.

type Interpolation 

type Interpolation struct {
	Name     string
	Raw      bool // true for :raw modifier
	Location SourceLocation
}

Interpolation represents a variable interpolation in a value.

type LineCommand 

type LineCommand struct {
	Parts    []CommandPart
	Location SourceLocation
}

LineCommand represents a single command line.

type LiteralCommand 

type LiteralCommand struct {
	Text string
}

LiteralCommand represents literal text in a command.

type LiteralSegment 

type LiteralSegment struct {
	Text string
}

LiteralSegment represents a literal string in a pattern.

type LiteralValue 

type LiteralValue struct {
	Text string
}

LiteralValue represents literal text in a value.

type NotDefinedCondition 

type NotDefinedCondition struct {
	Name string
}

NotDefinedCondition represents an ifndef check.

type NotEqualsCondition 

type NotEqualsCondition struct {
	Left  *Value
	Right *Value
}

NotEqualsCondition represents a != comparison.

type PatternSegment 

type PatternSegment interface {
	// contains filtered or unexported methods
}

PatternSegment is the interface for segments in a target pattern.

The patternSegmentNode() marker method is unexported to prevent external packages from implementing this interface, ensuring a closed set of segment types.

Implementers: LiteralSegment, BraceExpr

type Recipe 

type Recipe struct {
	Directives RecipeDirectives
	Commands   []Command
	Location   SourceLocation
}

Recipe represents the recipe section of a target.

func (*Recipe) String 

func (r *Recipe) String() string

String returns a human-readable representation of the recipe.

type RecipeDirectives 

type RecipeDirectives struct {
	Shell    *Value        // .shell override
	After    []*Value      // .after order-only dependencies
	Autodeps *Value        // .autodeps file path
	Requires []Requirement // .requires binaries
}

RecipeDirectives holds the directives that can appear in a recipe.

type Requirement 

type Requirement struct {
	Name    string
	Version VersionSpec
}

Requirement represents a required binary with optional version spec.

type Runtime 

type Runtime int

Runtime represents the runtime type for an environment. 

const (
	RuntimeBare Runtime = iota
	RuntimeDocker
	RuntimePodman
	RuntimeDevcontainer
	RuntimeNix
	RuntimeLima
)

func (Runtime) String 

func (r Runtime) String() string

String returns the string representation of the runtime.

type SourceLocation 

type SourceLocation struct {
	File   string // Source file path
	Line   int    // 1-based line number
	Column int    // 1-based column number
}

SourceLocation represents a position in source code.

func SourceLocationFromToken 

func SourceLocationFromToken(tok lexer.Token) SourceLocation

SourceLocationFromToken creates a SourceLocation from a lexer token.

func (SourceLocation) String 

func (l SourceLocation) String() string

String returns a human-readable representation of the source location.

type Statement 

type Statement interface {
	// contains filtered or unexported methods
}

Statement is the interface for all top-level AST nodes.

The statementNode() marker method is unexported to prevent external packages from implementing this interface. This ensures the set of statement types is closed and known at compile time, enabling exhaustive type switches without a default case.

Implementers: Directive, Environment, Variable, Conditional, Target, Comment, Blank

type Target 

type Target struct {
	Pattern      TargetPattern
	Dependencies []Dependency
	Recipe       *Recipe
	Location     SourceLocation
}

Target represents a target definition with dependencies and optional recipe.

func (*Target) String 

func (t *Target) String() string

String returns a human-readable representation of the target.

type TargetPattern 

type TargetPattern struct {
	Segments    []PatternSegment
	IsPhony     bool // true for @name targets
	IsDirectory bool // true for targets ending with /
}

TargetPattern represents the left side of a target definition.

type Value 

type Value struct {
	Parts    []ValuePart
	Location SourceLocation
}

Value represents a composite value (string with interpolations and function calls).

func (*Value) String 

func (v *Value) String() string

String returns a human-readable representation of the value.

type ValuePart 

type ValuePart interface {
	// contains filtered or unexported methods
}

ValuePart is the interface for parts of a value (right-hand side of =).

The valuePartNode() marker method is unexported to prevent external packages from implementing this interface, ensuring a closed set of value part types.

Implementers: LiteralValue, Interpolation, FunctionCall

type Variable 

type Variable struct {
	Name     string
	Value    *Value
	Lazy     bool // true for lazy assignment
	Location SourceLocation
}

Variable represents a variable definition.

func (*Variable) String 

func (v *Variable) String() string

String returns a human-readable representation of the variable.

type VersionExact 

type VersionExact struct {
	Major int
	Minor int
	Patch int
}

VersionExact represents an exact version (e.g., "11.4.0").

func (VersionExact) String 

func (v VersionExact) String() string

type VersionLatest 

type VersionLatest struct{}

VersionLatest represents "latest" or unspecified version.

func (VersionLatest) String 

func (v VersionLatest) String() string

type VersionMajor 

type VersionMajor struct {
	Major int
}

VersionMajor represents a major version (e.g., "11").

func (VersionMajor) String 

func (v VersionMajor) String() string

type VersionMajorMinor 

type VersionMajorMinor struct {
	Major int
	Minor int
}

VersionMajorMinor represents a major.minor version (e.g., "11.4").

func (VersionMajorMinor) String 

func (v VersionMajorMinor) String() string

type VersionSpec 

type VersionSpec interface {
	String() string
	// contains filtered or unexported methods
}

VersionSpec is the interface for version specifications in .requires directives.

The versionSpecNode() marker method is unexported to prevent external packages from implementing this interface, ensuring a closed set of version spec types.

Implementers: VersionLatest, VersionMajor, VersionMajorMinor, VersionExact

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.