Package sxir/pkg/grammar
import "syntaxir.dev/sxir/pkg/grammar"
Generated from the source of this version. Also on pkg.go.dev.
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
Variablesfunc Convertfunc Formatfunc FormatActionExprfunc FormatActionExprContextfunc FormatContextfunc FormatExprfunc FormatExprContextfunc FormatSyntaxfunc FormatTypefunc FormatTypeContextfunc Loadfunc Validatetype Encodingtype Sourcefunc FromBytesfunc FromFSfunc FromReaderfunc FromStringfunc (Source) Asfunc (Source) Decidefunc (Source) Encodingfunc (Source) Nametype SyntaxErrortype SyntaxErrors
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.