parse

package
v2.0.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 8, 2021 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package parse provides support functionality for writing scannerless parsers.

The main entry point is the Parse function. It works by setting up a parser on the supplied content, and then invoking the supplied root parsing function. The CST is built for you inside the ParseLeaf and ParseBranch methods of the parser, but it is up to the supplied parsing functions to hold on to the CST if you want it, and also to build the AST.

Index

Constants

View Source
const (
	// AbortParse is paniced when a parse cannot continue. It is recovered at the
	// top level, to allow the errors to be cleanly returned to the caller.
	AbortParse = fault.Const("abort")
)

Variables

View Source
var (
	// ParseErrorLimit is the maximum number of errors before a parse is aborted.
	ParseErrorLimit = 10
)

Functions

This section is empty.

Types

type BranchParser

type BranchParser func(*cst.Branch)

BranchParser is a function that is passed to ParseBranch. It is handed the Branch to fill in, and must either succeed or add an error to the parser.

type Error

type Error struct {
	// At is the parse fragment that was being processed when the error was encountered.
	At cst.Fragment
	// Message is the message associated with the error.
	Message string
	// Stack is the captured stack trace at the point the error was noticed.
	Stack []byte
}

Error represents the information that us useful in debugging a parse failure.

func Parse

func Parse(filename, data string, skip Skip, parse RootParser) []Error

Parse is the main entry point to the parse library. Given a root parse function, the input string and the Skip controller, it builds and initializes a Parser, runs the root using it, verifies it worked correctly and then returns the errors generated if any.

func (Error) Error

func (err Error) Error() string

func (Error) Format

func (err Error) Format(f fmt.State, c rune)

type ErrorList

type ErrorList []Error

ErrorList is a convenience type for managing lists of errors.

func (*ErrorList) Add

func (l *ErrorList) Add(r *Reader, at cst.Fragment, message string, args ...interface{})

func (ErrorList) Error

func (errs ErrorList) Error() string

type LeafParser

type LeafParser func(*cst.Leaf)

LeafParser is a function that is passed to ParseLeaf. It is handed the Leaf to fill in and the Parser to fill it from, and must either succeed or add an error to the parser.

type NumberKind

type NumberKind uint8

NumberKind is a type used by Reader.Numeric for identifying various kinds of numbers.

const (
	// No number was found.
	NotNumeric NumberKind = iota
	// A decimal number.
	Decimal
	// An octal number, starting with "0". PS: A lone "0" is classified as octal.
	Octal
	// A hexadecimal number, starting with "0x".
	Hexadecimal
	// A floating point number: "123.456". Whole and the fractional parts are optional (but
	// not both at the same time).
	Floating
	// A floating point number in scientific notation: "123.456e±789". The fractional part,
	// the dot and the exponent sign are all optional.
	Scientific
)

type Parser

type Parser struct {
	Reader           // The token reader for this parser.
	Errors ErrorList // The set of errors generated during the parse.
	// contains filtered or unexported fields
}

Parser contains all the context needed while parsing. They are built for you by the Parse function.

func (*Parser) Error

func (p *Parser) Error(message string, args ...interface{})

Error adds a new error to the parser error list. It will attempt to consume a token from the reader to act as a place holder, and also to ensure progress is made in the presence of errors.

func (*Parser) ErrorAt

func (p *Parser) ErrorAt(loc cst.Fragment, message string, args ...interface{})

ErrorAt is like Error, except because it is handed a fragment, it will not try to consume anything itself.

func (*Parser) Expected

func (p *Parser) Expected(value string)

Expected is a wrapper around p.ErrorAt for the very common case of an unexpected input. It uses value as the expected input, and parses a token of the stream for the unexpected actual input.

func (*Parser) Extend

func (p *Parser) Extend(n cst.Node, do BranchParser)

Extend inserts a new branch between n and its parent, and calls do() with the newly insterted branch.

Extend will transform:

n.parent ──> n

to:

n.parent ──> b ──> n

where b is passed as the second argument to do().

func (*Parser) ParseBranch

func (p *Parser) ParseBranch(b *cst.Branch, do BranchParser)

ParseBranch adds a new Branch to b and then calls the do function to parse the branch. This is called recursively to build the node tree.

func (*Parser) ParseLeaf

func (p *Parser) ParseLeaf(b *cst.Branch, do LeafParser)

ParseLeaf adds a new Leaf to b and then calls the do function to parse the Leaf. If do is nil, a leaf will be built with the current unconsumed input.

type Reader

type Reader struct {
	Source *cst.Source // The source being parsed.
	// contains filtered or unexported fields
}

Reader is the interface to an object that converts a rune array into tokens.

func NewReader

func NewReader(filename string, data string) *Reader

NewReader creates a new reader which reads from the supplied string.

func (*Reader) Advance

func (r *Reader) Advance()

Advance moves the cursor one rune forward.

func (*Reader) AdvanceN

func (r *Reader) AdvanceN(n int)

AdvanceN moves the cursor n runes forward.

func (*Reader) AlphaNumeric

func (r *Reader) AlphaNumeric() bool

AlphaNumeric moves past anything that starts with a letter or underscore, and consists of letters, numbers or underscores. It returns true if the pattern was matched, false otherwise.

func (*Reader) Consume

func (r *Reader) Consume() cst.Token

Consume consumes the current token.

func (*Reader) EOL

func (r *Reader) EOL() bool

EOL moves the cursor past the EOL and returns true if the cursor is at the end of a line (\n or \r\n), otherwise EOL returns false and does nothing.

func (*Reader) GuessNextToken

func (r *Reader) GuessNextToken() cst.Token

GuessNextToken attempts to do a general purpose consume of a single arbitrary token from the stream. It is used by error handlers to indicate where the error occurred. It guarantees that if the stream is not finished, it will consume at least one character.

func (*Reader) IsEOF

func (r *Reader) IsEOF() bool

IsEOF returns true when the cursor is at the end of the input.

func (*Reader) IsEOL

func (r *Reader) IsEOL() bool

IsEOL returns true when the cursor is at the end of a line (\n or \r\n). IsEOL does not move the cursor.

func (*Reader) NotSpace

func (r *Reader) NotSpace() bool

NotSpace skips over any non whitespace, returning true if it advanced the cursor.

func (*Reader) Numeric

func (r *Reader) Numeric() NumberKind

Numeric tries to move past the common number pattern. It returns a constant of type NumberKind describing the kind of number it found.

func (*Reader) Peek

func (r *Reader) Peek() rune

Peek returns the next rune without advancing the cursor.

func (*Reader) PeekN

func (r *Reader) PeekN(n int) rune

PeekN returns the n'th next rune without advancing the cursor.

func (*Reader) Rollback

func (r *Reader) Rollback()

Rollback sets the cursor back to the last consume point.

func (*Reader) Rune

func (r *Reader) Rune(value rune) bool

Rune advances and returns true if the next rune after the cursor matches value.

func (*Reader) SeekRune

func (r *Reader) SeekRune(value rune) bool

SeekRune advances the cursor until either the value is found or the end of stream is reached. It returns true if it found value, false otherwise.

func (*Reader) Space

func (r *Reader) Space() bool

Space skips over any whitespace, returning true if it advanced the cursor.

func (*Reader) String

func (r *Reader) String(value string) bool

String checks to see if value occurs at cursor, if it does, it advances the cursor past it and returns true.

func (*Reader) Token

func (r *Reader) Token() cst.Token

Token peeks at the current scanned token value. It does not consume anything.

type RootParser

type RootParser func(*Parser, *cst.Branch)

RootParser is a function that is passed to Parse. It is handed the Branch to fill in and the Parser to fill it from, and must either succeed or add an error to the parser.

type Skip

type Skip func(parser *Parser, mode SkipMode) cst.Separator

Skip is the function used to skip separating tokens. A separating token is one where, as far as the parser is concerned, the tokens do not exist, even though the tokens may have been necessary to separate the lexical tokens (whitespace), or carry useful information (comments).

func NewSkip

func NewSkip(line, blockstart, blockend string) Skip

NewSkip builds a Skip function for the common case of a parser that has one type of line comment, one type of block comment, and want to treat all unicode space characters as skippable.

type SkipMode

type SkipMode int
const (
	// SkipPrefix is the skip mode that skips tokens that are associated with
	// the following lexically relevant token. This is mostly important for
	// comment association.
	SkipPrefix SkipMode = iota
	// SkipSuffix is the skip mode that skips tokens that are associated with
	// the preceding lexically relevant token. This is mostly important for
	// comment association.
	SkipSuffix
)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL