ast

README

xelf/ast

Xelf needs a simple and minimal syntax that supports JSON based literals, types and expressions.

Accepting plain JSON as valid literals makes it very simple to interoperate with existing code, databases, and user assumptions. We already predefined JSON tokens:

• null, true, false as symbols
• char uses ""
• list uses []
• dict uses {}
• tags uses :

Xelf literals use a superset of JSON with additional rules to make handwriting literals easier:

• char can use single quotes. Single quotes str literals are the default xelf format, because xelf is often used inside strings in other languages
• char can use backtick quoted multiline string literals without escape sequence. This is helpful for templates and other pre-formatted multiline strings.
• the comma separator is optional, whitespaces work just as well and don't clutter the output
• tag keys do not need to be quoted if they are simple names as defined by the cor package
• short flag tags can omit the value (eq (obj flag;) (obj flag:true))

We need to fit in types and expressions and only have parenthesis and angle brackets left:

• exp uses () because it is familiar to write, needs less escaping and looks like a lisp. exp borrows tag notation form dict literals (let a:1 b:2 (add a b))
• typ uses <> because we don't need it much and can mostly inferred in problematic contexts <list|obj id:int name:str score:real date:time>

Composite literals can only contain other literals, but not symbols or calls. Forms must be used to construct literals from expressions. This makes it visually more obvious whether something is a literal, type or expression.

We use a token lexer and a scanner to scan an abstract syntax tree that can be used by the lit, typ and exp packages to parse language elements.

The Ast stores the source position and optionally a input source name. Line based positions are used because it is more likely to stay correct after small changes and more meaningful to a human when printed. We provide a list of line offsets to recalculate the source offset for ever line position.

Documentation

Overview

Package ast provides a token lexer and ast scanner for xelf.

Index

• Constants
• type Ast
  • func Read(r io.Reader, name string) (Ast, error)
  • func ReadAll(r io.Reader, name string) ([]Ast, error)
  • func Scan(l *Lexer) (Ast, error)
  • func ScanAll(l *Lexer) (res []Ast, _ error)
  • func ScanRest(l *Lexer, t Tok) (Ast, error)
  • func UnquotePair(e Ast) (key string, val Ast, err error)
  • func (n *Ast) Print(b *bfr.P) error
  • func (n Ast) String() string
• type Doc
• type Error
  • func ErrAdjZero(t Tok) *Error
  • func ErrEval(s Src, name string, err error) *Error
  • func ErrExpect(a Ast, kind knd.Kind) *Error
  • func ErrExpectSym(a Ast) *Error
  • func ErrExpectTag(a Ast) *Error
  • func ErrInvalid(a Ast, kind knd.Kind, err error) *Error
  • func ErrInvalidBool(a Ast) *Error
  • func ErrInvalidParams(a Ast) *Error
  • func ErrInvalidSep(t Tok) *Error
  • func ErrInvalidTag(t Tok) *Error
  • func ErrInvalidType(s Src, raw string) *Error
  • func ErrLayout(s Src, t fmt.Stringer, err error) *Error
  • func ErrNumExpo(t Tok) *Error
  • func ErrNumFrac(t Tok) *Error
  • func ErrReslSpec(s Src, name string, err error) *Error
  • func ErrReslSym(s Src, sym string, err error) *Error
  • func ErrReslTyp(s Src, t interface{}, err error) *Error
  • func ErrStrTerm(t Tok) *Error
  • func ErrTokStart(t Tok) *Error
  • func ErrTreeTerm(t Tok) *Error
  • func ErrUnexpected(a Ast) *Error
  • func ErrUnexpectedExp(s Src, e interface{}) *Error
  • func ErrUnify(s Src, name string) *Error
  • func ErrUnquote(t Tok, err error) *Error
  • func ErrUserErr(s Src, name string, err error) *Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type Formatter
• type Lexer
  • func NewLexer(r io.Reader, name string) *Lexer
  • func (l *Lexer) Tok() (Tok, error)
• type Pos
• type SimpleFormat
  • func (f *SimpleFormat) Format(w bfr.Writer, a Ast) error
• type Src
  • func (s Src) String() string
• type Tok
  • func (t Tok) String() string

Constants

const (
	FmtMin uint16 = 1 << iota
	FmtMax
	FmtLst
)

Types

type Ast

type Ast struct {
	Tok
	Seq []Ast
}

func Read

func Read(r io.Reader, name string) (Ast, error)

Read returns the next ast read from r or an error.

func ReadAll

func ReadAll(r io.Reader, name string) ([]Ast, error)

func Scan

func Scan(l *Lexer) (Ast, error)

Scan returns the next Ast from l or an error.

func ScanAll

func ScanAll(l *Lexer) (res []Ast, _ error)

func ScanRest

func ScanRest(l *Lexer, t Tok) (Ast, error)

func UnquotePair

func UnquotePair(e Ast) (key string, val Ast, err error)

func (*Ast) Print

func (n *Ast) Print(b *bfr.P) error

func (Ast) String

func (n Ast) String() string

type Doc

type Doc struct {
	Name  string
	Lines []int32
}

type Error

type Error struct {
	Src  Src
	Code uint
	Name string
	Help string
	Err  error
}

Error in addition to a name has a source position, error code and optional help message.

func ErrAdjZero

func ErrAdjZero(t Tok) *Error

func ErrEval

func ErrEval(s Src, name string, err error) *Error

func ErrExpect

func ErrExpect(a Ast, kind knd.Kind) *Error

func ErrExpectSym

func ErrExpectSym(a Ast) *Error

func ErrExpectTag

func ErrExpectTag(a Ast) *Error

func ErrInvalid

func ErrInvalid(a Ast, kind knd.Kind, err error) *Error

func ErrInvalidBool

func ErrInvalidBool(a Ast) *Error

func ErrInvalidParams

func ErrInvalidParams(a Ast) *Error

func ErrInvalidSep

func ErrInvalidSep(t Tok) *Error

func ErrInvalidTag

func ErrInvalidTag(t Tok) *Error

func ErrInvalidType

func ErrInvalidType(s Src, raw string) *Error

func ErrLayout

func ErrLayout(s Src, t fmt.Stringer, err error) *Error

func ErrNumExpo

func ErrNumExpo(t Tok) *Error

func ErrNumFrac

func ErrNumFrac(t Tok) *Error

func ErrReslSpec

func ErrReslSpec(s Src, name string, err error) *Error

func ErrReslSym

func ErrReslSym(s Src, sym string, err error) *Error

func ErrReslTyp

func ErrReslTyp(s Src, t interface{}, err error) *Error

func ErrStrTerm

func ErrStrTerm(t Tok) *Error

func ErrTokStart

func ErrTokStart(t Tok) *Error

func ErrTreeTerm

func ErrTreeTerm(t Tok) *Error

func ErrUnexpected

func ErrUnexpected(a Ast) *Error

func ErrUnexpectedExp

func ErrUnexpectedExp(s Src, e interface{}) *Error

func ErrUnify

func ErrUnify(s Src, name string) *Error

func ErrUnquote

func ErrUnquote(t Tok, err error) *Error

func ErrUserErr

func ErrUserErr(s Src, name string, err error) *Error

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Formatter

type Formatter interface {
	Format(bfr.Writer, Ast) error
}

type Lexer

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

Lexer is simple token lexer.

func NewLexer

func NewLexer(r io.Reader, name string) *Lexer

New returns a new Lexer for Reader r.

func (*Lexer) Tok

func (l *Lexer) Tok() (Tok, error)

Token reads and returns the next token or an error.

type Pos

type Pos struct {
	Line int32 // line number 1-indexed
	Byte int32 // byte offset within the line 0-indexed
}

Pos holds the line number and byte offset.

type SimpleFormat

type SimpleFormat struct {
	*bfr.P
	Flags, Max uint16
	// contains filtered or unexported fields
}

func (*SimpleFormat) Format

func (f *SimpleFormat) Format(w bfr.Writer, a Ast) error

type Src

type Src struct {
	*Doc
	Pos
	End Pos
}

Src spans from input position to an end position.

func (Src) String

func (s Src) String() string

type Tok

type Tok struct {
	Kind knd.Kind
	Rune rune
	Raw  string
	Src  Src
}

Tok is a lexer token with either a single rune or the raw string.

func (Tok) String

func (t Tok) String() string