parser

Documentation

Index

• Variables
• func ParseQuery(query string, options ...Option) (ast.Node, error)
• func ParseQueryReader(r io.Reader, options ...Option) (ast.Node, error)
• type MessageTape
  • func (mt *MessageTape) Error(msg string, v ...any)
  • func (mt *MessageTape) ErrorAt(where ast.Pos, msg string, v ...any)
  • func (mt *MessageTape) ErrorWith(node Positioned, msg string, v ...any)
  • func (mt *MessageTape) Hint(msg string, v ...any)
  • func (mt *MessageTape) HintAt(where ast.Pos, msg string, v ...any)
  • func (mt *MessageTape) HintWith(node Positioned, msg string, v ...any)
  • func (mt *MessageTape) Warning(msg string, v ...any)
  • func (mt *MessageTape) WarningAt(where ast.Pos, msg string, v ...any)
  • func (mt *MessageTape) WarningWith(node Positioned, msg string, v ...any)
• type MessageType
  • func (t *MessageType) MarshalJSON() ([]byte, error)
• type MessageVisitor
  • func NewMessageVisitor(f func(ast.Node, *MessageTape) error) *MessageVisitor
  • func (mv *MessageVisitor) Messages() []*ParserMessage
  • func (mv *MessageVisitor) Visit(node ast.Node) error
• type Option
  • func Debug() Option
  • func Visitors(visitors ...Visitor) Option
• type ParseError
  • func ErrorAt(pos ast.Pos, message string) *ParseError
  • func ErrorWith(node Positioned, message string) *ParseError
• type ParserMessage
  • func (p *ParserMessage) Message() string
  • func (p *ParserMessage) Pos() ast.Pos
  • func (p *ParserMessage) String() string
• type ParserOpts
• type Positioned
• type Visitor
• type VisitorFunc
  • func (vf VisitorFunc) Visit(node ast.Node) error

Variables

var (
	Skip    = errors.New("skipping node")
	SkipAll = errors.New("skipping all remaining nodes")
)

Functions

func ParseQuery

func ParseQuery(query string, options ...Option) (ast.Node, error)

func ParseQueryReader

func ParseQueryReader(r io.Reader, options ...Option) (ast.Node, error)

Types

type MessageTape

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

MessageTape is a message appended to be used during tree-traversal.

func (*MessageTape) Error

func (mt *MessageTape) Error(msg string, v ...any)

Error adds a message to the tape that will make the query unusuable. If the message tape contains an error when the visitor is complete, the parser will return the first error in the tape if it is not already returning one.

Messages generated with this call will not have a position attached.

func (*MessageTape) ErrorAt

func (mt *MessageTape) ErrorAt(where ast.Pos, msg string, v ...any)

ErrorAt adds an error message to the tape with a query offset attached for printing.

func (*MessageTape) ErrorWith

func (mt *MessageTape) ErrorWith(node Positioned, msg string, v ...any)

ErrorWith allows using an AST node as the position basis for an error message.

func (*MessageTape) Hint

func (mt *MessageTape) Hint(msg string, v ...any)

Hint adds an informational message to the tape that is neither a warning nor an error, yet might be helpful to the user. If a particular query or regular expression is less efficient, this is the way to let the user know.

Messages generated with this call will not have a position attached.

func (*MessageTape) HintAt

func (mt *MessageTape) HintAt(where ast.Pos, msg string, v ...any)

HintAt adds a hint message to the tape with a query offset attached for printing or highlighting.

func (*MessageTape) HintWith

func (mt *MessageTape) HintWith(node Positioned, msg string, v ...any)

HintWith allows using an AST node as the position basis for a hint message.

func (*MessageTape) Warning

func (mt *MessageTape) Warning(msg string, v ...any)

Warning adds a message to the tape that is a more notable, yet still not an error.

Messages generated with this call will not have a positition attached.

func (*MessageTape) WarningAt

func (mt *MessageTape) WarningAt(where ast.Pos, msg string, v ...any)

WarningAt adds a warning message to the tape with a query offset attached for printing.

func (*MessageTape) WarningWith

func (mt *MessageTape) WarningWith(node Positioned, msg string, v ...any)

WarningWith allows using an AST node as the position basis for a warning message.

type MessageType

type MessageType int

MessageType is the type of a parser message

const (
	MsgHint MessageType
	MsgWarning
	MsgError
)

func (*MessageType) MarshalJSON

func (t *MessageType) MarshalJSON() ([]byte, error)

type MessageVisitor

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

MessageVisitor is a Visitor to generate informational messages.

func NewMessageVisitor

func NewMessageVisitor(f func(ast.Node, *MessageTape) error) *MessageVisitor

NewMessageVisitor creates a visitor that can return [ParserMessage]s for errors, warnings and hints. The function will have access to a *MessageTape type to which messages can be appended. After parsing is complete, the messages can be retrieved with the MessageVisitor.Messages method.

func (*MessageVisitor) Messages

func (mv *MessageVisitor) Messages() []*ParserMessage

Messages can be used to retrieve the messages from a MessageVisitor when the walk is complete.

func (*MessageVisitor) Visit

func (mv *MessageVisitor) Visit(node ast.Node) error

Visit implements Visitor

type Option

type Option func(*ParserOpts)

func Debug

func Debug() Option

Debug instructs the parser to print detailed parse information

func Visitors

func Visitors(visitors ...Visitor) Option

Visitors adds additional visitors to the parsing pass

type ParseError

type ParseError = grammar.ParseError

ParseError is a detailed parser error. It's a type alias to allow exporting the internal type from the generated code.

func ErrorAt

func ErrorAt(pos ast.Pos, message string) *ParseError

ErrorAt allows returning a parser error with a manually-defined position. Useful for tweaking position from a node.

func ErrorWith

func ErrorWith(node Positioned, message string) *ParseError

ErrorWith allows using an AST node as the position basis for a parser error message.

type ParserMessage

type ParserMessage struct {
	Position ast.Pos     `json:"position"`
	Msg      string      `json:"message"`
	Type     MessageType `json:"type"`
}

ParserMessage is a message output by the parser.

func (*ParserMessage) Message

func (p *ParserMessage) Message() string

func (*ParserMessage) Pos

func (p *ParserMessage) Pos() ast.Pos

func (*ParserMessage) String

func (p *ParserMessage) String() string

type ParserOpts

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

type Positioned

type Positioned interface {
	Pos() ast.Pos
}

Positioned refers to language features such as statements and identifiers that have a defined position in the query string. TODO: Consider just replacing with Pos in message and error calls for more precise control.

type Visitor

type Visitor interface {
	Visit(node ast.Node) error
}

Visitor is the interface that defines an AST visitor, which will visit nodes in a depth-first order. If it returns an error, crawling will be stopped immediately. *[ParseError]s will be treated specially and printed with the positional information. Optionally, it can also return Skip to skip visiting a particular node or SkipAll to stop processing. TODO: Global Walk method that takes a visitor and node. Ergo: nodes should have children.

type VisitorFunc

type VisitorFunc func(node ast.Node) error

VisitorFun is a function that can act as a visitor, meaning it will be called for every node in the tree, unless it chooses to skip. Non-skip errors will halt the walk immediately.

func (VisitorFunc) Visit

func (vf VisitorFunc) Visit(node ast.Node) error