builtin

Documentation

Overview

Package builtin provides the functions that serve as the bootstrapped routines for the system's runtime environment.

Index

• Constants
• Variables
• func Args() data.Value
• func Asm(e encoder.Encoder, args ...data.Value)
• func Env() data.Value
• func Lambda(e encoder.Encoder, args ...data.Value)
• func Let(e encoder.Encoder, args ...data.Value)
• func LetMutual(e encoder.Encoder, args ...data.Value)

Constants

const (
	// ErrUnknownDirective is raised when an unknown directive is called
	ErrUnknownDirective = "unknown directive: %s"

	// ErrUnexpectedForm is raised when an unexpected form is encountered in
	// the assembler block
	ErrUnexpectedForm = "unexpected form: %s"

	// ErrIncompleteInstruction is raised when an instruction is encountered in
	// the assembler block not accompanied by a required operand
	ErrIncompleteInstruction = "incomplete instruction: %s"

	// ErrUnknownLocalType is raised when a local or private is declared that
	// doesn't have a proper disposition (var, ref, rest)
	ErrUnknownLocalType = "unexpected local type: %s, expected: %s"

	// ErrUnexpectedParameter is raised when an encoder parameter is not found.
	// These are declared using the !make-special directive
	ErrUnexpectedParameter = "unexpected parameter name: %s"

	// ErrUnexpectedName is raised when a local name is referenced that hasn't
	// been declared as part of the assembler encoder's scope
	ErrUnexpectedName = "unexpected local name: %s"

	// ErrUnexpectedLabel is raised when a jump or cond-jump instruction refers
	// to a label that hasn't been anchored in the assembler block
	ErrUnexpectedLabel = "unexpected label: %s"

	// ErrBadNameResolution is raised when an attempt is made to bind a local
	// using an argument to the encoder that is not a Local symbol
	ErrBadNameResolution = "encoder argument is not a name: %s"
)

const (
	MakeSpecial = data.Local("!make-special")
	Resolve     = data.Local(".resolve")
	Evaluate    = data.Local(".eval")
	ForEach     = data.Local(".for-each")
	Const       = data.Local(".const")
	Local       = data.Local(".local")
	Private     = data.Local(".private")
	PushLocals  = data.Local(".push-locals")
	PopLocals   = data.Local(".pop-locals")
)

const (
	// ErrUnpairedBindings is raised when a Let binding Vector has fewer or
	// more than two elements
	ErrUnpairedBindings = "binding must be a paired vector"

	// ErrUnexpectedLetSyntax is raised when the Let bindings are not in the
	// form of a List or Vector
	ErrUnexpectedLetSyntax = "unexpected binding syntax: %s"

	// ErrNameAlreadyBound is raised when there's an attempt to bind the same
	// name more than once in a single Let scope
	ErrNameAlreadyBound = "name is already bound in local scope: %s"
)

const (
	// ErrUnexpectedCaseSyntax is raised when a call to Lambda doesn't include
	// a proper parameter case initializer. If it first encounters a Vector,
	// the parsing will assume multiple parameter cases, otherwise it will
	// assume a single parameter case
	ErrUnexpectedCaseSyntax = "unexpected case syntax: %s"

	// ErrUnexpectedParamSyntax is raised when a Lambda parameter case is
	// represented by an unexpected syntax. Valid syntax representations are
	// data.List, data.Cons, or data.Local
	ErrUnexpectedParamSyntax = "unexpected parameter syntax: %s"

	// ErrUnreachableCase is raised when a Lambda parameter is defined that
	// would otherwise be impossible to reach given previous definitions
	ErrUnreachableCase = "unreachable parameter case: %s, matched by: %s"
)

const (
	AnyKey       = data.Keyword("any")
	AtomKey      = data.Keyword("atom")
	AppenderKey  = data.Keyword("appender")
	BooleanKey   = data.Keyword("boolean")
	ConsKey      = data.Keyword("cons")
	CountedKey   = data.Keyword("counted")
	ProcedureKey = data.Keyword("procedure")
	IndexedKey   = data.Keyword("indexed")
	KeywordKey   = data.Keyword("keyword")
	ListKey      = data.Keyword("list")
	LocalKey     = data.Keyword("local")
	MacroKey     = data.Keyword("macro")
	MappedKey    = data.Keyword("mapped")
	NaNKey       = data.Keyword("nan")
	NullKey      = data.Keyword("null")
	NumberKey    = data.Keyword("number")
	ObjectKey    = data.Keyword("object")
	PairKey      = data.Keyword("pair")
	PromiseKey   = data.Keyword("promise")
	QualifiedKey = data.Keyword("qualified")
	ResolvedKey  = data.Keyword("resolved")
	ReverserKey  = data.Keyword("reverser")
	SequenceKey  = data.Keyword("sequence")
	SpecialKey   = data.Keyword("special")
	StringKey    = data.Keyword("string")
	SymbolKey    = data.Keyword("symbol")
	VectorKey    = data.Keyword("vector")
)

const ErrAssocRequiresPair = "assoc requires a key/value combination or a pair"

ErrAssocRequiresPair is raised when a call to Assoc receives a second argument other than a Pair

const ErrIndexOutOfBounds = "index out of bounds"

ErrIndexOutOfBounds is raised when a call to Nth receives an index outside the bounds of the sequence being accessed

const ErrNoMatchingParamPattern = "no matching parameter pattern"

ErrNoMatchingParamPattern is raised when none of the parameter patterns for a Lambda were capable of being matched

const ErrProcedureRequired = "argument must be a procedure: %s"

ErrProcedureRequired is raised when a call to the Macro built-in doesn't receive a data.Procedure to wrap

const ErrUnknownPredicate = "unknown predicate: %s"

ErrUnknownPredicate is raised when a call to IsA can't resolve a built-in predicate for the specified keyword

Variables

var (
	// List constructs a new list
	List = makeConstructor(data.NewList)

	// Vector creates a new vector
	Vector = makeConstructor(data.NewVector)
)

var Append = data.MakeProcedure(func(args ...data.Value) data.Value {
	a := args[0].(data.Appender)
	s := args[1]
	return a.Append(s)
}, 2)

Append adds a value to the end of the provided AppenderKey

var Assoc = data.MakeProcedure(func(args ...data.Value) data.Value {
	s := args[0].(data.Mapper)
	if len(args) == 3 {
		p := data.NewCons(args[1], args[2])
		return s.Put(p)
	}
	if p, ok := args[1].(data.Pair); ok {
		return s.Put(p)
	}
	panic(errors.New(ErrAssocRequiresPair))
}, 2, 3)

Assoc returns a new Mapper containing the key/value association

var Chan = data.MakeProcedure(func(args ...data.Value) data.Value {
	var size int
	if len(args) != 0 {
		size = int(args[0].(data.Integer))
	}
	return stream.NewChannel(size)
}, 0, 1)

Chan instantiates a new go channel

var CurrentTime = data.MakeProcedure(func(...data.Value) data.Value {
	return data.Integer(time.Now().UnixNano())
}, 0)

CurrentTime returns the current system time in nanoseconds

var Defer = data.MakeProcedure(func(args ...data.Value) (res data.Value) {
	body := args[0].(data.Procedure)
	cleanup := args[1].(data.Procedure)

	defer cleanup.Call()
	return body.Call()
}, 2)

Defer invokes a cleanup function, no matter what has happened

var Dissoc = data.MakeProcedure(func(args ...data.Value) data.Value {
	s := args[0].(data.Mapper)
	if _, r, ok := s.Remove(args[1]); ok {
		return r
	}
	return s
}, 2)

Dissoc returns a new Mapper with the key removed

var Eval = makeEvaluator(eval.Value)

Eval encodes an immediate evaluation

var GenSym = data.MakeProcedure(func(args ...data.Value) data.Value {
	if len(args) == 0 {
		return data.NewGeneratedSymbol(anonName)
	}
	s := args[0].(data.Local)
	return data.NewGeneratedSymbol(s)
}, 0, 1)

GenSym generates a unique symbol

var Get = data.MakeProcedure(func(args ...data.Value) data.Value {
	s := args[0].(data.Mapped)
	res, _ := s.Get(args[1])
	return res
}, 2)

Get returns a value by key from the provided Mapper

var Go = data.MakeProcedure(func(args ...data.Value) data.Value {
	fn := args[0].(data.Procedure)
	go func() {
		defer runtime.NormalizeGoRuntimeErrors()
		fn.Call(args[1:]...)
	}()
	return data.Null
}, 1)

Go runs the provided function asynchronously

var IsA = data.MakeProcedure(func(args ...data.Value) data.Value {
	kwd := args[0].(data.Keyword)
	if p, ok := predicates[kwd]; ok {
		return p
	}
	panic(fmt.Errorf(ErrUnknownPredicate, kwd))
}, 1)

IsA returns a Predicate from the set of builtin named Predicates

var LazySequence = data.MakeProcedure(func(args ...data.Value) data.Value {
	fn := args[0].(data.Procedure)
	resolver := makeLazyResolver(fn)
	return sequence.NewLazy(resolver)
}, 1)

LazySequence treats a function as a lazy sequence

var Length = data.MakeProcedure(func(args ...data.Value) data.Value {
	s := args[0].(data.Counted)
	l := s.Count()
	return l
}, 1)

Length returns the element count of the provided CountedKey

var Macro = data.MakeProcedure(func(args ...data.Value) data.Value {
	switch body := args[0].(type) {
	case data.Procedure:
		wrapper := func(_ env.Namespace, args ...data.Value) data.Value {
			if err := body.CheckArity(len(args)); err != nil {
				panic(err)
			}
			return body.Call(args...)
		}
		return macro.Call(wrapper)
	default:
		panic(fmt.Errorf(ErrProcedureRequired, args[0]))
	}
}, 1)

Macro converts a function into a macro

var MacroExpand = makeEvaluator(macro.Expand)

MacroExpand performs macro expansion of a form until it can no longer

var MacroExpand1 = makeEvaluator(macro.Expand1)

MacroExpand1 performs a single-step macro expansion of a form

var Nth = data.MakeProcedure(func(args ...data.Value) data.Value {
	s := args[0].(data.Indexed)
	i := args[1].(data.Integer)
	if res, ok := s.ElementAt(i); ok {
		return res
	}
	if len(args) > 2 {
		return args[2]
	}
	panic(errors.New(ErrIndexOutOfBounds))
}, 2, 3)

Nth returns the nth element of the provided sequence or a default

var Object = data.MakeProcedure(func(args ...data.Value) data.Value {
	res, err := data.ValuesToObject(args...)
	if err != nil {
		panic(err)
	}
	return res
})

Object creates a new object instance

var Promise = data.MakeProcedure(func(args ...data.Value) data.Value {
	resolver := args[0].(data.Procedure)
	return async.NewPromise(resolver)
}, 1)

Promise instantiates a new eventually fulfilled promise

var Read = data.MakeProcedure(func(args ...data.Value) data.Value {
	v := args[0]
	s := v.(data.Sequence)
	if v, ok := data.Last(read.FromString(sequence.ToString(s))); ok {
		return v
	}
	return data.Null
}, 1)

Read performs the standard LISP read of a string

var ReaderStr = data.MakeProcedure(func(args ...data.Value) data.Value {
	if len(args) == 0 {
		return emptyString
	}

	var b bytes.Buffer
	b.WriteString(data.ToQuotedString(args[0]))
	for _, f := range args[1:] {
		b.WriteString(" ")
		b.WriteString(data.ToQuotedString(f))
	}
	return data.String(b.String())
})

ReaderStr converts the provided arguments to a delimited string

var Recover = data.MakeProcedure(func(args ...data.Value) (res data.Value) {
	body := args[0].(data.Procedure)
	rescue := args[1].(data.Procedure)

	defer func() {
		if rec := recover(); rec != nil {
			switch rec := runtime.NormalizeGoRuntimeError(rec).(type) {
			case data.Value:
				res = rescue.Call(rec)
			case error:
				res = rescue.Call(data.String(rec.Error()))
			default:

				panic("recover returned an invalid result")
			}
		}
	}()

	return body.Call()
}, 2)

Recover invokes a function and runs a recovery function if Go panics

var Reverse = data.MakeProcedure(func(args ...data.Value) data.Value {
	r := args[0].(data.Reverser)
	return r.Reverse()
}, 1)

Reverse returns a reversed copy of a Sequence

var Str = data.MakeProcedure(func(args ...data.Value) data.Value {
	v := data.Vector(args)
	return sequence.ToString(v)
})

Str converts the provided arguments to an undelimited string

var Sym = data.MakeProcedure(func(args ...data.Value) data.Value {
	if s, ok := args[0].(data.Symbol); ok {
		return s
	}
	s := args[0].(data.String)
	return data.MustParseSymbol(s)
}, 1)

Sym instantiates a new symbol

var TypeOf = data.MakeProcedure(func(args ...data.Value) data.Value {
	return data.TypePredicateOf(args[0], args[1:]...)
}, 1, data.OrMore)

TypeOf returns a CallType Predicate for the Types of the given Values. If more than one Value is provided, the Union of their Types will be returned

Functions

func Args

func Args() data.Value

Args returns a vector containing the args passed to this program

func Asm

func Asm(e encoder.Encoder, args ...data.Value)

Asm provides indirect access to the Encoder's methods and generators

func Env

func Env() data.Value

Env returns an object containing the operating system's environment

func Lambda

func Lambda(e encoder.Encoder, args ...data.Value)

Lambda encodes a lambda

func Let

func Let(e encoder.Encoder, args ...data.Value)

Let encodes a binding form. Binding values are evaluated first, and are then bound to fresh names, meaning that mutual recursion is not supported

func LetMutual

func LetMutual(e encoder.Encoder, args ...data.Value)

LetMutual encodes a binding form. First fresh names are introduced, and then binding values are evaluated with access to those names via the MutualScope