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:
- simple literals (e.g.,
\afora) - special literals (e.g.,
\newline,\tabetc.) - unicode literals (e.g.,
\u00A5for¥etc.)
- simple literals (e.g.,
- A simple
stdlibwhich 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
- Run
REPLby runningparenscommand. - Run a lisp file using
parens <filename>command. - 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
- An implementaion of a particular LISP dialect (like scheme, common-lisp etc.)
- A new dialect of LISP
TODO
- Better error reporting
- Optimization
-
Gocode 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
- type Expr
- type Float64
- type Int64
- type Keyword
- type List
- type MacroFunc
- type Module
- type Reader
- type ReaderError
- type ReaderMacro
- type Scope
- type Stream
- type String
- type Symbol
- type Vector
Constants ¶
This section is empty.
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 ¶ added in v0.0.7
Execute reads until EOF or an error from the RuneScanner and executes the read s-expressions in the given scope.
func ExecuteExpr ¶ added in v0.0.7
ExecuteExpr executes the expr in the given scope.
func ExecuteStr ¶ added in v0.0.7
ExecuteStr is a convenience wrapper for Execute.
Types ¶
type Character ¶ added in v1.0.0
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.
type Expr ¶ added in v0.0.7
Expr represents an expression.
type Float64 ¶ added in v1.0.0
type Float64 float64
Float64 represents double precision floating point numbers represented using float or scientific number formats.
type Int64 ¶ added in v1.0.0
type Int64 int64
Int64 represents integer values represented using decimal, octal, radix and hexadecimal formats.
type Keyword ¶ added in v1.0.0
type Keyword string
Keyword represents a keyword literal.
type List ¶ added in v1.0.0
type List []Expr
List represents an list of forms. Evaluating a list leads to a function invocation.
type MacroFunc ¶ added in v0.0.7
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 ¶ added in v1.0.0
type Module []Expr
Module represents a group of forms. Evaluating a module form returns the result of evaluating the last form in the list.
type Reader ¶ added in v1.0.0
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 ¶
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
ReaderError wraps the parsing error with file and positional information.
func (ReaderError) Error ¶ added in v1.0.0
func (err ReaderError) Error() string
type ReaderMacro ¶ added in v1.0.0
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.
type Stream ¶ added in v1.0.0
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 ¶ added in v1.0.0
Info returns information about the stream including file name and the position of the reader.
func (*Stream) NextRune ¶ added in v1.0.0
NextRune returns next rune from the stream and advances the stream.
func (*Stream) SkipSpaces ¶ added in v1.0.0
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.
type String ¶ added in v1.0.0
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.
type Symbol ¶ added in v1.0.0
type Symbol string
Symbol represents a name given to a value in memory.
Source Files
Directories