Documentation

Overview

Package parse implements the elvish parser.

The parser builds a hybrid of AST (abstract syntax tree) and parse tree (a.k.a. concrete syntax tree). The AST part only includes parts that are semantically significant -- i.e. skipping whitespaces and symbols that do not alter the semantics, and is embodied in the fields of each *Node type. The parse tree part corresponds to all the text in the original source text, and is embodied in the children of each *Node type.

Index

Constants

This section is empty.

Variables

This section is empty.

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, w io.Writer) error

ParseAs parses the given source as a node, depending on the dynamic type of n, writing deprecation warnings to the given io.Writer if it is not nil. If the error is not nil, it always has type MultiError.

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 SourceText

func SourceText(n Node) string

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

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 Assignment

type Assignment struct {
	Left  *Indexing
	Right *Compound
	// contains filtered or unexported fields
}

Assignment = Indexing '=' Compound

func (*Assignment) Range

func (n *Assignment) 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 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 Form

type Form struct {
	Assignments []*Assignment
	Head        *Compound
	// Left-hand-sides for the spacey assignment. Right-hand-sides are in Args.
	Vars   []*Compound
	Args   []*Compound
	Opts   []*MapPair
	Redirs []*Redir
	// contains filtered or unexported fields
}

Form = { Space } { { Assignment } { Space } }

{ Compound } { 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
	Indicies []*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 MultiError

type MultiError struct {
	Entries []*diag.Error
}

MultiError stores multiple Error's and can pretty print them.

func (*MultiError) Error

func (me *MultiError) Error() string

Error returns a string representation of the error.

func (*MultiError) Show

func (me *MultiError) Show(indent string) string

Show shows the error.

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 Labda
	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.

func (Source) Path

func (src Source) Path() string

Path returns src.Name if src.IsFile is true, and an empty string otherwise. It is kept for backward compatibility and will be removed after the 0.14 release.

func (Source) Repr

func (src Source) Repr(int) string

Repr returns the representation of Source as if it were a map, except that the code field is replaced by "...", since it is typically very large.

type Tree

type Tree struct {
	Root   *Chunk
	Source Source
}

Tree represents a parsed tree.

func Parse

func Parse(src Source) (Tree, error)

Parse parses the given source. The returned error always has type MultiError if it is not nil.

func ParseWithDeprecation

func ParseWithDeprecation(src Source, w io.Writer) (Tree, error)

ParseWithDeprecation is like Parse, but also writes out deprecation warnings to the given io.Writer.

Directories

Path Synopsis
parseutil Package parseutil contains utilities built on top of the parse package.