builtin

Documentation

Overview

Package builtin provides core runtime functions implemented in Go that form the foundation of Ale's standard library. These include essential operations like I/O, type checking, sequence manipulation, and system integration that require direct access to Go's capabilities or are more efficient when implemented natively rather than in Ale itself.

Index

• Constants
• Variables
• func Args() ale.Value
• func Env() ale.Value
• func SyntaxQuote(ns env.Namespace, args ...ale.Value) ale.Value

Constants

const (
	AnyKey       = data.Keyword("any")
	AtomKey      = data.Keyword("atom")
	AppenderKey  = data.Keyword("appender")
	BooleanKey   = data.Keyword("boolean")
	BytesKey     = data.Keyword("bytes")
	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 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

const ErrUnsupportedSyntaxQuote = "unsupported type in syntax quote: %s"

ErrUnsupportedSyntaxQuote is raised when an attempt to syntax quote an unsupported type is made. Generally on basic sequences are supported

Variables

var (
	// Bytes constructs a new byte vector
	Bytes = makeConstructor(data.NewBytes)

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

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

var Chan = data.MakeProcedure(func(args ...ale.Value) ale.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(...ale.Value) ale.Value {
	return data.Integer(time.Now().UnixNano())
}, 0)

CurrentTime returns the current system time in nanoseconds

var Defer = data.MakeProcedure(func(args ...ale.Value) (res ale.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 GenSym = data.MakeProcedure(func(args ...ale.Value) ale.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 Go = data.MakeProcedure(func(args ...ale.Value) ale.Value {
	fn := args[0].(data.Procedure)
	callArgs := slices.Clone(args[1:])
	go func() {
		defer runtime.NormalizeGoRuntimeErrors()
		fn.Call(callArgs...)
	}()
	return data.Null
}, 1, data.OrMore)

Go runs the provided function asynchronously

var IsA = data.MakeProcedure(func(args ...ale.Value) ale.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 Macro = data.MakeProcedure(func(args ...ale.Value) ale.Value {
	switch body := args[0].(type) {
	case data.Procedure:
		wrapper := func(_ env.Namespace, args ...ale.Value) ale.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 Object = data.MakeProcedure(func(args ...ale.Value) ale.Value {
	res, err := data.ValuesToObject(args...)
	if err != nil {
		panic(err)
	}
	return res
})

Object creates a new object instance

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

Read performs the standard LISP read of a string

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

	var b strings.Builder
	b.WriteString(data.ToQuotedString(args[0]))
	for _, f := range args[1:] {
		b.WriteString(lang.Space)
		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 ...ale.Value) (res ale.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 ale.Value:
				res = rescue.Call(rec)
			case error:
				res = rescue.Call(data.String(rec.Error()))
			default:
				panic(debug.ProgrammerError("recover returned invalid result"))
			}
		}
	}()

	return body.Call()
}, 2)

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

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

Str converts the provided arguments to an undelimited string

var Sym = data.MakeProcedure(func(args ...ale.Value) ale.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 ...ale.Value) ale.Value {
	return data.TypePredicateOf(args[0], args[1:]...)
}, 1, data.OrMore)

TypeOf returns a Type 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() ale.Value

Args returns a vector containing the args passed to this program

func Env

func Env() ale.Value

Env returns an object containing the operating system's environment

func SyntaxQuote

func SyntaxQuote(ns env.Namespace, args ...ale.Value) ale.Value

SyntaxQuote performs syntax quoting on the provided value