package parse

import "src.elv.sh/pkg/parse"

Package parse implements parsing of Elvish code.

The entrypoint of this package is Parse and the more low-level ParseAs.

This package defines many types that implement the Node interface, Chunk being the root node. Each node can be thought of as a AST/parse tree hybrid:

• To access the semantically relevant information of a node (as an AST), use its exported fields.

• To access all its children (as a parse tree), call Children.

Internally, this package uses a handwritten recursive-descent parser. There's no separate tokenization phase; the parser consumes the source text directly.

Index ¶

• func IsInlineWhitespace(r rune) bool
• func IsWhitespace(r rune) bool
• func ParseAs(src Source, n Node, cfg Config) error
• func Quote(s string) string
• func QuoteCommandName(s string) string
• func QuoteVariableName(s string) string
• func SourceText(n Node) string
• func ValidLHSVariable(p *Primary, allowSigil bool) bool
• type Array
• func (n *Array) Range() diag.Ranging
• type Chunk
• func (n *Chunk) Range() diag.Ranging
• type Compound
• func (n *Compound) Range() diag.Ranging
• type Config
• type Error
• func UnpackErrors(e error) []*Error
• type ErrorTag
• func (ErrorTag) ErrorTag() string
• type ExprCtx
• func (i ExprCtx) String() string
• type Filter
• func (n *Filter) Range() diag.Ranging
• type Form
• func (n *Form) Range() diag.Ranging
• type Indexing
• func (n *Indexing) Range() diag.Ranging
• type MapPair
• func (n *MapPair) Range() diag.Ranging
• type Node
• func Children(n Node) []Node
• func Parent(n Node) Node
• type Pipeline
• func (n *Pipeline) Range() diag.Ranging
• type Primary
• func (n *Primary) Range() diag.Ranging
• type PrimaryType
• func QuoteAs(s string, q PrimaryType) (string, PrimaryType)
• func (i PrimaryType) String() string
• type Redir
• func (n *Redir) Range() diag.Ranging
• type RedirMode
• func (i RedirMode) String() string
• type Sep
• func NewSep(src string, begin, end int) *Sep
• func (n *Sep) Range() diag.Ranging
• type Source
• func SourceForTest(code string) Source
• func (src Source) IsStructMap()
• type Tree
• func Parse(src Source, cfg Config) (Tree, error)

Functions ¶

func IsInlineWhitespace ¶

func IsInlineWhitespace(r rune) bool

IsInlineWhitespace reports whether r is an inline whitespace character. Currently this includes space (Unicode 0x20) and tab (Unicode 0x9).

func IsWhitespace ¶

func IsWhitespace(r rune) bool

IsWhitespace reports whether r is a whitespace. Currently this includes inline whitespace characters and newline (Unicode 0xa).

func ParseAs ¶

func ParseAs(src Source, n Node, cfg Config) error

ParseAs parses the given source as a node, depending on the dynamic type of n. The returned error may contain one or more parse error, which can be unpacked with UnpackErrors.

func Quote ¶

func Quote(s string) string

Quote returns a valid Elvish expression that evaluates to the given string. If s is a valid bareword, it is returned as is; otherwise it is quoted, preferring the use of single quotes.

func QuoteCommandName ¶

func QuoteCommandName(s string) string

QuoteCommandName is like Quote, but uses the slightly laxer rule for what can appear in a command name unquoted, like <.

func QuoteVariableName ¶

func QuoteVariableName(s string) string

QuoteVariableName is like Quote, but quotes s if it contains any character that may not appear unquoted in variable names.

func SourceText ¶

func SourceText(n Node) string

SourceText returns the part of the source text that parses to the node.

func ValidLHSVariable ¶

func ValidLHSVariable(p *Primary, allowSigil bool) bool

ValidLHSVariable returns whether a Primary node containing a variable name being used as the LHS of an assignment form without the $ prefix is valid.

Types ¶

type Array ¶

type Array struct {
	Compounds []*Compound
	// When non-empty, records the occurrences of semicolons by the indices of
	// the compounds they appear before. For instance, [; ; a b; c d;] results
	// in Semicolons={0 0 2 4}.
	Semicolons []int
	// contains filtered or unexported fields
}

Array = { Space | '\n' } { Compound { Space | '\n' } }

func (*Array) Range ¶

func (n *Array) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type Chunk ¶

type Chunk struct {
	Pipelines []*Pipeline
	// contains filtered or unexported fields
}

Chunk = { PipelineSep | Space } { Pipeline { PipelineSep | Space } }

func (*Chunk) Range ¶

func (n *Chunk) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type Compound ¶

type Compound struct {
	ExprCtx   ExprCtx
	Indexings []*Indexing
	// contains filtered or unexported fields
}

Compound = { Indexing }

func (*Compound) Range ¶

func (n *Compound) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type Config ¶

type Config struct {
	// Destination of warnings. If nil, warnings are suppressed.
	WarningWriter io.Writer
}

Config keeps configuration options when parsing.

type Error ¶

type Error = diag.Error[ErrorTag]

Error is a parse error.

func UnpackErrors ¶

func UnpackErrors(e error) []*Error

UnpackErrors returns the constituent parse errors if the given error contains one or more parse errors. Otherwise it returns nil.

type ErrorTag ¶

type ErrorTag struct{}

ErrorTag parameterizes diag.Error to define Error.

func (ErrorTag) ErrorTag ¶

func (ErrorTag) ErrorTag() string

type ExprCtx ¶

type ExprCtx int

ExprCtx represents special contexts of expression parsing.

const (
	// NormalExpr represents a normal expression, namely none of the special
	// ones below. It is the default value.
	NormalExpr ExprCtx = iota
	// CmdExpr represents an expression used as the command in a form. In this
	// context, unquoted <>*^ are treated as bareword characters.
	CmdExpr
	// LHSExpr represents an expression used as the left-hand-side in either
	// assignments or map pairs. In this context, an unquoted = serves as an
	// expression terminator and is thus not treated as a bareword character.
	LHSExpr
	// BracedElemExpr represents an expression used as an element in a braced
	// expression. In this context, an unquoted , serves as an expression
	// terminator and is thus not treated as a bareword character.
	BracedElemExpr
)

func (ExprCtx) String ¶

func (i ExprCtx) String() string

type Filter ¶

type Filter struct {
	Args []*Compound
	Opts []*MapPair
	// contains filtered or unexported fields
}

Filter is the Elvish filter DSL. It uses the same syntax as arguments and options to a command.

func (*Filter) Range ¶

func (n *Filter) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type Form ¶

type Form struct {
	Head   *Compound
	Args   []*Compound
	Opts   []*MapPair
	Redirs []*Redir
	// contains filtered or unexported fields
}

Form = { Compound-CmdExpr } { Space } { ( Compound | MapPair | Redir ) { Space } }

func (*Form) Range ¶

func (n *Form) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type Indexing ¶

type Indexing struct {
	ExprCtx ExprCtx
	Head    *Primary
	Indices []*Array
	// contains filtered or unexported fields
}

Indexing = Primary { '[' Array ']' }

func (*Indexing) Range ¶

func (n *Indexing) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type MapPair ¶

type MapPair struct {
	Key, Value *Compound
	// contains filtered or unexported fields
}

MapPair = '&' { Space } Compound { Space } Compound

func (*MapPair) Range ¶

func (n *MapPair) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type Node ¶

type Node interface {
	diag.Ranger
	// contains filtered or unexported methods
}

Node represents a parse tree as well as an AST.

func Children ¶

func Children(n Node) []Node

Children returns all children of the node in the parse tree.

func Parent ¶

func Parent(n Node) Node

Parent returns the parent of a node. It returns nil if the node is the root of the parse tree.

type Pipeline ¶

type Pipeline struct {
	Forms      []*Form
	Background bool
	// contains filtered or unexported fields
}

Pipeline = Form { '|' Form }

func (*Pipeline) Range ¶

func (n *Pipeline) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type Primary ¶

type Primary struct {
	ExprCtx ExprCtx
	Type    PrimaryType
	// The unquoted string value. Valid for Bareword, SingleQuoted,
	// DoubleQuoted, Variable, Wildcard and Tilde.
	Value    string
	Elements []*Compound // Valid for List and Lambda
	Chunk    *Chunk      // Valid for OutputCapture, ExitusCapture and Lambda
	MapPairs []*MapPair  // Valid for Map and Lambda
	Braced   []*Compound // Valid for Braced
	// contains filtered or unexported fields
}

Primary is the smallest expression unit.

func (*Primary) Range ¶

func (n *Primary) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type PrimaryType ¶

type PrimaryType int

PrimaryType is the type of a Primary.

const (
	BadPrimary PrimaryType = iota
	Bareword
	SingleQuoted
	DoubleQuoted
	Variable
	Wildcard
	Tilde
	ExceptionCapture
	OutputCapture
	List
	Lambda
	Map
	Braced
)

Possible values for PrimaryType.

func QuoteAs ¶

func QuoteAs(s string, q PrimaryType) (string, PrimaryType)

QuoteAs returns a representation of s in Elvish syntax, preferring the syntax specified by q, which must be one of Bareword, SingleQuoted, or DoubleQuoted. It returns the quoted string and the actual quoting.

func (PrimaryType) String ¶

func (i PrimaryType) String() string

type Redir ¶

type Redir struct {
	Left      *Compound
	Mode      RedirMode
	RightIsFd bool
	Right     *Compound
	// contains filtered or unexported fields
}

Redir = { Compound } { '<'|'>'|'<>'|'>>' } { Space } ( '&'? Compound )

func (*Redir) Range ¶

func (n *Redir) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type RedirMode ¶

type RedirMode int

RedirMode records the mode of an IO redirection.

const (
	BadRedirMode RedirMode = iota
	Read
	Write
	ReadWrite
	Append
)

Possible values for RedirMode.

func (RedirMode) String ¶

func (i RedirMode) String() string

type Sep ¶

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

Sep is the catch-all node type for leaf nodes that lack internal structures and semantics, and serve solely for syntactic purposes. The parsing of separators depend on the Parent node; as such it lacks a genuine parse method.

func NewSep ¶

func NewSep(src string, begin, end int) *Sep

NewSep makes a new Sep.

func (*Sep) Range ¶

func (n *Sep) Range() diag.Ranging

Range returns the range within the full source text that parses to the node.

type Source ¶

type Source struct {
	Name   string
	Code   string
	IsFile bool
}

Source describes a piece of source code.

func SourceForTest ¶

func SourceForTest(code string) Source

SourceForTest returns a Source used for testing.

func (Source) IsStructMap ¶

func (src Source) IsStructMap()

IsStructMap marks that Source is a structmap.

type Tree ¶

type Tree struct {
	Root   *Chunk
	Source Source
}

Tree represents a parsed tree.

func Parse ¶

func Parse(src Source, cfg Config) (Tree, error)

Parse parses the given source. The returned error may contain one or more parse error, which can be unpacked with UnpackErrors.

Source Files ¶

node.go parse.go parser.go pprint.go quote.go source.go zstring.go

Directories ¶