SCM Builtins

From MemCP
Revision as of 11:59, 28 August 2026 by Wikiservice (talk | contribs) (Refresh MemCP documentation: accuracy, operational guidance, performance profile and maintained API reference)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search


SCM Builtins

Generated from MemCP commit c42e19eba on 27 August 2026. See Full SCM API documentation.

SCM Builtins form the core MemCP Scheme language. They include:

  • quoting, evaluation, lambdas, application, and lexical bindings;
  • conditional and parallel control flow;
  • type conversion, matching, errors, and recovery;
  • list and symbol primitives required to construct code as data;
  • optimizer, formatting, timing, and source-location support.

The dialect is functional: set defines a binding in the current scope rather than imperatively mutating an outer scope. A lambda has a parameter list and one body; wrap multiple forms in begin. See Introduction to Scheme.

quote

returns a symbol or list without evaluating it

Allowed number of parameters: 1–1

Parameters

  • symbol (symbol): symbol to quote

Returns

  • value (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

  • value (any)

size

compute the memory size of a value

Allowed number of parameters: 1–1

Parameters

  • value (any): value to examine

Returns

  • value (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): optional callback invoked once with optimizer telemetry (optional)
    • Parameters
      • parameter (assoc)
        • budget_remaining (int)
        • callback_analyses (int)
        • callback_clones (int)
        • compile_ns (int)
        • input_nodes (int)
        • output_nodes (int)
        • rejected_rewrites (int)
        • rewrites (int)
    • Returns
      • value (any)

Returns

  • value (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

  • value (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

  • value (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

  • value (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

  • value (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

  • value (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

  • value (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

  • value (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

  • value (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

  • value (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
    • Returns
      • value (any)
  • errorhandler (func): function that takes the error as parameter
    • Parameters
      • error (any)
    • Returns
      • value (any)

Returns

  • value (any)

apply

runs the function with its arguments

Allowed number of parameters: 2–2

Parameters

  • function (func): function to execute
    • Parameters
      • argument (any) (variadic)
    • Returns
      • result (any)
  • arguments (list): list of arguments to apply

Returns

  • value (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)
    • Parameters
      • named argument (any) (variadic)
    • Returns
      • result (any)
  • arguments (list): assoc list of arguments to apply

Returns

  • value (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

  • value (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

  • value (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): func that receives the current state as parameters and must return true if the loop shall be continued
    • Parameters
      • state (any) (variadic)
    • Returns
      • value (bool)
  • step (func): step func that returns the next state as a list
    • Parameters
      • state (any) (variadic)
    • Returns
      • value (list)

Returns

  • value (list)

string

converts the given value into string

Allowed number of parameters: 1–1

Parameters

  • value (any): any value

Returns

  • value (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

  • value (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

  • lambda (func): function constructed from parameters and code
    • Parameters
      • argument (any): value bound to the corresponding declared parameter (variadic)
    • Returns
      • result (any): value produced by code

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

  • value (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

  • value (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

  • value (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

  • value (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

  • value (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

  • value (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

  • value (string)
Retrieved from "https://www.memcp.org/index.php?title=SCM_Builtins&oldid=352"