ast

Documentation

Overview

Package ast holds the set of types used in the abstract syntax tree representation of the api language.

Index

• Constants
• Variables
• func Visit(node Node, visitor func(Node))
• type API
• type Abort
• type Annotation
• type Annotations
  • func (a Annotations) GetAnnotation(name string) *Annotation
• type Assign
• type BinaryOp
• type Block
• type Bool
• type Branch
• type Call
• type Case
• type Class
• type Clear
• type DeclareLocal
• type Default
• type Definition
• type Delete
• type Enum
• type EnumEntry
• type Fence
• type Field
• type Function
• type Generic
• type Group
• type Identifier
• type Import
• type Imported
• type Index
• type IndexedType
• type Invalid
• type Iteration
• type MapIteration
• type Mappings
  • func (m *Mappings) Add(a Node, c cst.Node)
  • func (m *Mappings) CST(ast Node) cst.Node
  • func (m *Mappings) MergeIn(other *Mappings)
• type Member
• type NamedArg
• type Node
• type Null
• type Number
• type Parameter
• type PointerType
• type PreConst
• type Pseudonym
• type Return
• type String
• type Switch
• type UnaryOp
• type Unknown

Constants

const (
	// Keyword strings represent places in the syntax where a word has special
	// meaning.
	KeywordAbort     = "abort"
	KeywordAPI       = "api"
	KeywordAlias     = "alias"
	KeywordBitfield  = "bitfield"
	KeywordCase      = "case"
	KeywordClass     = "class"
	KeywordCmd       = "cmd"
	KeywordConst     = "const"
	KeywordDefault   = "default"
	KeywordDefine    = "define"
	KeywordDelete    = "delete"
	KeywordClear     = "clear"
	KeywordElse      = "else"
	KeywordEnum      = "enum"
	KeywordExtern    = "extern"
	KeywordFalse     = "false"
	KeywordFence     = "fence"
	KeywordFor       = "for"
	KeywordIf        = "if"
	KeywordImport    = "import"
	KeywordIn        = "in"
	KeywordLabel     = "label"
	KeywordNull      = "null"
	KeywordReturn    = "return"
	KeywordPseudonym = "type"
	KeywordSwitch    = "switch"
	KeywordSub       = "sub"
	KeywordThis      = "this"
	KeywordTrue      = "true"
	KeywordWhen      = "when"
	KeywordApiIndex  = "api_index"
)

const (
	// Runes with special meaning to the parser.
	Quote    = '"'
	Backtick = '`'
)

const (
	// The set of operators understood by the parser.
	OpUnknown       = "?"
	OpBlockStart    = "{"
	OpBlockEnd      = "}"
	OpIndexStart    = "["
	OpIndexEnd      = "]"
	OpSlice         = ":"
	OpListStart     = "("
	OpListSeparator = ","
	OpListEnd       = ")"
	OpAssign        = "="
	OpAssignPlus    = "+="
	OpAssignMinus   = "-="
	OpDeclare       = ":="
	OpMember        = "."
	OpExtends       = ":"
	OpAnnotation    = "@"
	OpInitialise    = ":"
	OpPointer       = "*"
	OpEQ            = "=="
	OpGT            = ">"
	OpLT            = "<"
	OpGE            = ">="
	OpLE            = "<="
	OpNE            = "!="
	OpOr            = "||"
	OpAnd           = "&&"
	OpPlus          = "+"
	OpMinus         = "-"
	OpMultiply      = "*"
	OpDivide        = "/"
	OpBitwiseAnd    = "&"
	OpBitwiseOr     = "|"
	OpBitShiftRight = ">>"
	OpBitShiftLeft  = "<<"
	OpRange         = ".."
	OpNot           = "!"
	OpIn            = "in"
	OpGeneric       = "!"
)

Variables

var (
	Operators       = []string{}            // all valid operator strings, sorted in descending length order
	UnaryOperators  = map[string]struct{}{} // the map of valid unary operators
	BinaryOperators = map[string]struct{}{} // the map of valid boolean operators
)

var InvalidGeneric = &Generic{InvalidIdentifier, nil}

InvalidGeneric is a placeholder for an expected, but invalid generic. They are only generated by the parser when the source has a syntatic error.

var InvalidIdentifier = &Identifier{"<invalid>"}

InvalidIdentifier is a placeholder for an expected, but invalid identifier. They are only generated by the parser when the source has a syntatic error.

var InvalidNumber = &Number{"<invalid>"}

InvalidNumber is a placeholder for an expected, but invalid number. They are only generated by the parser when the source has a syntatic error.

var InvalidString = &String{"<invalid>"}

InvalidString is a placeholder for an expected, but invalid string. They are only generated by the parser when the source has a syntatic error.

Functions

func Visit

func Visit(node Node, visitor func(Node))

Visit invokes visitor for all the children of the supplied node.

Types

type API

type API struct {
	Imports     []*Import     // api files imported with the "import" keyword
	Externs     []*Function   // functions declared with the "extern" keyword
	Commands    []*Function   // functions declared with the "cmd" keyword
	Subroutines []*Function   // functions declared with the "sub" keyword
	Pseudonyms  []*Pseudonym  // strong type aliases declared with the "type" keyword
	Enums       []*Enum       // enumerated types, declared with the "enum" keyword
	Classes     []*Class      // class types, declared with the "class" keyword
	Fields      []*Field      // variables declared at the global scope
	Definitions []*Definition // definitions declared with the "define" keyword
	Index       *Number       // the API index
}

API is the root of the AST tree, and constitutes one entire parsed file. It holds the set of top level AST nodes, grouped by type.

type Abort

type Abort struct {
	// contains filtered or unexported fields
}

Abort is the AST node that represents «abort» statement

type Annotation

type Annotation struct {
	Name      *Identifier // the name part (between the @ and the brackets)
	Arguments []Node      // the list of arguments (the bit in brackets)
}

Annotation is the AST node that represents «@name(arguments) constructs»

type Annotations

type Annotations []*Annotation

Annotations represents the set of Annotation objects that apply to another AST node.

func (Annotations) GetAnnotation

func (a Annotations) GetAnnotation(name string) *Annotation

GetAnnotation finds annotation with given name, or nil if not found.

type Assign

type Assign struct {
	LHS      Node   // the location to store the value into
	Operator string // the assignment operator being applied
	RHS      Node   // the value to store
}

Assign represents a «location {,+,-}= value» statement that assigns a value to an existing mutable location.

type BinaryOp

type BinaryOp struct {
	LHS      Node   // the expression on the left of the operator
	Operator string // the operator being applied
	RHS      Node   // the expression on the right of the operator
}

BinaryOp represents any binary operation applied to two expressions.

type Block

type Block struct {
	Statements []Node // The set of statements that make up the block
}

Block represents a linear sequence of statements, most often the contents of a {} pair.

type Bool

type Bool struct {
	Value bool // The value of the boolean
}

Bool is used for the "true" and "false" keywords.

type Branch

type Branch struct {
	Condition Node   // the condition to use to select which block is active
	True      *Block // the block to use if condition is true
	False     *Block // the block to use if condition is false
}

Branch represents an «"if" condition { trueblock } "else" { falseblock }» structure.

type Call

type Call struct {
	Target    Node   // the function to invoke
	Arguments []Node // the arguments to the function
}

Call is an expression that invokes a function with a set of arguments. It has the structure «target(arguments)» where target must be a function and arguments is a comma separated list of expressions.

type Case

type Case struct {
	Annotations Annotations // the annotations applied to this case
	Conditions  []Node      // the set of conditions that would select this case
	Block       *Block      // the block to run if this case is selected
}

Case represents a «"case" conditions: block» structure within a switch statement. The conditions are a comma separated list of expressions the switch statement value will be compared against.

type Class

type Class struct {
	Annotations Annotations // the annotations applied to the class
	Name        *Identifier // the name of the class
	Fields      []*Field    // the fields of the class
}

Class represents a class type declaration of the form «"class" name { fields }»

type Clear

type Clear struct {
	Map Node
}

Clear is the AST node that represents «clear(map)» statement

type DeclareLocal

type DeclareLocal struct {
	Name *Identifier // the name to give the new local
	RHS  Node        // the value to store in that local
}

DeclareLocal represents a «name := value» statement that declares a new immutable local variable with the specified value and inferred type.

type Default

type Default struct {
	Block *Block // the block to run if the default is selected
}

Default represents a «"default": block» structure within a switch statement.

type Definition

type Definition struct {
	Annotations Annotations // the annotations applied to this definition
	Name        *Identifier // the name of this definition
	Expression  Node        // the expression this definition expands to
}

Definition declares a new named literal, has the form «"define" name value».

type Delete

type Delete struct {
	Map Node
	Key Node
}

Delete is the AST node that represents «delete(map, key)» statement

type Enum

type Enum struct {
	Annotations Annotations  // the annotations applied to the enum
	NumberType  Node         // the optional numerical type of the enum
	Name        *Identifier  // the name of the enum
	IsBitfield  bool         // whether this enum represents a bitfield form
	Entries     []*EnumEntry // the set of valid entries for this enum
}

Enum represents an enumerated type declaration, of the form «"enum" name [: type] { entries }» where entries is a comma separated list of «name = value»

type EnumEntry

type EnumEntry struct {
	Owner *Enum       // the enum this entry is a part of
	Name  *Identifier // the name this entry is given
	Value *Number     // the value of this entry
}

EnumEntry represents a single value in an enumerated type.

type Fence

type Fence struct {
	// contains filtered or unexported fields
}

Fence is the AST node that represents «fence» statement

type Field

type Field struct {
	Annotations Annotations // the annotations applied to the field
	Type        Node        // the type the field holds
	Name        *Identifier // the name of the field
	Default     Node        // the default value expression for the field
}

Field represents a field of a class or api, with the structure «type name = expression»

type Function

type Function struct {
	Annotations Annotations  // the annotations applied to this function
	Generic     *Generic     // the name of the function
	Parameters  []*Parameter // the parameters the function takes
	Block       *Block       // the body of the function if present
}

Function represents the declaration of a callable entity, any of "cmd", "sub" or "extern". Its structure is «return_type name(parameters) body» where parameters is a comma separated list and body is an optional block.

type Generic

type Generic struct {
	Name      *Identifier // the generic identifier.
	Arguments []Node      // the type arguments to the generic.
}

Generic represents a identifier modified by type arguments. It looks like: «identifier ! ( arg | <arg {, arg} )>»

type Group

type Group struct {
	Expression Node // the expression within the parentheses
}

Group represents the «(expression)» construct, a single parenthesized expression.

type Identifier

type Identifier struct {
	Value string // the identifier
}

Identifier holds a parsed identifier in the parse tree.

type Import

type Import struct {
	Annotations Annotations // the annotations applied to the import
	Path        *String     // the relative path to the api file
}

Import is the AST node that represents «import name "path"» constructs

type Imported

type Imported struct {
	From *Identifier // the import this name is from
	Name *Identifier // the name being imported
}

Imported represents an imported type name.

type Index

type Index struct {
	Object Node // the object to index
	Index  Node // the index to lookup
}

Index represents any expression of the form «object[index]» Used for arrays, maps and bitfields.

type IndexedType

type IndexedType struct {
	ValueType Node // The element type exposed by the indexed type
	Index     Node // the index of the type
}

IndexedType represents a type declaration with an indexing suffix, which looks like «type[index]»

type Invalid

type Invalid struct {
	// contains filtered or unexported fields
}

Invalid is used when an error was encountered in the parsing, but we want to keep going. If there are no errors, this will never be in the tree.

type Iteration

type Iteration struct {
	Variable *Identifier // the variable to use for the iteration value
	Iterable Node        // the expression that produces the iterable to loop over
	Block    *Block      // the block to run once per item in the iterable
}

Iteration represents a «"for" variable "in" iterable { block }» structure.

type MapIteration

type MapIteration struct {
	IndexVariable *Identifier // The index variable to use for iteration
	KeyVariable   *Identifier // the key variable to use for iteration
	ValueVariable *Identifier // the value variable to use for iteration
	Map           Node        // the expression that produces the map to loop over
	Block         *Block      // the block to run once per k-v mapping
}

MapIteration represents a «"for" i "," k "," v "in" map { block }» structure.

type Mappings

type Mappings struct {
	ASTToCST map[Node]cst.Node
	CSTToAST map[cst.Node]Node
}

Mappings is a two-way map of AST nodes to semantic nodes.

func (*Mappings) Add

func (m *Mappings) Add(a Node, c cst.Node)

Add creates an association between the AST and CST nodes.

func (*Mappings) CST

func (m *Mappings) CST(ast Node) cst.Node

CST returns the CST node for the given AST node.

func (*Mappings) MergeIn

func (m *Mappings) MergeIn(other *Mappings)

MergeIn merges the mappings in other into m.

type Member

type Member struct {
	Object Node        // the object to get a member of
	Name   *Identifier // the name of the member to get
}

Member represents an expression that access members of objects. Always of the form «object.name» where object is an expression.

type NamedArg

type NamedArg struct {
	Name  *Identifier // the name of the parameter this value is for
	Value Node        // the value to use for that parameter
}

NamedArg represents a «name = value» expression as a function argument.

type Node

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

Node represents any AST-node type.

type Null

type Null struct {
	// contains filtered or unexported fields
}

Null represents the null literal. This is the default value for the inferred type, and must be used in a context where the type can be inferred.

type Number

type Number struct {
	Value string // the string representation of the constant
}

Number represents a typeless numeric constant.

type Parameter

type Parameter struct {
	Annotations Annotations // the annotations applied to this parameter
	This        bool        // true if the parameter is the this pointer of a method
	Type        Node        // the type of the parameter
	Name        *Identifier // the name the parameter as exposed to the body
}

Parameter represents a single parameter in the set of parameters for a Function. It has the structure «["in"|"out"|"inout"|"this"] type name»

type PointerType

type PointerType struct {
	To    Node // the underlying type this pointer points to
	Const bool // whether the pointer type has the post-const modifier applied
}

PointerType represents a pointer type declaration, of the form «type*»

type PreConst

type PreConst struct {
	Type Node // the underlying type that is constant
}

PreConst represents a pre-const type declaration, of the form «const type»

type Pseudonym

type Pseudonym struct {
	Annotations Annotations // the annotations applied to the type
	Name        *Identifier // the name of the type
	To          Node        // the underlying type
}

Pseudonym declares a new type in terms of another type. Has the form «"type" type name» Pseydonyms are proper types, but the underlying type can be discovered.

type Return

type Return struct {
	Value Node // the value to return
}

Return represents the «"return" value» construct, that assigns the value to the result slot of the function.

type String

type String struct {
	Value string // The body of the string, not including the delimiters
}

String represents a quoted string constant.

type Switch

type Switch struct {
	Value   Node     // the value to match against
	Cases   []*Case  // the set of cases to match the value with
	Default *Default // the block which is used if no case is matched
}

Switch represents a «"switch" value { cases }» structure. The first matching case is selected. If a switch is used as an expression, the case blocks must all be a single expression.

type UnaryOp

type UnaryOp struct {
	Operator   string // the operator being applied
	Expression Node   // the expression the operator is being applied to
}

UnaryOp represents any unary operation applied to an expression.

type Unknown

type Unknown struct {
	// contains filtered or unexported fields
}

Unknown represents the "?" construct. This is used in places where an expression takes a value that is implementation defined.