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
- Variables
- type BranchParser
- type Error
- type ErrorList
- type LeafParser
- type NumberKind
- type Parser
- func (p *Parser) Error(message string, args ...interface{})
- func (p *Parser) ErrorAt(loc cst.Fragment, message string, args ...interface{})
- func (p *Parser) Expected(value string)
- func (p *Parser) Extend(n cst.Node, do BranchParser)
- func (p *Parser) ParseBranch(b *cst.Branch, do BranchParser)
- func (p *Parser) ParseLeaf(b *cst.Branch, do LeafParser)
- type Reader
- func (r *Reader) Advance()
- func (r *Reader) AdvanceN(n int)
- func (r *Reader) AlphaNumeric() bool
- func (r *Reader) Consume() cst.Token
- func (r *Reader) EOL() bool
- func (r *Reader) GuessNextToken() cst.Token
- func (r *Reader) IsEOF() bool
- func (r *Reader) IsEOL() bool
- func (r *Reader) NotSpace() bool
- func (r *Reader) Numeric() NumberKind
- func (r *Reader) Peek() rune
- func (r *Reader) PeekN(n int) rune
- func (r *Reader) Rollback()
- func (r *Reader) Rune(value rune) bool
- func (r *Reader) SeekRune(value rune) bool
- func (r *Reader) Space() bool
- func (r *Reader) String(value string) bool
- func (r *Reader) Token() cst.Token
- type RootParser
- type Skip
- type SkipMode
Constants ¶
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 ¶
var (
// ParseErrorLimit is the maximum number of errors before a parse is aborted.
ParseErrorLimit = 10
)
Functions ¶
This section is empty.
Types ¶
type BranchParser ¶
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.
type ErrorList ¶
type ErrorList []Error
ErrorList is a convenience type for managing lists of errors.
type LeafParser ¶
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 ¶
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 ¶
ErrorAt is like Error, except because it is handed a fragment, it will not try to consume anything itself.
func (*Parser) Expected ¶
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.
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 (*Reader) AlphaNumeric ¶
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) EOL ¶
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 ¶
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) IsEOL ¶
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 ¶
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) Rollback ¶
func (r *Reader) Rollback()
Rollback sets the cursor back to the last consume point.
func (*Reader) Rune ¶
Rune advances and returns true if the next rune after the cursor matches value.
func (*Reader) SeekRune ¶
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.
type RootParser ¶ added in v1.2.0
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 ¶
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).
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 )
Source Files
Directories