parser

Documentation

Overview

Package parser is an internal package that parses template source into an abstract syntax tree.

Index

• type ASTBlock
• type ASTBroken
• type ASTNode
• type ASTObject
• type ASTRaw
  • func (n *ASTRaw) SourceLocation() SourceLoc
  • func (n *ASTRaw) SourceText() string
• type ASTSeq
  • func (n *ASTSeq) SourceLocation() SourceLoc
  • func (n *ASTSeq) SourceText() string
• type ASTTag
• type ASTText
• type ASTTrim
  • func (n *ASTTrim) SourceLocation() SourceLoc
  • func (n *ASTTrim) SourceText() string
• type BlockSyntax
• type Config
  • func NewConfig(g Grammar) Config
  • func (c *Config) Parse(source string, loc SourceLoc) (ASTNode, Error)
  • func (c *Config) ParseAudit(source string, loc SourceLoc) (ASTNode, []ParseDiag, Error)
• type Error
  • func WrapError(err error, loc Locatable) Error
• type Grammar
• type Locatable
• type ParseDiag
• type ParseDiagRelated
• type ParseError
  • func Errorf(loc Locatable, format string, a ...any) *ParseError
  • func (e ParseError) Cause() error
  • func (e *ParseError) Error() string
  • func (e ParseError) LineNumber() int
  • func (e ParseError) MarkupContext() string
  • func (e ParseError) Message() string
  • func (e ParseError) Path() string
  • func (e ParseError) Unwrap() error
• type SourceLoc
  • func (s SourceLoc) IsZero() bool
  • func (s SourceLoc) String() string
• type SyntaxError
• type Token
  • func Scan(data string, loc SourceLoc, delims []string) (tokens []Token)
  • func (c Token) SourceLocation() SourceLoc
  • func (c Token) SourceText() string
  • func (c Token) String() string
• type TokenType
  • func (i TokenType) String() string
• type TrimDirection

Types

type ASTBlock

type ASTBlock struct {
	Token

	Body    []ASTNode   // Body is the nodes before the first branch
	Clauses []*ASTBlock // E.g. else and elseif w/in an if
	// contains filtered or unexported fields
}

ASTBlock represents a {% tag %}…{% endtag %}.

type ASTBroken

type ASTBroken struct {
	Token
	ParseErr error // original compile-time error
}

ASTBroken is a node that failed to compile but does not break the block structure. It renders as an empty string. The parser emits a Diagnostic and continues. ASTBroken is produced by the audit parse path only (parseTokensAudit).

type ASTNode

type ASTNode Locatable

ASTNode is a node of an AST.

type ASTObject

type ASTObject struct {
	Token

	Expr expressions.Expression
}

ASTObject is an {{ object }} object.

type ASTRaw

type ASTRaw struct {
	Slices []string
	// contains filtered or unexported fields
}

ASTRaw holds the text between the start and end of a raw tag.

func (*ASTRaw) SourceLocation

func (n *ASTRaw) SourceLocation() SourceLoc

func (*ASTRaw) SourceText

func (n *ASTRaw) SourceText() string

type ASTSeq

type ASTSeq struct {
	Children []ASTNode
	// contains filtered or unexported fields
}

ASTSeq is a sequence of nodes.

func (*ASTSeq) SourceLocation

func (n *ASTSeq) SourceLocation() SourceLoc

func (*ASTSeq) SourceText

func (n *ASTSeq) SourceText() string

type ASTTag

type ASTTag struct {
	Token
}

ASTTag is a tag {% tag %} that is not a block start or end.

type ASTText

type ASTText struct {
	Token
}

ASTText is a text span, that is rendered verbatim.

type ASTTrim

type ASTTrim struct {
	TrimDirection
	// contains filtered or unexported fields
}

ASTTrim is a trim object.

func (*ASTTrim) SourceLocation

func (n *ASTTrim) SourceLocation() SourceLoc

func (*ASTTrim) SourceText

func (n *ASTTrim) SourceText() string

type BlockSyntax

type BlockSyntax interface {
	IsBlock() bool
	CanHaveParent(BlockSyntax) bool
	IsBlockEnd() bool
	IsBlockStart() bool
	IsClause() bool
	ParentTags() []string
	RequiresParent() bool
	TagName() string
}

BlockSyntax supplies the parser with syntax information about blocks.

type Config

type Config struct {
	expressions.Config

	Grammar Grammar
	Delims  []string
}

A Config holds configuration information for parsing and rendering.

func NewConfig

func NewConfig(g Grammar) Config

NewConfig creates a parser Config.

func (*Config) Parse

func (c *Config) Parse(source string, loc SourceLoc) (ASTNode, Error)

Parse parses a source template. It returns an AST root, that can be compiled and evaluated.

func (*Config) ParseAudit

func (c *Config) ParseAudit(source string, loc SourceLoc) (ASTNode, []ParseDiag, Error)

ParseAudit is the error-recovering variant of Parse. It returns the AST, non-fatal diagnostics (syntax errors), and a fatal error (unclosed-tag or unexpected-tag). All three may be inspected independently:

• diags contains only non-fatal issues (syntax-error); it is empty when fatalErr != nil and none occurred before it
• fatalErr is non-nil only for the two structural errors that prevent a coherent AST

type Error

type Error interface {
	error
	Cause() error
	Path() string
	LineNumber() int
	// Message returns the error message without the "Liquid error" prefix or
	// location information. Useful for re-formatting errors with a different prefix.
	Message() string
	// MarkupContext returns the source text of the token/node that produced the
	// error. For example, for a {{ expr }} node it returns the full "{{ expr }}"
	// string. Returns an empty string when no source text is available.
	MarkupContext() string
}

An Error is a syntax error during template parsing.

func WrapError

func WrapError(err error, loc Locatable) Error

WrapError wraps its argument in a parser.Error if this argument is not already a parser.Error and is not locatable.

type Grammar

type Grammar interface {
	BlockSyntax(string) (BlockSyntax, bool)
}

Grammar supplies the parser with syntax information about blocks.

type Locatable

type Locatable interface {
	SourceLocation() SourceLoc
	SourceText() string
}

A Locatable provides source location information for error reporting.

type ParseDiag

type ParseDiag struct {
	Code    string
	Message string
	Tok     Token
	Related []ParseDiagRelated
}

ParseDiag is an internal parse-time diagnostic. It is converted to the public Diagnostic type at the API boundary.

type ParseDiagRelated

type ParseDiagRelated struct {
	Loc     SourceLoc
	Message string
}

ParseDiagRelated is supplementary source info for a ParseDiag.

type ParseError

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

ParseError is a parse-time syntax error with source location information. The Error() string uses the "Liquid syntax error" prefix, matching Ruby Liquid. Use errors.As to check whether a liquid error originates from parsing.

SyntaxError is provided as a type alias so callers can use the more semantically precise name: errors.As(err, new(*parser.SyntaxError)).

func Errorf

func Errorf(loc Locatable, format string, a ...any) *ParseError

Errorf creates a parser.Error at the given source location.

func (ParseError) Cause

func (e ParseError) Cause() error

func (*ParseError) Error

func (e *ParseError) Error() string

Error overrides sourceLocError.Error to use the "Liquid syntax error" prefix. This matches Ruby Liquid, where parse-time errors are "Liquid syntax error: …".

func (ParseError) LineNumber

func (e ParseError) LineNumber() int

func (ParseError) MarkupContext

func (e ParseError) MarkupContext() string

func (ParseError) Message

func (e ParseError) Message() string

func (ParseError) Path

func (e ParseError) Path() string

func (ParseError) Unwrap

func (e ParseError) Unwrap() error

Unwrap returns the underlying cause of this error, enabling errors.As and errors.Is to walk the error chain (e.g. to find a ZeroDivisionError or UndefinedVariableError).

type SourceLoc

type SourceLoc struct {
	Pathname string
	LineNo   int
	ColNo    int // 1-based column number; 0 means not tracked
}

SourceLoc contains a Token's source location. Pathname is in the local file system; for example "dir/file.html" on Linux and macOS; "dir\file.html" on Windows.

func (SourceLoc) IsZero

func (s SourceLoc) IsZero() bool

IsZero returns a boolean indicating whether the location doesn't have a set path.

func (SourceLoc) String

func (s SourceLoc) String() string

type SyntaxError

type SyntaxError = ParseError

SyntaxError is an alias for ParseError. Both names refer to the same type; errors.As patterns using either *ParseError or *SyntaxError are equivalent.

type Token

type Token struct {
	Type      TokenType
	SourceLoc SourceLoc
	EndLoc    SourceLoc // End location (exclusive) of this token; zero if not tracked.
	Name      string    // Name is the tag name of a tag Chunk. E.g. the tag name of "{% if 1 %}" is "if".
	Args      string    // Parameters is the tag arguments of a tag Chunk. E.g. the tag arguments of "{% if 1 %}" is "1".
	Source    string    // Source is the entirety of the token, including the "{{" "{%", etc. markers.
}

A Token is an object {{ a.b }}, a tag {% if a>b %}, or a text chunk (anything outside of {{}} and {%%}.)

func Scan

func Scan(data string, loc SourceLoc, delims []string) (tokens []Token)

Scan breaks a string into a sequence of Tokens.

func (Token) SourceLocation

func (c Token) SourceLocation() SourceLoc

SourceLocation returns the token's source location, for use in error reporting.

func (Token) SourceText

func (c Token) SourceText() string

SourceText returns the token's source text, for use in error reporting.

func (Token) String

func (c Token) String() string

type TokenType

type TokenType int

TokenType is the type of a Chunk

const (
	// TextTokenType is the type of a text Chunk
	TextTokenType TokenType = iota
	// TagTokenType is the type of a tag Chunk "{%…%}"
	TagTokenType
	// ObjTokenType is the type of an object Chunk "{{…}}"
	ObjTokenType
	// TrimLeftTokenType is the type of a left trim tag "-"
	TrimLeftTokenType
	// TrimRightTokenType is the type of a right trim tag "-"
	TrimRightTokenType
)

func (TokenType) String

func (i TokenType) String() string

type TrimDirection

type TrimDirection int

TrimDirection determines the trim direction of an ASTTrim object.

const (
	Left TrimDirection = iota
	Right
)