parens

README

Parens

Parens is a LISP-like scripting layer for Go (or Golang).

Features

• Highly Customizable reader/parser through a read table (Inspired by Clojure)
• Built-in data types: string, number, character, keyword, symbol, list, vector
• Multiple number formats supported: decimal, octal, hexadecimal, radix and scientific notations.
• Full unicode support. Symbols can include unicode characters (Example: find-δ, π etc.)
• Character Literals with support for:
  1. simple literals (e.g., \a for a)
  2. special literals (e.g., \newline, \tab etc.)
  3. unicode literals (e.g., \u00A5 for ¥ etc.)
• A simple stdlib which acts as reference for extending and provides some simple useful functions and macros.

Installation

To embed Parens in your application import github.com/spy16/parens.

For stand-alone usage, install the Parens binary using:

go get -u -v github.com/spy16/parens/cmd/parens

Then you can

1. Run REPL by running parens command.
2. Run a lisp file using parens <filename> command.
3. Execute a LISP string using parens -e "(+ 1 2)"

Usage

Take a look at cmd/parens/main.go for a good example.

Check out examples/ for supported constructs.

Goals

1. Simple

Should have absolute bare minimum functionality.

scope := parens.NewScope(nil)
parens.ExecuteStr("10")

Above snippet gives you an interpreter that understands literals, (eval expr) and (load <file>).

2. Flexible

Should be possible to control what is available. Standard functions should be registered not built-in.

stdlib.RegisterAll(scope)

Adding this one line into the previous snippet allows you to include some minimal set of standard functions like +, -, *, / etc. and macros like let, cond, do etc.

The type of scope argument in any parens function is the following interface:

// Scope is responsible for managing bindings.
type Scope interface {
    Get(name string) (interface{}, error)
    Bind(name string, v interface{}, doc ...string) error
    Root() Scope
}

3. Interoperable

Should be able to expose Go values inside LISP and vice versa without custom signatures.

// any Go value can be exposed to interpreter as shown here:
scope.Bind("π", 3.1412)
scope.Bind("banner", "Hello from Parens!")

// functions can be bound directly.
// variadic functions are supported too.
scope.Bind("println", fmt.Println)
scope.Bind("printf", fmt.Printf)
scope.Bind("sin", math.Sin)

// once bound you can use them just as easily:
parens.ExecuteStr("(println banner)", scope)
parens.ExecuteStr(`(printf "value of π is = %f" π)`, scope)

4. Extensible Semantics

Special constructs like do, cond, if etc. can be added using Macros.

// This is simple implementation of '(do expr*)' special-form from Clojure!
func doMacro(scope parens.Scope, exps []parens.Expr) (interface{}, error) {
    var val interface{}
    var err error
    for _, exp := range exps {
        val, err = exp.Eval(scope)
        if err != nil {
            return nil, err
        }
    }

    return val, nil
}

// register the macro func in the scope.
scope.Bind("do", parens.MacroFunc(doMacro))

// finally use it!
src := `
(do
    (println "Hello from parens")
    (label π 3.1412))
`
// value of 'val' after below statement should be 3.1412
val, _ := parens.ExecuteStr(src, scope)

See stdlib/macros.go for some built-in macros.

Parens is NOT

1. An implementaion of a particular LISP dialect (like scheme, common-lisp etc.)
2. A new dialect of LISP

TODO

• Better error reporting
• Optimization
• Go code generation?

License

Documentation

Index

• Variables
• func Execute(rd io.Reader, env Scope) (interface{}, error)
• func ExecuteExpr(expr Expr, env Scope) (interface{}, error)
• func ExecuteStr(src string, env Scope) (interface{}, error)
• type Character
  • func (char Character) Eval(scope Scope) (interface{}, error)
  • func (char Character) String() string
• type Expr
  • func Parse(r io.Reader) (Expr, error)
  • func ParseStr(src string) (Expr, error)
• type Float64
  • func (f64 Float64) Eval(scope Scope) (interface{}, error)
  • func (f64 Float64) String() string
• type Int64
  • func (i64 Int64) Eval(scope Scope) (interface{}, error)
  • func (i64 Int64) String() string
• type Keyword
  • func (kw Keyword) Eval(scope Scope) (interface{}, error)
  • func (kw Keyword) String() string
• type List
  • func (lf List) Eval(scope Scope) (interface{}, error)
  • func (lf List) String() string
• type MacroFunc
• type Module
  • func (m Module) Eval(scope Scope) (interface{}, error)
  • func (m Module) String() string
• type Reader
  • func New(rs io.Reader) *Reader
  • func (rd *Reader) All() (Module, error)
  • func (rd *Reader) IsTerminal(r rune) bool
  • func (rd *Reader) One() (Expr, error)
  • func (rd *Reader) SetMacro(init rune, macro ReaderMacro)
• type ReaderError
  • func (err ReaderError) Error() string
• type ReaderMacro
• type Scope
  • func NewScope(parent Scope) Scope
• type Stream
  • func (stream Stream) Info() (file string, line, col int)
  • func (stream *Stream) NextRune() (rune, error)
  • func (stream *Stream) SkipSpaces() error
  • func (stream *Stream) Unread(runes ...rune)
• type String
  • func (se String) Eval(scope Scope) (interface{}, error)
  • func (se String) String() string
• type Symbol
  • func (sym Symbol) Eval(scope Scope) (interface{}, error)
  • func (sym Symbol) String() string
• type Vector
  • func (vf Vector) Eval(scope Scope) (interface{}, error)
  • func (vf Vector) String() string

Variables

var (
	// ErrNameNotFound is returned when a lookup is performed with a
	// non-bound name.
	ErrNameNotFound = errors.New("name not bound to a value")

	// ErrNotCallable is returned when a Call is attempted on a non-
	// callable value.
	ErrNotCallable = errors.New("value is not callable")

	// ErrConversionImpossible is returned when the Value type cannot be
	// converted to the expected type.
	ErrConversionImpossible = errors.New("cannot be converted")

	// ErrInvalidNumberOfArgs is returned when a function call is attempted
	// with invalid number of arguments.
	ErrInvalidNumberOfArgs = errors.New("invalid number of arguments")
)

var (
	// ErrSkip can be returned by reader macro to indicate a no-op.
	ErrSkip = errors.New("skip expr")
)

Functions

func Execute

func Execute(rd io.Reader, env Scope) (interface{}, error)

Execute reads until EOF or an error from the RuneScanner and executes the read s-expressions in the given scope.

func ExecuteExpr

func ExecuteExpr(expr Expr, env Scope) (interface{}, error)

ExecuteExpr executes the expr in the given scope.

func ExecuteStr

func ExecuteStr(src string, env Scope) (interface{}, error)

ExecuteStr is a convenience wrapper for Execute.

Types

type Character

type Character rune

Character represents a character literal. For example, \a, \b, \1, \∂ etc are valid character literals. In addition, special literals like \newline, \space etc are supported.

func (Character) Eval

func (char Character) Eval(scope Scope) (interface{}, error)

Eval returns the character value.

func (Character) String

func (char Character) String() string

type Expr

type Expr interface {
	Eval(env Scope) (interface{}, error)
}

Expr represents an expression.

func Parse

func Parse(r io.Reader) (Expr, error)

Parse parses till the EOF and returns all s-exprs as a single ModuleExpr. This should be used to build an entire module from a file or string etc.

func ParseStr

func ParseStr(src string) (Expr, error)

ParseStr is a convenience wrapper for Parse.

type Float64

type Float64 float64

Float64 represents double precision floating point numbers represented using float or scientific number formats.

func (Float64) Eval

func (f64 Float64) Eval(scope Scope) (interface{}, error)

Eval returns the underlying double-precision float value.

func (Float64) String

func (f64 Float64) String() string

type Int64

type Int64 int64

Int64 represents integer values represented using decimal, octal, radix and hexadecimal formats.

func (Int64) Eval

func (i64 Int64) Eval(scope Scope) (interface{}, error)

Eval returns the underlying integer value.

func (Int64) String

func (i64 Int64) String() string

type Keyword

type Keyword string

Keyword represents a keyword literal.

func (Keyword) Eval

func (kw Keyword) Eval(scope Scope) (interface{}, error)

Eval returns the keyword value.

func (Keyword) String

func (kw Keyword) String() string

type List

type List []Expr

List represents an list of forms. Evaluating a list leads to a function invocation.

func (List) Eval

func (lf List) Eval(scope Scope) (interface{}, error)

Eval executes the list as a function invocation.

func (List) String

func (lf List) String() string

type MacroFunc

type MacroFunc func(scope Scope, exprs []Expr) (interface{}, error)

MacroFunc represents the signature of the Go macro functions. Functions bound in the scope as MacroFunc will receive un-evaluated list of s-exps and the current scope.

type Module

type Module []Expr

Module represents a group of forms. Evaluating a module form returns the result of evaluating the last form in the list.

func (Module) Eval

func (m Module) Eval(scope Scope) (interface{}, error)

Eval evaluates all the forms and returns the result of the last evaluation.

func (Module) String

func (m Module) String() string

type Reader

type Reader struct {
	Stream

	Hook ReaderMacro
	// contains filtered or unexported fields
}

Reader provides functions to parse characters from a stream into symbolic expressions or forms.

func New

func New(rs io.Reader) *Reader

New returns a lisp reader instance which can read forms from r. Reader behavior can be customized by using SetMacro to override or remove from the default read table. File name will be inferred from the reader value and type information.

func (*Reader) All

func (rd *Reader) All() (Module, error)

All consumes characters from stream until EOF and returns a list of all the forms parsed. Any no-op forms (e.g., comment) returned will not be included in the result.

func (*Reader) IsTerminal

func (rd *Reader) IsTerminal(r rune) bool

IsTerminal returns true if the rune should terminate a form. ReaderMacro trigger runes defined in the read table and all space characters including "," are considered terminal.

func (*Reader) One

func (rd *Reader) One() (Expr, error)

One consumes characters from underlying stream until a complete form is parsed and returns the form while ignoring the no-op forms like comments. Except EOF, all errors will be wrapped with ReaderError type along with the positional information obtained using Info().

func (*Reader) SetMacro

func (rd *Reader) SetMacro(init rune, macro ReaderMacro)

SetMacro sets the given reader macro as the handler for init rune in the read table. Overwrites if a macro is already present. If the macro value given is nil, entry for the init rune will be removed from the read table.

type ReaderError

type ReaderError struct {
	Cause  error
	File   string
	Line   int
	Column int
}

ReaderError wraps the parsing error with file and positional information.

func (ReaderError) Error

func (err ReaderError) Error() string

type ReaderMacro

type ReaderMacro func(rd *Reader, init rune) (Expr, error)

ReaderMacro implementations can be plugged into the Reader to extend, override or customize behavior of the reader.

type Scope

type Scope interface {
	Get(name string) (interface{}, error)
	Bind(name string, v interface{}, doc ...string) error
	Root() Scope
}

Scope is responsible for managing bindings.

func NewScope

func NewScope(parent Scope) Scope

NewScope initializes a new scope with given parent scope. parent can be nil.

type Stream

type Stream struct {
	File string
	// contains filtered or unexported fields
}

Stream provides functions to read from a rune reader and also maintains the stream information such as filename and position in stream.

func (Stream) Info

func (stream Stream) Info() (file string, line, col int)

Info returns information about the stream including file name and the position of the reader.

func (*Stream) NextRune

func (stream *Stream) NextRune() (rune, error)

NextRune returns next rune from the stream and advances the stream.

func (*Stream) SkipSpaces

func (stream *Stream) SkipSpaces() error

SkipSpaces consumes and discards runes from stream repeatedly until a character that is not a whitespace is identified. Along with standard unicode white-space characters "," is also considered a white-space and discarded.

func (*Stream) Unread

func (stream *Stream) Unread(runes ...rune)

Unread can be used to return runes consumed from the stream back to the stream. Un-reading more runes than read is guaranteed to work but might cause inconsistency in stream positional information.

type String

type String string

String represents double-quoted string literals. String Form represents the true string value obtained from the reader. Escape sequences are not applicable at this level.

func (String) Eval

func (se String) Eval(scope Scope) (interface{}, error)

Eval returns the unquoted string value.

func (String) String

func (se String) String() string

type Symbol

type Symbol string

Symbol represents a name given to a value in memory.

func (Symbol) Eval

func (sym Symbol) Eval(scope Scope) (interface{}, error)

Eval returns the value bound for the symbol in the scope.

func (Symbol) String

func (sym Symbol) String() string

type Vector

type Vector []Expr

Vector represents a list of values. Unlike List type, evaluation of vector does not lead to function invoke.

func (Vector) Eval

func (vf Vector) Eval(scope Scope) (interface{}, error)

Eval evaluates each item in the vector and returns the result list.

func (Vector) String

func (vf Vector) String() string