libparser

README

Tomefile Parser

Library to parse Tomefile code and output a node tree for use by another program.

• Features
• Usage

Features

• Parsing libparser.Parse(...) — Parses the input UTF-8 stream into a node tree
• Formatting libparser.Format(...) — Formats the input UTF-8 stream returning a slice of segments. Used to substitute environmental, local, and such variables.
• Post-Processing func(Node) (Node, *DetailedError) — Inject functions into libparser.Parse(...) to be applied to a node before it gets appended to the tree. Returns as soon as an error is encountered. Used to validate, discard or modify nodes.

Usage

Parsing a file:

parser := libparser.New(
    "example.tome",
    bufio.NewReader(file),
    libparser.PostNoShebang,  // remove UNIX shebang, e.g. #!/bin/tome
    libparser.PostExclude[*libparser.DirectiveNode], // let's say we want to exclude a specific node type
)
tree, err := parser.Parse()
if err != nil {
    err.BeautyPrint(os.Stderr)
    os.Exit(1)
}

// [tree] is [*libparser.NodeTree]

Formatting a variable (i.e. $name ${name:mod} etc.)

formatter := libparser.NewStringFormatter(
    bufio.NewReader(strings.NewReader(
        "this is an example $string with ${string:trim_suffix 123}",
    )),
)

segments, err := formatter.Format()
if err != nil {
    err.BeautyPrint(os.Stderr)
    os.Exit(1)
}

// [segments] is [[]libparser.Segment]

Documentation

Index

• Constants
• Variables
• func PostExclude[T Node](node Node) (Node, *DetailedError)
• func PostNoShebang(node Node) (Node, *DetailedError)
• type CallNode
  • func (node *CallNode) Node() string
• type CommentNode
  • func (node *CommentNode) Node() string
• type DetailedError
  • func (err *DetailedError) BeautyPrint(writer io.Writer)
  • func (err *DetailedError) Error() string
  • func (err *DetailedError) GetBeautyPrinted() string
• type DirectiveNode
  • func (node *DirectiveNode) Node() string
• type ExecNode
  • func (node *ExecNode) Node() string
• type LiteralNode
  • func (node *LiteralNode) Eval(_ Locals) (string, error)
  • func (node *LiteralNode) Node() string
• type Locals
• type Node
• type NodeArgs
• type NodeChildren
• type NodeTree
• type Parser
  • func New(name string, reader *bufio.Reader, processors ...PostProcessor) *Parser
  • func (parser *Parser) NewNested(name string, reader *bufio.Reader, processors ...PostProcessor) *Parser
  • func (parser *Parser) Parse() (*NodeTree, *DetailedError)
• type PostProcessor
• type Segment
• type StringFormatter
  • func NewStringFormatter(reader *bufio.Reader) *StringFormatter
  • func (formatter *StringFormatter) Format() ([]Segment, *DetailedError)
• type StringModifier
  • func GetModifier(name string, args []string) StringModifier
• type StringNode
  • func (node *StringNode) Node() string
• type TraceItem
• type VariableSegment
  • func (segment *VariableSegment) Eval(locals Locals) (string, error)

Constants

const (
	ERROR_READING    = "Reading Error"
	ERROR_SYNTAX     = "Syntax Error"
	ERROR_INTERNAL   = "Internal Error"
	ERROR_FORMATTING = "Formatting Error"
)

Variables

var EOF = &DetailedError{Name: "EOF"}

Functions

func PostExclude

func PostExclude[T Node](node Node) (Node, *DetailedError)

Discards nodes of type [T] from the tree

func PostNoShebang

func PostNoShebang(node Node) (Node, *DetailedError)

Discards shebang (unix) comment

Types

type CallNode

type CallNode struct {
	Macro string

	NodeArgs
}

An executable external program

func (*CallNode) Node

func (node *CallNode) Node() string

type CommentNode

type CommentNode struct {
	Contents string
}

Can be used for documentation

func (*CommentNode) Node

func (node *CommentNode) Node() string

type DetailedError

type DetailedError struct {
	Name    string
	Details string

	Trace   []TraceItem
	Context string
}

func (*DetailedError) BeautyPrint

func (err *DetailedError) BeautyPrint(writer io.Writer)

func (*DetailedError) Error

func (err *DetailedError) Error() string

func (*DetailedError) GetBeautyPrinted

func (err *DetailedError) GetBeautyPrinted() string

type DirectiveNode

type DirectiveNode struct {
	Name string

	NodeArgs
	NodeChildren
}

func (*DirectiveNode) Node

func (node *DirectiveNode) Node() string

type ExecNode

type ExecNode struct {
	Binary string

	NodeArgs
}

An executable external program

func (*ExecNode) Node

func (node *ExecNode) Node() string

type LiteralNode

type LiteralNode struct {
	Contents string
}

A literal string does not get modified in any way.

func (*LiteralNode) Eval

func (node *LiteralNode) Eval(_ Locals) (string, error)

func (*LiteralNode) Node

func (node *LiteralNode) Node() string

type Locals

type Locals map[string]string

type Node

type Node interface {
	Node() string
}

type NodeArgs

type NodeArgs []Node

type NodeChildren

type NodeChildren []Node

type NodeTree

type NodeTree struct {
	Tomes map[string]Node

	NodeChildren
}

type Parser

type Parser struct {
	Name string
	// contains filtered or unexported fields
}

func New

func New(name string, reader *bufio.Reader, processors ...PostProcessor) *Parser

func (*Parser) NewNested

func (parser *Parser) NewNested(
	name string,
	reader *bufio.Reader,
	processors ...PostProcessor,
) *Parser

func (*Parser) Parse

func (parser *Parser) Parse() (*NodeTree, *DetailedError)

type PostProcessor

type PostProcessor func(Node) (Node, *DetailedError)

type Segment

type Segment interface {
	Eval(Locals) (string, error)
}

type StringFormatter

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

func NewStringFormatter

func NewStringFormatter(reader *bufio.Reader) *StringFormatter

func (*StringFormatter) Format

func (formatter *StringFormatter) Format() ([]Segment, *DetailedError)

type StringModifier

type StringModifier func(string) string

func GetModifier

func GetModifier(name string, args []string) StringModifier

type StringNode

type StringNode struct {
	Contents string

	// Holds segments generated by [libparser.StringFormatter]
	//
	// WARN: Parse() does NOT set it by default.
	// Used by other libraries such as `lib-validator` as part of post-processing
	Segments []Segment
}

A string that can have variable expansions inside. Uses backticks (`) instead of quotes.

func (*StringNode) Node

func (node *StringNode) Node() string

type TraceItem

type TraceItem struct {
	Name     string
	Col, Row uint
}

type VariableSegment

type VariableSegment struct {
	Name       string
	Modifier   StringModifier
	IsOptional bool
}

func (*VariableSegment) Eval

func (segment *VariableSegment) Eval(locals Locals) (string, error)