syntax

Documentation

Overview

Package syntax is an idiomatic Go port of @fluent/syntax (Project Fluent): a parser, serializer, and AST visitor for the Fluent localization format.

The AST node types live in the sub-package github.com/hakastein/gofluent/syntax/ast.

Index

• func ColumnOffset(source string, pos int) int
• func LineOffset(source string, pos int) int
• func Parse(source string, opts ...Option) *ast.Resource
• func ParseEntry(source string, opts ...Option) ast.Entry
• func Serialize(resource *ast.Resource, opts ...SerializerOption) string
• func Transform(t Transformer, node ast.Node) ast.Node
• func Walk(v Visitor, node ast.Node)
• type Option
  • func WithSpans(enabled bool) Option
• type ParseError
  • func (e *ParseError) Error() string
• type Parser
  • func NewParser(opts ...Option) *Parser
  • func (p *Parser) Parse(source string) *ast.Resource
  • func (p *Parser) ParseEntry(source string) ast.Entry
• type Serializer
  • func NewSerializer(opts ...SerializerOption) *Serializer
  • func (s *Serializer) Serialize(resource *ast.Resource) string
• type SerializerOption
  • func WithJunk(enabled bool) SerializerOption
• type Transformer
• type Visitor

Functions

func ColumnOffset

func ColumnOffset(source string, pos int) int

ColumnOffset returns the zero-based column of pos within its line in source. As with LineOffset, pos is a UTF-16 code-unit offset and the scan is over UTF-16 units, mirroring the reference columnOffset (including its off-by-one: it searches backwards from pos-1 so a line break sitting exactly at pos is not treated as the previous one).

func LineOffset

func LineOffset(source string, pos int) int

LineOffset returns the zero-based line index of pos within source. pos is a UTF-16 code-unit offset, matching the offsets the parser records in spans (the parser is a port of fluent.js, whose stream indexes UTF-16 strings). This mirrors the reference lineOffset, which operates on JS (UTF-16) strings.

func Parse

func Parse(source string, opts ...Option) *ast.Resource

Parse performs a full parse of source with junk recovery. It never returns an error: invalid entries become ast.Junk carrying ast.Annotation diagnostics. Spans are recorded by default; pass WithSpans(false) to disable them.

func ParseEntry

func ParseEntry(source string, opts ...Option) ast.Entry

ParseEntry parses the first Message or Term in source, skipping any preceding comments. It returns ast.Junk for unparseable input.

func Serialize

func Serialize(resource *ast.Resource, opts ...SerializerOption) string

Serialize renders a resource to canonical Fluent source. Junk is omitted unless WithJunk(true) is supplied.

func Transform

func Transform(t Transformer, node ast.Node) ast.Node

Transform applies t to node and its descendants, rewriting children in place. It mirrors Transformer.visit + genericVisit. If t returns nil for the root node, Transform returns nil.

func Walk

func Walk(v Visitor, node ast.Node)

Walk visits node with v, then (if v returned true) descends into each child node in declaration order. It corresponds to Visitor.visit + genericVisit.

Types

type Option

type Option func(*Parser)

Option configures a Parser.

func WithSpans

func WithSpans(enabled bool) Option

WithSpans enables or disables span recording. The default is true, matching @fluent/syntax.

type ParseError

type ParseError struct {
	Code    string
	Args    []any
	Message string
}

ParseError is a recoverable parse error carrying a Fluent error code (E0001..) and the formatted human-readable message. During a full Parse these are not returned to the caller; instead they become Annotations on Junk entries.

func (*ParseError) Error

func (e *ParseError) Error() string

type Parser

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

Parser is a recursive-descent parser for Fluent, a faithful port of the @fluent/syntax FluentParser. Construct one with NewParser, or use the package-level Parse / ParseEntry helpers.

func NewParser

func NewParser(opts ...Option) *Parser

NewParser builds a parser with the given options. Spans are enabled by default.

func (*Parser) Parse

func (p *Parser) Parse(source string) *ast.Resource

Parse performs a full parse with junk recovery. It never returns an error; invalid entries become Junk carrying Annotations.

func (*Parser) ParseEntry

func (p *Parser) ParseEntry(source string) ast.Entry

ParseEntry parses the first Message or Term in source, skipping preceding comments. Unparseable input yields ast.Junk.

type Serializer

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

Serializer renders an AST back to canonical Fluent source. It is a port of the @fluent/syntax FluentSerializer.

func NewSerializer

func NewSerializer(opts ...SerializerOption) *Serializer

NewSerializer builds a serializer. Junk is omitted by default.

func (*Serializer) Serialize

func (s *Serializer) Serialize(resource *ast.Resource) string

Serialize renders a whole resource.

type SerializerOption

type SerializerOption func(*Serializer)

SerializerOption configures a Serializer.

func WithJunk

func WithJunk(enabled bool) SerializerOption

WithJunk includes Junk entries in the serialized output.

type Transformer

type Transformer interface {
	// Transform returns the replacement for node (possibly node itself), or nil
	// to remove it.
	Transform(node ast.Node) ast.Node
}

Transformer is a read-and-write visitor, a port of Transformer from visitor.ts. Transform is called for each node; the returned node replaces the original in the tree, and a nil return removes it. Return the node unchanged to keep it.

type Visitor

type Visitor interface {
	// Visit is called for a node. Return true to let Walk descend into the
	// node's children automatically.
	Visit(node ast.Node) (descend bool)
}

Visitor is a read-only AST visitor, a port of the Visitor base class from visitor.ts. Implementations receive each visited node via Visit. Returning true descends into the node's children via the generic walk; returning false stops descent for that subtree (the implementation is then responsible for any custom traversal, e.g. by calling Walk on selected children).

This is the idiomatic Go shape of the reference's "add a visit{Type} method, then call genericVisit to descend" pattern: switch on the concrete node type inside Visit and return whether to auto-descend.