README
¶
sxpf - S-Expression Framework
This is a framework to work with s-expressions.
If you are looking to the previous work, please take a look at branch v0.
Types
Sxpf support the following atomic, immutable types:
- Numbers contain numeric values.
Currently, only integer values are supported.
There is no maximum or minimum integer value.
They optionally start with a
+or-sign and contain only digits0, ...,9. - Strings are UTF-8 encoded Unicode character sequences.
They are delimited by
"characters. Special characters inside the string, like the"character itself, are escaped by the\character. - Symbols are sequences of printable / visible Unicode characters. They are typically used to bind them to values within an environment. Another use case is symbolic computation. A symbol allows to store additional values by providing an association list (a-list), a list of cons cells. Symbols can be compared for equality quite efficients, since they are interned by their associated symbol factory.
- Boolean are the symbols
TrueandFalse, interpreted as boolean values. Therefore, there are no symbols with this name. - Keywords are sequences of printable / visible Unicode characters, starting with a
&character. They are somehow in between of strings and symbols. They have a string-like value, but cannot contain special Unicode characters. They are simple enough to be like symbols, but do not contain an a-list, are not interned. They always evaluate to themself. Their use case is to act like a marker, a special value.
Sxpf supports nested lists.
A list is delimited by parentheses: ( ... ).
Within a list, all values are separated by space characters, including new line.
Lists can be nested.
Internally, lists are created by cons cells, also called pairs.
The first part of a cons cell, called "car", contains the actual value stored at the beginning of a list.
The second part, called "cdr", typically links to the next cons cell
This allows multiple lists to share elements.
A proper list is a list, where the last elements second part is the empty list.
The last element of a list may be a cons cell, where the second part references a values except a list.
Such lists are improper lists.
Since the second part may reference any value, even earlier elements of a list, lists may be circular.
Single cons cells are denoted as (X . Y), where the car references S and the cdr references Y (Y is not a list).
All other types supported by Sxpf cannot be specified via the reader.
Documentation
¶
Overview ¶
Package sxpf allows to build a custom REPL for s-expressions.
Index ¶
- Constants
- Variables
- func IsFalse(obj Object) bool
- func IsList(obj Object) bool
- func IsNil(obj Object) bool
- func IsPair(obj Object) bool
- func IsTrue(obj Object) bool
- func IsUndefined(obj Object) bool
- func NumCmp(x, y Number) int
- func Print(w io.Writer, obj Object) (int, error)
- func Repr(obj Object) string
- func WriteStrings(w io.Writer, sl ...string) (int, error)
- type Boolean
- type Environment
- type ErrEnvFrozen
- type ErrImproper
- type Int64
- type Keyword
- type List
- func (lst *List) AppendBang(obj Object) *List
- func (lst *List) Assoc(obj Object) *List
- func (lst *List) Car() Object
- func (lst *List) Cdr() Object
- func (cdr *List) Cons(car Object) *List
- func (lst *List) ExtendBang(obj *List) *List
- func (lst *List) Head() *List
- func (lst *List) IsAtom() bool
- func (lst *List) IsEql(other Object) bool
- func (lst *List) IsEqual(other Object) bool
- func (lst *List) IsNil() bool
- func (lst *List) Last() (Object, error)
- func (lst *List) LastPair() *List
- func (lst *List) Length() int
- func (lst *List) Print(w io.Writer) (int, error)
- func (lst *List) Repr() string
- func (lst *List) Reverse() (*List, error)
- func (lst *List) SetCdr(obj Object)
- func (lst *List) String() string
- func (lst *List) Tail() *List
- type Number
- type Object
- type Printable
- type String
- type Symbol
- func (sy *Symbol) Assoc(key Object) *List
- func (sy *Symbol) Cons(key, obj Object) *List
- func (sy *Symbol) Factory() SymbolFactory
- func (sy *Symbol) IsAtom() bool
- func (sy *Symbol) IsEql(other Object) bool
- func (sy *Symbol) IsEqual(other Object) bool
- func (sy *Symbol) IsNil() bool
- func (sy *Symbol) Name() string
- func (sy *Symbol) Repr() string
- func (sy *Symbol) String() string
- type SymbolFactory
- type Undefined
Constants ¶
const ( True = Boolean(true) False = Boolean(false) TrueString = "True" FalseString = "False" )
The two boolean values, Do not use other constants. There are defined string values other code must respect (e.g. symbol factory, reader, ...)
const MappedFactorySize = 128
MappedFactorySize is the base size of a new maped symbol factory. If more symbols are entered into the factory, it must be re-sized internally, which will consume some time.
const RootEnvironmentSize = 128
RootEnvironmentSize is the base size of the root environment. If more bindings are entered, it must be re-sized, which may consume some time.
Variables ¶
var ErrZeroNotAllowed = errors.New("number zero not allowed")
ErrZeroNotAllowed
Functions ¶
func IsFalse ¶
IsFalse returns true, if object is a false value.
A nil object, the False object or an empty string are false values.
func IsTrue ¶
IsTrue returns true, if object is a true value.
Everything except a nil object, the False object, and the empty string, is a true value.
func IsUndefined ¶
IsUndefined returns true iff the object is a undefined value
Types ¶
type Boolean ¶
type Boolean bool
Boolean represents a boolean object.
func GetBoolean ¶
GetBoolean returns the object as a boolean, if possible.
type Environment ¶
type Environment interface {
// An environment is an object by itself
Object
// String returns the local name of this environment.
String() string
// Parent allows to retrieve the parent environment. Environment is the root
// environment, nil is returned. Lookups that cannot be satisfied in an
// environment are delegated to the parent envrionment.
Parent() Environment
// Bind creates a local mapping with a given symbol and object.
// A previous mapping will be overwritten.
Bind(*Symbol, Object) error
// Lookup will search for a local binding of the given symbol. If not
// found, the search will *not* be continued in the parent environment.
// Use the global `Resolve` function, if you want a search up to the parent.
Lookup(*Symbol) (Object, bool)
// Bindings returns all bindings as an a-list in some random order.
Bindings() *List
// Unbind removes the mapping of the given symbol to an object.
Unbind(*Symbol) error
// Freeze sets the environment in a read-only state.
Freeze()
}
Environment maintains a mapping between symbols and values. Form are evaluated within environments.
func GetEnvironment ¶
func GetEnvironment(obj Object) (Environment, bool)
GetEnvironment returns the object as an environment, if possible.
func MakeChildEnvironment ¶
func MakeChildEnvironment(parent Environment, name string, baseSize int) Environment
MakeChildEnvironment creates a new environment with a given parent.
func MakeRootEnvironment ¶
func MakeRootEnvironment() Environment
MakeRootEnvironment creates a new root environment.
func RootEnv ¶
func RootEnv(env Environment) Environment
RootEnv returns the root environment of the given environment.
type ErrEnvFrozen ¶
type ErrEnvFrozen struct{ Env Environment }
ErrEnvFrozen is returned when trying to update a frozen environment.
func (ErrEnvFrozen) Error ¶
func (err ErrEnvFrozen) Error() string
type ErrImproper ¶
type ErrImproper struct{ Lst *List }
ErrImproper is signalled if an improper list is found where it is not appropriate.
func (ErrImproper) Error ¶
func (err ErrImproper) Error() string
type Int64 ¶
type Int64 int64
Int64 is a number that store 64 bit integer values.
type Keyword ¶
type Keyword string
Keyword represents a symbolic value.
A keyword is like a string, but contains only printable characters. A keyword is like a symbol, but does not allow to associate additional data. A keyword is often used as a key of an association list, as it is more lightweight compared to a string and to a symbol.
func GetKeyword ¶
GetKeyword returns the object as a keyword, if possible
type List ¶
type List struct {
// contains filtered or unexported fields
}
A list is a node containing a value for the element and a pointer to the tail. In other lisps it is often called "cons", "cons-cell", or "cell".
func AllBindings ¶
func AllBindings(env Environment) *List
AllBindings returns an a-list of all bindings in the given environment and its parent environments.
func (*List) AppendBang ¶
AppendBang updates the given list by appending a new element after its end.
func (*List) ExtendBang ¶
ExtendBang updates the given list by extending it with the second list after its end. Returns the last list node of the newly formed list beginning with `lst`, which is also the last list node of the list starting with `val`.
func (*List) IsEql ¶
IsEql compares two objects for equivalence. Two lists are eqv iff they are the same lists.
type Number ¶
Number value store numbers.
func ParseInteger ¶
ParseInteger parses the string as an integer value and returns its value as a number.
type Object ¶
type Object interface {
fmt.Stringer
// IsNil checks if the concrete object is nil.
IsNil() bool
// IsAtom returns true iff the object is an object that is not further decomposable.
IsAtom() bool
// IsEql compares two objects for atomic / shallow equality.
IsEql(Object) bool
// IsEqual compare two objects for deep equality.
IsEqual(Object) bool
// Repr returns the object representation.
Repr() string
}
Object is the generic value all s-expressions must fulfill.
type Printable ¶
type Printable interface {
// Print emits the string representation on the given Writer
Print(io.Writer) (int, error)
}
Printable is a object that has is specific representation, which is different to String().
type String ¶
type String string
String represents a string object.
type Symbol ¶
type Symbol struct {
// contains filtered or unexported fields
}
Symbol represent a symbol value.
Every symbol can store metadata with the help of Cons(). It can be retrieved using Assoc().
func (*Symbol) Factory ¶
func (sy *Symbol) Factory() SymbolFactory
Factory returns the symbol factory that created this symbol.
func (*Symbol) IsEql ¶
IsEqual compare two objects.
Two symbols are equal, if the are created by the same factory and have the same same.
type SymbolFactory ¶
type SymbolFactory interface {
// Make produces a singleton symbol from the given string.
// If the string denotes an invalid name, an error will be returned.
Make(string) (*Symbol, error)
// MustMake will produce a singleton symbol and panic if that does not work.
MustMake(string) *Symbol
// IsValidName returns true, if given name is a valid name for a symbol.
//
// The empty string is always an invalid name.
IsValidName(string) bool
// Symbols returns a sequence of all symbols managed by this factory.
Symbols() []*Symbol
// ReprSymbol returns the factory-specific representation of the given symbol.
ReprSymbol(*Symbol) string
}
SymbolFactory creates new symbols and ensures locally that there is only one symbol with a given string value. It encapsulates case-sensitiveness, and is the only way to produce a valid symbol.
func FindSymbolFactory ¶
func FindSymbolFactory(obj Object) SymbolFactory
FindSymbolFactory searches for a symbol an returns its symbol factory.
Typically, the search is done depth-first.
func MakeMappedFactory ¶
func MakeMappedFactory() SymbolFactory
MakeMappedFactory creates a new factory.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package builtins contains functions that help to build builtin functions.
|
Package builtins contains functions that help to build builtin functions. |
|
binding
Package binding contains builtins and syntax to bind values.
|
Package binding contains builtins and syntax to bind values. |
|
boolean
Package boolean contains builtins and syntax for boolean values.
|
Package boolean contains builtins and syntax for boolean values. |
|
callable
Package callable provides syntaxes and builtins to work with callables / functions / procedure.
|
Package callable provides syntaxes and builtins to work with callables / functions / procedure. |
|
cond
Package cond provides some special/builtin functions to conditionally evaluate values.
|
Package cond provides some special/builtin functions to conditionally evaluate values. |
|
define
Package define contains all syntaxes and builtins to bind values to symbols.
|
Package define contains all syntaxes and builtins to bind values to symbols. |
|
env
Package env provides some special/builtin functions to work with environments.
|
Package env provides some special/builtin functions to work with environments. |
|
equiv
Package equiv contains function to test for equivalence of objects.
|
Package equiv contains function to test for equivalence of objects. |
|
list
Package list contains all list-related builtins
|
Package list contains all list-related builtins |
|
number
Package number contains builtins to work with numbers.
|
Package number contains builtins to work with numbers. |
|
pprint
Package pprint provides some function to pretty-print objects.
|
Package pprint provides some function to pretty-print objects. |
|
quote
Package quote contains functions to use quotations These are: quote, quasiquote, unquote, unquote-splicing.
|
Package quote contains functions to use quotations These are: quote, quasiquote, unquote, unquote-splicing. |
|
timeit
Package timeit provides functions to measure evaluation.
|
Package timeit provides functions to measure evaluation. |
|
Package eval allows to evaluate s-expressions.
|
Package eval allows to evaluate s-expressions. |