Package sxir/pkg/grammar

import "syntaxir.dev/sxir/pkg/grammar"

Overview

Package grammar loads, validates, formats and converts SyntaxIR grammars.

A grammar source (Source) is one grammar input: a named value made from bytes, a string, a reader or a path in a file system, in grammar syntax or in JSON. Load gives the grammar AST of a source, which package ast defines; Format writes an AST as grammar syntax, and Convert writes a source in a given encoding. A program that builds an AST by hand checks it with Validate.

Like all of the module API at v0.x, this package may change in any release.

Index

Variables

var ErrCompiled = errors.New("a compiled grammar holds the bytecode of a parser, not the grammar source")

ErrCompiled is the error, wrapped, of loading a compiled grammar (the output of sxir compile), which holds the bytecode of a parser and not the grammar.

Functions

func Convert source

func Convert(s Source, to Encoding) ([]byte, error)

Convert returns the grammar of s in the encoding to: grammar syntax as Format writes it, or the JSON form of the AST. It returns an error for EncodingAuto and the errors of Load.

func Format source

func Format(g *ast.Grammar) string

Format writes g as grammar syntax.

Comments and line breaks recorded in the AST (see ast.LineBreak) are kept, so formatting parsed source preserves its comments. Struct field types and trailing comments on consecutive lines are aligned. A grammar without such layout information (for example, one decoded from JSON) is printed with a blank line between definitions and one item per line in blocks.

The syntax cannot write a sequence of one item or a choice of one sequence directly: written as the item or the sequence, it reads back with the value of the item or with the elements spliced into a sequence around it. Format spells the first as `x _` and the second as `s / _|_`, which read back with the same value shape and the same cost.

func FormatActionExpr source

func FormatActionExpr(t ast.ActionExpr) string

FormatActionExpr writes the action expression t of an action or a predicate as grammar syntax.

func FormatActionExprContext source

func FormatActionExprContext(ctx context.Context, t ast.ActionExpr) (string, error)

FormatActionExprContext is FormatActionExpr with cooperative cancellation, as for FormatContext.

func FormatContext source

func FormatContext(ctx context.Context, g *ast.Grammar) (string, error)

FormatContext is Format with cooperative cancellation. Cancellation returns an empty string and ctx.Err(), never partial source. The caller must not mutate g during formatting.

func FormatExpr source

func FormatExpr(e ast.Expr) string

FormatExpr writes the parser expression e as grammar syntax.

func FormatExprContext source

func FormatExprContext(ctx context.Context, e ast.Expr) (string, error)

FormatExprContext is FormatExpr with cooperative cancellation, as for FormatContext.

func FormatSyntax source

func FormatSyntax(g *ast.Grammar) string

FormatSyntax writes the parsing syntax of g without modifying it. It omits type declarations, result annotations, Value Actions, captures, metadata attributes and recovery wrappers, and keeps Predicate Actions, matching operators and other pragmas. It is a documentation view, not an equivalent grammar: a predicate may depend on an omitted capture, action or type.

func FormatType source

func FormatType(t ast.TypeExpr) string

FormatType writes the type t as grammar syntax.

func FormatTypeContext source

func FormatTypeContext(ctx context.Context, t ast.TypeExpr) (string, error)

FormatTypeContext is FormatType with cooperative cancellation, as for FormatContext.

func Load source

func Load(s Source) (*ast.Grammar, error)

Load returns the grammar AST of s, in grammar syntax or in JSON. JSON is decoded strictly, as ast.DecodeJSON does: an unknown field, a duplicate key or trailing data is an error, as is a tree that ast.Validate rejects. Load returns an error wrapping ErrCompiled for a compiled grammar, the error of reading s, or the errors of the source with their positions: SyntaxErrors for grammar syntax and the errors of ast.DecodeJSON for JSON. The errors do not name s, so a caller that reports them adds Name.

func Validate source

func Validate(g *ast.Grammar) error

Validate checks the structure of g, an AST that a program has built, as ast.Validate does.

Types

type Encoding source

type Encoding int

Encoding is the encoding of a grammar source: grammar syntax or JSON.

const (
	// EncodingAuto decides the encoding from the source: the extension of its name (.sxir or
	// .json), then its content, where JSON is content whose first byte other than a space, tab,
	// carriage return or line feed is '{', and anything else is grammar syntax.
	EncodingAuto Encoding = iota
	// EncodingSXIR is grammar syntax.
	EncodingSXIR
	// EncodingJSON is the JSON form of the grammar AST.
	EncodingJSON
)

func (Encoding) String source

func (e Encoding) String() string

String returns the name of the encoding: "auto", "sxir" or "json".

type Source source

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

Source is one grammar input, a named value with an encoding. Its fields are not exported, so a source has exactly one supplier: the constructor that made it. The zero Source is empty and unnamed.

func FromBytes source

func FromBytes(name string, data []byte) Source

FromBytes returns the source named name with the content data. The source reads data when it is loaded, so the caller must not modify data until then.

func FromFS source

func FromFS(fsys fs.FS, name string) Source

FromFS returns the source at the path name in the file system fsys. The name of the source is name, and the source reads the file when it is loaded.

func FromReader source

func FromReader(name string, r io.Reader) Source

FromReader returns the source named name that r supplies. The source reads r in full when it is first loaded, because a diagnostic may need the text of any line, and keeps what it read, so later loads of the source and of its copies give the same content (or the same read error).

func FromString source

func FromString(name, text string) Source

FromString returns the source named name with the content text.

func (Source) As source

func (s Source) As(e Encoding) Source

As returns s with the encoding e, which Load then uses instead of deciding one; As(EncodingAuto) restores the decision from the name and the content.

func (Source) Decide source

func (s Source) Decide() (Encoding, error)

Decide returns the encoding in which Load reads s: the one that As set, or else the one that EncodingAuto decides from the name and the content. It reads s as Load does and returns the same errors of reading, including ErrCompiled.

func (Source) Encoding source

func (s Source) Encoding() Encoding

Encoding returns the encoding of s that As set, or EncodingAuto.

func (Source) Name source

func (s Source) Name() string

Name returns the name of s: the name given to its constructor.

type SyntaxError source

type SyntaxError struct {
	// Pos is where the error is: a 1-based line and a 1-based column counted in characters, where
	// a tab is one character, as in the positions of the grammar AST.
	Pos ast.Pos
	// End is the position just after the text that the error covers, such as an invalid escape
	// sequence or a run of characters that start no token. It is the zero Pos for an error at the
	// point Pos, such as an expected token that is missing.
	End ast.Pos
	// Msg is the message, without the position.
	Msg string
}

SyntaxError is an error in the grammar syntax of a source: a lexical error, a syntax error, or an error of a check that the parser makes on the source, such as an invalid escape sequence.

func (*SyntaxError) Error source

func (e *SyntaxError) Error() string

Error returns the position and the message as "line:column: message".

type SyntaxErrors source

type SyntaxErrors []*SyntaxError

SyntaxErrors is the list of errors of a source in grammar syntax that Load rejects; it is never empty. The lexical errors come first, then the other errors in the order of the source. A source with more than 100 errors gives 100 of them and one more whose message is "too many errors", at the position where the errors left out begin.

Load returns the list itself, so a program obtains it with errors.As:

var errs grammar.SyntaxErrors
if errors.As(err, &errs) {
	for _, e := range errs {
		// e.Pos, e.End, e.Msg
	}
}

The list does not unwrap to its elements: errors.As always gives the whole list, never one error.

func (SyntaxErrors) Error source

func (l SyntaxErrors) Error() string

Error returns the errors, one per line.