package parse

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

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

Package Files

error.go node.go parse.go parser.go pprint.go quote.go source.go string.go

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. If the error is not nil, it always has type *Error.

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

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 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 struct {
    Entries []*diag.Error
}

Error stores multiple underlying parse errors, and can pretty print them.

func GetError

func GetError(e error) *Error

GetError returns an *Error if the given error has dynamic type *Error, i.e. is returned by one of the Parse functions. Otherwise it returns nil.

func (*Error) Error

func (er *Error) Error() string

Error returns a string representation of the error.

func (*Error) Show

func (er *Error) Show(indent string) string

Show shows the error.

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
    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 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 Query

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

Query represents an Elvish query. It uses the same syntax as arguments and options to a command.

func (*Query) Range

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

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

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) 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, cfg Config) (Tree, error)

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

Package parse imports 10 packages (graph) and is imported by 10 packages. Updated now.

.
Tools for package owners.