SCM Builtins

The SCM Builtins module provides the core foundational functions for the SCM (Scheme) programming language implementation. These built-in functions handle essential operations including:

Language constructs: Control flow (if, and, or), variable management (define, set), and code evaluation (eval, quote)
Function operations: Lambda creation, function application, and error handling (try, error)
Data manipulation: Type conversion (string, symbol), list operations, and pattern matching
Development tools: Code optimization, timing measurements, and debugging support
Execution control: Parallel processing, variable scoping, and source code annotation

This module forms the foundation upon which all other SCM functionality is built, providing the essential primitives needed for Scheme programming.

← Back to Full SCM API documentation

quote

returns a symbol or list without evaluating it

Allowed number of parameters: 1–1

Parameters

symbol (symbol): symbol to quote

Returns

symbol

eval

executes the given scheme program in the current environment

Allowed number of parameters: 1–1

Parameters

code (list): list with head and optional parameters

Returns

any

size

compute the memory size of a value

Allowed number of parameters: 1–1

Parameters

value (any): value to examine

Returns

int

optimize

optimize the given scheme program and optionally report telemetry after completion

Allowed number of parameters: 1–2

Parameters

code (list): list with head and optional parameters
telemetry_callback (func(assoc) -> any): optional callback invoked once with optimizer telemetry (optional)

Returns

any

time

measures the time it takes to compute the first argument

Allowed number of parameters: 1–2

Parameters

code (any): code to execute
label (string): label to print in the log or trace (optional)

Returns

any

if

checks a condition and then conditionally evaluates code branches; there might be multiple condition+true-branch clauses

Allowed number of parameters: 2–10000

Parameters

condition... (any): condition to evaluate
true-branch... (returntype): code to evaluate if condition is true
false-branch (any): code to evaluate if condition is false (variadic)

Returns

returntype

and

lazily combines conditions using SQL three-valued logic; returns false on the first false value, nil for UNKNOWN, otherwise true

Allowed number of parameters: 0–10000

Parameters

condition (bool): condition to evaluate (variadic)

Returns

bool

or

lazily combines conditions using SQL three-valued logic; returns true on the first true value, nil for UNKNOWN, otherwise false

Allowed number of parameters: 0–10000

Parameters

condition (any): condition to evaluate (variadic)

Returns

bool

coalesce

returns the first value that has a non-zero value

Allowed number of parameters: 0–10000

Parameters

value (returntype): value to examine (variadic)

Returns

returntype

coalesceNil

returns the first value that has a non-nil value

Allowed number of parameters: 0–10000

Parameters

value (returntype): value to examine (variadic)

Returns

returntype

define

defines or sets a variable in the current environment

Allowed number of parameters: 2–2

Parameters

variable (symbol): variable to set
value (returntype): value to set the variable to

Returns

bool

set

defines or sets a variable in the current environment

Allowed number of parameters: 2–2

Parameters

variable (symbol): variable to set
value (returntype): value to set the variable to

Returns

bool

error

halts the whole execution thread and throws an error message

Allowed number of parameters: 0–10000

Parameters

value... (any): value or message to throw (variadic)

Returns

string

try

tries to execute a function and returns its result. In case of a failure, the error is fed to the second function and its result value will be used

Allowed number of parameters: 2–2

Parameters

func (func): function with no parameters that will be called
errorhandler (func(error:any) -> any): function that takes the error as parameter

Returns

any

apply

runs the function with its arguments

Allowed number of parameters: 2–2

Parameters

function (func): function to execute
arguments (list): list of arguments to apply

Returns

any

apply_assoc

runs the function with its arguments but arguments is a assoc list

Allowed number of parameters: 2–2

Parameters

function (func): function to execute (must be a lambda)
arguments (list): assoc list of arguments to apply

Returns

symbol

symbol

returns a symbol built from that string

Allowed number of parameters: 1–1

Parameters

value (string): string value that will be converted into a symbol

Returns

symbol

list

constructs a list from its arguments

Allowed number of parameters: 0–10000

Parameters

items (any): items to put into the list (variadic)

Returns

list

for

Sequential loop over a list state; applies a condition and step function and returns the final state list. Use only when iterations have strong data dependencies and must run sequentially.

Examples:

Count to 10: (for '(0) (lambda (x) (< x 10)) (lambda (x) (list (+ x 1)))) => '(10)
Sum 0..9: (for '(0 0) (lambda (x sum) (< x 10)) (lambda (x sum) (list (+ x 1) (+ sum x)))) => '(10 45)

Allowed number of parameters: 3–3

Parameters

init (list): initial state as a list
condition (func(state:any...) -> bool): func that receives the current state as parameters and must return true if the loop shall be continued
step (func(state:any...) -> list): step func that returns the next state as a list

Returns

list

string

converts the given value into string

Allowed number of parameters: 1–1

Parameters

value (any): any value

Returns

string

match

takes a value evaluates the branch that first matches the given pattern Patterns can be any of:

symbol matches any value and stores is into a variable
"string" (matches only this string)
number (matches only this value)
(symbol "something") will only match the symbol 'something'
'(subpattern subpattern...) matches a list with exactly these subpatterns
(concat str1 str2 str3) will decompose a string into one of the following patterns: "prefix" variable, variable "postfix", variable "infix" variable
(cons a b) will reverse the cons function, so it will match the head of the list with a and the rest with b
(regex "pattern" text var1 var2...) will match the given regex pattern, store the whole string into text and all capture groups into var1, var2...

Allowed number of parameters: 3–10000

Parameters

value (any): value to evaluate
pattern... (any): pattern
result... (returntype): result value when the pattern matches; this code can use the variables matched in the pattern
default (any): (optional) value that is returned when no pattern matches (variadic)

Returns

any

lambda

returns a function (func) constructed from the given code

Allowed number of parameters: 2–3

Parameters

parameters (symbol|list|nil): if you provide a parameter list, you will have named parameters. If you provide a single symbol, the list of parameters will be provided in that symbol
code (any): value that is evaluated when the lambda is called. code can use the parameters provided in the declaration as well es the scope above
numvars (number): number of unnamed variables that can be accessed via (var 0) (var 1) etc. (optional)

Returns

func

begin

creates a own variable scope, evaluates all sub expressions and returns the result of the last one

Allowed number of parameters: 0–10000

Parameters

expression... (any): expressions to evaluate (variadic)

Returns

any

parallel

executes all parameters in parallel and returns nil if they are finished

Allowed number of parameters: 0–10000

Parameters

expression... (any): expressions to evaluate in parallel (variadic)

Returns

any

source

annotates the node with filename and line information for better backtraces

Allowed number of parameters: 4–4

Parameters

filename (string): Filename of the code
line (number): Line of the code
column (number): Column of the code
code (returntype): code

Returns

returntype

source_coverage_report

returns Scheme source coverage statistics, optionally filtered by source path prefix

Allowed number of parameters: 0–1

Parameters

prefix (string): source path prefix (optional)

Returns

assoc

scheme

parses a scheme expression into a list

Allowed number of parameters: 1–2

Parameters

code (string): Scheme code
filename (string): optional filename (optional)

Returns

any

serialize

serializes a piece of code into a (hopefully) reparsable string; you shall be able to send that code over network and reparse with (scheme)

Allowed number of parameters: 1–1

Parameters

code (list): Scheme code

Returns

string

pretty_print

formats Scheme code as an indented, human-readable string; expressions up to width characters are kept on one line, longer ones are expanded with one argument per line

Allowed number of parameters: 1–2

Parameters

code (list): Scheme code to format
width (int): max characters before expanding (default 20) (optional)

Returns

string