ast

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Aug 26, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package ast defines the Runefile abstract syntax tree produced by the parser and consumed by the analyzer, evaluator, scheduler, cache, and MCP server. Every node carries a token.Span so any diagnostic can point at precise source (Principle II).

Index

Constants

View Source
const (
	ExecSh     = "sh"
	ExecPython = "python"
	ExecNode   = "node"
	ExecAgent  = "agent"
)

Executor names for the built-in body languages. The empty string means the default shell executor; any other non-built-in string is a custom executor.

View Source
const (
	AttrPrivate          = "private"
	AttrConfirm          = "confirm"
	AttrGroup            = "group"
	AttrParallel         = "parallel"
	AttrLinux            = "linux"
	AttrMacos            = "macos"
	AttrWindows          = "windows"
	AttrUnix             = "unix"
	AttrNoCD             = "no-cd"
	AttrWorkingDirectory = "working-directory"
	AttrEnv              = "env"
	AttrDoc              = "doc"
	AttrScript           = "script"
	AttrCache            = "cache"
	AttrNetwork          = "network"         // sets MCP openWorldHint
	AttrNoExitMessage    = "no-exit-message" // suppress the trailing error banner
	AttrContext          = "context"         // project-health hook injected into agent context (spec 021)
)

Attribute kinds.

Variables

This section is empty.

Functions

func Dump

func Dump(f *File) string

Dump renders a File as a stable, indented tree. It is used by golden AST tests and for ad-hoc debugging; it is deterministic (declaration order preserved).

func DumpExpr

func DumpExpr(e Expr) string

DumpExpr renders an expression in the same compact form Dump uses (exported for --dump JSON output).

Types

type Assignment

type Assignment struct {
	Name string
	Expr Expr
	Sp   token.Span
}

Assignment is a module-level variable binding `NAME := EXPR`.

func (*Assignment) Span

func (a *Assignment) Span() token.Span

type Attribute

type Attribute struct {
	Kind       string
	Str        string // confirm prompt, group name, doc, script cmd, working-directory, env name
	Str2       string // env value
	Inputs     []Expr // cache(inputs=[...])
	Outputs    []Expr // cache(outputs=[...])
	HasOutputs bool
	Sp         token.Span
}

Attribute is a `[name(args)]` annotation on a task. Most attributes carry a single string argument (Str); env carries two (Str, Str2); cache carries input/output glob lists.

func (*Attribute) Span

func (a *Attribute) Span() token.Span

type Binary

type Binary struct {
	Op    token.Kind // PLUS or SLASH
	Left  Expr
	Right Expr
	Sp    token.Span
}

Binary is a concatenation (+) or path-join (/) expression.

func (*Binary) Span

func (e *Binary) Span() token.Span

type BodyLine

type BodyLine struct {
	Raw             string
	NoEcho          bool // leading @
	ContinueOnError bool // leading -
	Sp              token.Span
}

BodyLine is one line of a task body, with leading-sigil flags stripped. Raw retains {{ ... }} interpolation placeholders for the evaluator.

func (*BodyLine) Span

func (b *BodyLine) Span() token.Span

type CondBranch

type CondBranch struct {
	Left   Expr
	Op     token.Kind // EQ, NEQ, MATCH
	Right  Expr
	Result Expr
}

CondBranch is one `if/else if` clause: Left Op Right { Result }.

type Conditional

type Conditional struct {
	Branches []CondBranch
	Else     Expr
	Sp       token.Span
}

Conditional is an if/else-if/else expression. It always has a final Else.

func (*Conditional) Span

func (e *Conditional) Span() token.Span

type DepCall

type DepCall struct {
	Name string // may be namespaced (mod::task)
	Args []Expr
	Sp   token.Span
}

DepCall is a dependency or post-hook invocation.

func (*DepCall) Span

func (d *DepCall) Span() token.Span

type Expr

type Expr interface {
	Node
	// contains filtered or unexported methods
}

Expr is implemented by every expression node.

type File

type File struct {
	Path        string
	Settings    []*Setting
	Assignments []*Assignment
	Tasks       []*Task
	Imports     []*Import
	Mods        []*Mod
	Sp          token.Span
}

File is the root of one parsed Runefile. A project may be a tree of Files via import (spliced) and mod (namespaced).

func (*File) Span

func (f *File) Span() token.Span

type FuncCall

type FuncCall struct {
	Name string
	Args []Expr
	Sp   token.Span
}

FuncCall is a built-in function call.

func (*FuncCall) Span

func (e *FuncCall) Span() token.Span

type Import

type Import struct {
	Path     string // decoded string-literal path
	Optional bool   // import?
	Sp       token.Span
}

Import splices another file's definitions into the current namespace.

func (*Import) Span

func (i *Import) Span() token.Span

type Mod

type Mod struct {
	Name string
	Path string // optional explicit path; "" => derive from name
	Sp   token.Span
}

Mod loads another file as a child namespace addressable as name::task.

func (*Mod) Span

func (m *Mod) Span() token.Span

type Node

type Node interface {
	Span() token.Span
}

Node is implemented by every AST node.

type Param

type Param struct {
	Name    string
	Kind    ParamKind
	Default Expr // only for ParamDefaulted
	Sp      token.Span
}

Param is a positional task parameter.

func (*Param) Span

func (p *Param) Span() token.Span

type ParamKind

type ParamKind int

ParamKind classifies a task parameter.

const (
	ParamRequired     ParamKind = iota // name
	ParamDefaulted                     // name=expr
	ParamVariadicPlus                  // +name (one or more)
	ParamVariadicStar                  // *name (zero or more)
)

type Setting

type Setting struct {
	Name  string
	Value Expr   // nil for the bare boolean form
	List  []Expr // populated for list-valued settings
	Bool  bool   // true for the bare form
	Sp    token.Span
}

Setting is a `set NAME [:= VALUE]` directive. The bare form (`set export`) is boolean true (Bool=true, Value=nil). List-valued settings (e.g. `set shell`) keep their elements in List.

func (*Setting) Span

func (s *Setting) Span() token.Span

type StringLit

type StringLit struct {
	Value string
	Sp    token.Span
}

StringLit is a decoded string literal.

func (*StringLit) Span

func (e *StringLit) Span() token.Span

type Task

type Task struct {
	Name       string
	Doc        string // from the preceding comment run or [doc("...")]
	Params     []*Param
	Executor   string // "" => default sh
	Deps       []*DepCall
	PostHooks  []*DepCall // run after, on success (&&)
	FailHooks  []*DepCall // run after, on failure (||)
	Attributes []*Attribute
	Body       []*BodyLine
	Sp         token.Span
}

Task is a named recipe.

func (*Task) Attr

func (t *Task) Attr(kind string) *Attribute

Attr returns the first attribute of the given kind, or nil.

func (*Task) AvailableOn added in v0.5.0

func (t *Task) AvailableOn(goos string) bool

AvailableOn reports whether the task may run on the given GOOS. A task with no OS attribute is available everywhere; multiple OS attributes combine as OR; "unix" matches every GOOS except "windows". This is the single availability rule shared by listing, completion, MCP exposure, root resolution, and dependency scheduling.

func (*Task) Edges added in v0.6.0

func (t *Task) Edges() []*DepCall

Edges returns every outgoing task reference of t: dependencies, && post- hooks, and || failure hooks — the single edge-set definition shared by dependency resolution, cycle detection, context closure walks, and editor navigation, so a new clause kind cannot be missed by one of them.

func (*Task) IsPrivate

func (t *Task) IsPrivate() bool

IsPrivate reports whether the task carries the [private] attribute or a name beginning with '_'.

func (*Task) OSFilters added in v0.5.0

func (t *Task) OSFilters() []string

OSFilters returns the task's OS attribute kinds in source order, or nil when the task is unrestricted.

func (*Task) Span

func (t *Task) Span() token.Span

type VarRef

type VarRef struct {
	Name string
	Sp   token.Span
}

VarRef is a bare name reference. Resolution (param vs module variable) is performed by the analyzer/evaluator; params shadow variables.

func (*VarRef) Span

func (e *VarRef) Span() token.Span

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL