ast

Documentation

Overview

Package ast defines the Fluent abstract syntax tree, a faithful port of the data model from @fluent/syntax (ast.ts).

Go has no class inheritance, so the abstract bases from the TypeScript implementation (SyntaxNode, Entry, Expression, Literal, BaseComment) are modeled as interfaces and the concrete productions as structs implementing them. Every node carries an optional *Span which is only populated when spans are enabled during parsing.

Index

• func Marshal(n Node, withSpans bool) ([]byte, error)
• type Annotation
• type Attribute
• type BaseComment
• type CallArguments
• type Comment
• type Entry
• type Expression
• type FunctionReference
• type GroupComment
• type Identifier
• type InlineExpression
• type Junk
  • func (j *Junk) AddAnnotation(a *Annotation)
• type Literal
• type Message
• type MessageReference
• type NamedArgument
• type Node
• type NumberLiteral
  • func (n *NumberLiteral) Parse() (value float64, precision int)
• type Pattern
• type PatternElement
• type Placeable
• type Resource
  • func (r *Resource) MarshalJSON() ([]byte, error)
• type ResourceComment
• type SelectExpression
• type Span
  • func (*Span) GetSpan() *Span
• type Spanned
  • func (s *Spanned) AddSpan(start, end int)
  • func (s *Spanned) GetSpan() *Span
  • func (s *Spanned) SetSpan(sp *Span)
• type StringLiteral
  • func (s *StringLiteral) Parse() string
• type SyntaxNode
• type Term
• type TermReference
• type TextElement
• type VariableReference
• type Variant
• type VariantKey

Functions

func Marshal

func Marshal(n Node, withSpans bool) ([]byte, error)

Marshal encodes any AST node to canonical Fluent JSON matching the shape used by @fluent/syntax. When withSpans is false, every "span" field is omitted, which mirrors the fixtures_structure comparison and is what the conformance suite uses to compare span-free trees.

The "type" discriminator equals the node's class name, field names and their order match the reference implementation, empty slices serialize as [] and absent optional nodes serialize as null.

Types

type Annotation

type Annotation struct {
	Spanned
	Code      string
	Arguments []any
	Message   string
}

Annotation describes a single parse error within Junk.

type Attribute

type Attribute struct {
	Spanned
	ID    *Identifier
	Value *Pattern
}

Attribute is a named sub-pattern of a Message or Term (.name = value).

type BaseComment

type BaseComment interface {
	Entry
	// contains filtered or unexported methods
}

BaseComment is a Comment, GroupComment, or ResourceComment.

type CallArguments

type CallArguments struct {
	Spanned
	Positional []InlineExpression
	Named      []*NamedArgument
}

CallArguments holds the positional and named arguments of a call.

type Comment

type Comment struct {
	Spanned
	Content string
}

Comment is a standalone or attached comment (# ...).

type Entry

type Entry interface {
	SyntaxNode
	// contains filtered or unexported methods
}

Entry is one of the top-level productions in a Resource body: Message, Term, a comment, or Junk.

type Expression

type Expression interface {
	SyntaxNode
	// contains filtered or unexported methods
}

Expression is any expression that may appear inside a Placeable.

type FunctionReference

type FunctionReference struct {
	Spanned
	ID        *Identifier
	Arguments *CallArguments
}

FunctionReference is a call to a built-in function (upper-case identifier).

type GroupComment

type GroupComment struct {
	Spanned
	Content string
}

GroupComment groups a section of a resource (## ...).

type Identifier

type Identifier struct {
	Spanned
	Name string
}

Identifier is a bare name.

type InlineExpression

type InlineExpression interface {
	Expression
	// contains filtered or unexported methods
}

InlineExpression is the subset of expressions usable outside of a Placeable (everything except SelectExpression).

type Junk

type Junk struct {
	Spanned
	Annotations []*Annotation
	Content     string
}

Junk is a slice of source that failed to parse, carrying the annotations that describe the errors.

func (*Junk) AddAnnotation

func (j *Junk) AddAnnotation(a *Annotation)

AddAnnotation appends an annotation to the junk.

type Literal

type Literal interface {
	InlineExpression
	// contains filtered or unexported methods
}

Literal is a StringLiteral or NumberLiteral.

type Message

type Message struct {
	Spanned
	ID         *Identifier
	Value      *Pattern // nil when the message has only attributes
	Attributes []*Attribute
	Comment    *Comment // nil when no comment is attached
}

Message is a translatable message with an optional value, attributes, and an optional attached comment.

type MessageReference

type MessageReference struct {
	Spanned
	ID        *Identifier
	Attribute *Identifier // nil when no attribute is referenced
}

MessageReference refers to another message, optionally to one of its attributes.

type NamedArgument

type NamedArgument struct {
	Spanned
	Name  *Identifier
	Value Literal
}

NamedArgument is a key/value call argument (name: value).

type Node

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

Node is the base interface implemented by every AST node, including Span and Annotation. It corresponds to BaseNode in the reference. Node is a closed interface: all implementations live in this package.

type NumberLiteral

type NumberLiteral struct {
	Spanned
	Value string
}

NumberLiteral holds the textual form of a number literal.

func (*NumberLiteral) Parse

func (n *NumberLiteral) Parse() (value float64, precision int)

Parse returns the numeric value and the number of fractional digits.

type Pattern

type Pattern struct {
	Spanned
	Elements []PatternElement
}

Pattern is the value of a message, term, attribute, or variant: a sequence of text elements and placeables.

type PatternElement

type PatternElement interface {
	SyntaxNode
	// contains filtered or unexported methods
}

PatternElement is an element of a Pattern: TextElement or Placeable.

type Placeable

type Placeable struct {
	Spanned
	Expression Expression
}

Placeable wraps an expression embedded in a Pattern (between { and }).

type Resource

type Resource struct {
	Spanned
	Body []Entry
}

Resource is the root node holding a list of top-level entries.

func (*Resource) MarshalJSON

func (r *Resource) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for Resource, omitting spans. Use Marshal(node, true) to include them.

type ResourceComment

type ResourceComment struct {
	Spanned
	Content string
}

ResourceComment documents the whole resource (### ...).

type SelectExpression

type SelectExpression struct {
	Spanned
	Selector InlineExpression
	Variants []*Variant
}

SelectExpression chooses among variants based on a selector.

type Span

type Span struct {
	Start int
	End   int
}

Span records the [Start, End) byte range a node covers in the source.

func (*Span) GetSpan

func (*Span) GetSpan() *Span

GetSpan satisfies a partial SyntaxNode shape; a Span has no span of its own.

type Spanned

type Spanned struct {
	Span *Span
}

Spanned is embedded by all SyntaxNode structs to provide span storage.

func (*Spanned) AddSpan

func (s *Spanned) AddSpan(start, end int)

AddSpan attaches a new span covering [start, end).

func (*Spanned) GetSpan

func (s *Spanned) GetSpan() *Span

GetSpan returns the node's span (nil when spans are disabled).

func (*Spanned) SetSpan

func (s *Spanned) SetSpan(sp *Span)

SetSpan replaces the node's span.

type StringLiteral

type StringLiteral struct {
	Spanned
	Value string
}

StringLiteral holds the exact, character-for-character contents of a quoted literal (escape sequences are not unescaped in the AST).

func (*StringLiteral) Parse

func (s *StringLiteral) Parse() string

Parse unescapes the literal, returning the resolved string value. Escape sequences representing surrogate code points are replaced with U+FFFD.

type SyntaxNode

type SyntaxNode interface {
	Node
	GetSpan() *Span
	SetSpan(*Span)
	AddSpan(start, end int)
}

SyntaxNode is the interface for nodes which carry their own Span via the Spanned embed. Every node in this package satisfies it except *Span and *Annotation, which implement only Node.

type Term

type Term struct {
	Spanned
	ID         *Identifier
	Value      *Pattern
	Attributes []*Attribute
	Comment    *Comment
}

Term is a private message (its id is prefixed with "-"); it always has a value.

type TermReference

type TermReference struct {
	Spanned
	ID        *Identifier
	Attribute *Identifier    // nil when no attribute is referenced
	Arguments *CallArguments // nil when no arguments are present
}

TermReference refers to a term, optionally to one of its attributes, and may carry call arguments.

type TextElement

type TextElement struct {
	Spanned
	Value string
}

TextElement is verbatim text within a Pattern.

type VariableReference

type VariableReference struct {
	Spanned
	ID *Identifier
}

VariableReference refers to an external variable ($name).

type Variant

type Variant struct {
	Spanned
	Key     VariantKey // *Identifier or *NumberLiteral
	Value   *Pattern
	Default bool
}

Variant is a single branch of a SelectExpression.

type VariantKey

type VariantKey interface {
	SyntaxNode
	// contains filtered or unexported methods
}

VariantKey is the key of a Variant: Identifier or NumberLiteral.