libparser

README

Tomefile Parser

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

• Features
• Roadmap
• 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.

Roadmap

Things that need to be done before v1:

• Create a custom error library
• Macros example!.
• Support for ; to separate statements.
• Support && and || in commands.
• Pipes |.
• Redirects > & <.
• Better test coverage

Usage

Parsing a file:

// Close all files when all parsers have finished.
defer libparser.CloseAll()

file, err := libparser.OpenFile("example.tome")
if err != nil {
    panic(err)
}

parser := libparser.New(file).
    With(libparser.PostNoShebang).  // remove UNIX shebang, e.g. #!/bin/tome
    With(libparser.PostExclude[*libparser.CommentNode])  // let's say we want to exclude a specific node type

tree, detailed_err := parser.Parse()
if detailed_err != nil {
    detailed_err.BeautyPrint(os.Stderr)
    os.Exit(1)
}

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

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

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

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

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

Documentation

Index

• Variables
• func CloseAll()
• func OpenFile(path string) (*os.File, error)
• type CallNode
  • func (node *CallNode) Node() string
• type CommentNode
  • func (node *CommentNode) Node() string
• type DirectiveNode
  • func (node *DirectiveNode) Node() string
• type ExecNode
  • func (node *ExecNode) Node() string
• type File
• type LiteralNode
  • func (node *LiteralNode) Eval(_ Locals) (string, error)
  • func (node *LiteralNode) Node() string
• type Locals
• type Node
  • func PostExclude[T Node](node Node) (Node, *liberrors.DetailedError)
  • func PostNoShebang(node Node) (Node, *liberrors.DetailedError)
• type NodeArgs
• type NodeChildren
• type NodeTree
• type Parser
  • func New(file File) *Parser
  • func (parser *Parser) Parse() (*NodeTree, *liberrors.DetailedError)
  • func (parser *Parser) SetParent(parent *Parser) *Parser
  • func (parser *Parser) With(processor PostProcessor) *Parser
• type PostProcessor
• type Segment
• type StringFormatter
  • func NewStringFormatter(input string) *StringFormatter
  • func (formatter *StringFormatter) Format() ([]Segment, *liberrors.DetailedError)
• type StringModifier
  • func GetModifier(name string, args []string) StringModifier
• type StringNode
  • func (node *StringNode) Node() string
• type VariableSegment
  • func (segment *VariableSegment) Eval(locals Locals) (string, error)

Variables

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

var OpenedFiles = []File{}

Functions

func CloseAll

func CloseAll()

Close all OpenedFiles.

Recommended to be defered in [main], e.g. `defer libparser.CloseAll()`.

func OpenFile

func OpenFile(path string) (*os.File, error)

Recommended way of opening files for parsing.

Use `defer CloseAll()` in [main] to make sure no files are closed before parsing is finished.

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

type File interface {
	io.Reader
	Name() string
	Close() error
}

The parts of *os.File that parser cares about

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
}

func PostExclude

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

Discards nodes of type [T] from the tree

func PostNoShebang

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

Discards shebang (unix) comment

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

	PostProcessors []PostProcessor
	// contains filtered or unexported fields
}

func New

func New(file File) *Parser

func (*Parser) Parse

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

func (*Parser) SetParent

func (parser *Parser) SetParent(parent *Parser) *Parser

Used for error tracing

func (*Parser) With

func (parser *Parser) With(processor PostProcessor) *Parser

Appends the PostProcessor to be applied to every single node before it gets appended to the tree.

NOTE: Order matters (sequentially from first to last)

type PostProcessor

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

type Segment

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

type StringFormatter

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

func NewStringFormatter

func NewStringFormatter(input string) *StringFormatter

func (*StringFormatter) Format

func (formatter *StringFormatter) Format() ([]Segment, *liberrors.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 VariableSegment

type VariableSegment struct {
	Name       string
	Modifier   StringModifier
	IsOptional bool
}

func (*VariableSegment) Eval

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