SCM Builtins: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
Wikiservice (talk | contribs) (Refresh MemCP documentation: accuracy, operational guidance, performance profile and maintained API reference) |
||
| Line 1: | Line 1: | ||
<!-- Copyright (C) 2026 Carl-Philip Haensch --> | |||
<!-- SPDX-License-Identifier: GPL-3.0-or-later --> | |||
<span id="scm-builtins"></span> | |||
= SCM Builtins = | = SCM Builtins = | ||
<!-- Generated from MemCP c42e19eba on 2026-08-27; do not edit manually. --> | |||
<div class="mw-message-box mw-message-box-notice">Generated from MemCP commit <code>c42e19eba</code> on 27 August 2026. See [[Full SCM API documentation]].</div> | |||
'''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: <code>set</code> 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 <code>begin</code>. See [[Introduction to Scheme]]. | |||
== quote == | == quote == | ||
| Line 28: | Line 32: | ||
=== Returns === | === Returns === | ||
<code>symbol</code> | * '''value''' (<code>symbol</code>) | ||
== eval == | == eval == | ||
| Line 44: | Line 48: | ||
=== Returns === | === Returns === | ||
<code>any</code> | * '''value''' (<code>any</code>) | ||
== size == | == size == | ||
| Line 60: | Line 64: | ||
=== Returns === | === Returns === | ||
<code>int</code> | * '''value''' (<code>int</code>) | ||
== optimize == | == optimize == | ||
| Line 72: | Line 76: | ||
* '''code''' (<code>list</code>): list with head and optional parameters | * '''code''' (<code>list</code>): list with head and optional parameters | ||
* '''telemetry_callback''' (<code>func | * '''telemetry_callback''' (<code>func</code>): optional callback invoked once with optimizer telemetry ''(optional)'' | ||
** '''Parameters''' | |||
*** '''parameter''' (<code>assoc</code>) | |||
**** '''budget_remaining''' (<code>int</code>) | |||
**** '''callback_analyses''' (<code>int</code>) | |||
**** '''callback_clones''' (<code>int</code>) | |||
**** '''compile_ns''' (<code>int</code>) | |||
**** '''input_nodes''' (<code>int</code>) | |||
**** '''output_nodes''' (<code>int</code>) | |||
**** '''rejected_rewrites''' (<code>int</code>) | |||
**** '''rewrites''' (<code>int</code>) | |||
** '''Returns''' | |||
*** '''value''' (<code>any</code>) | |||
<span id="returns-3"></span> | <span id="returns-3"></span> | ||
=== Returns === | === Returns === | ||
<code>any</code> | * '''value''' (<code>any</code>) | ||
== time == | == time == | ||
| Line 94: | Line 110: | ||
=== Returns === | === Returns === | ||
<code>any</code> | * '''value''' (<code>any</code>) | ||
== if == | == if == | ||
| Line 112: | Line 128: | ||
=== Returns === | === Returns === | ||
<code>returntype</code> | * '''value''' (<code>returntype</code>) | ||
== and == | == and == | ||
| Line 128: | Line 144: | ||
=== Returns === | === Returns === | ||
<code>bool</code> | * '''value''' (<code>bool</code>) | ||
== or == | == or == | ||
| Line 144: | Line 160: | ||
=== Returns === | === Returns === | ||
<code>bool</code> | * '''value''' (<code>bool</code>) | ||
== coalesce == | == coalesce == | ||
| Line 160: | Line 176: | ||
=== Returns === | === Returns === | ||
<code>returntype</code> | * '''value''' (<code>returntype</code>) | ||
<span id="coalescenil"></span> | <span id="coalescenil"></span> | ||
| Line 177: | Line 193: | ||
=== Returns === | === Returns === | ||
<code>returntype</code> | * '''value''' (<code>returntype</code>) | ||
== define == | == define == | ||
| Line 194: | Line 210: | ||
=== Returns === | === Returns === | ||
<code>bool</code> | * '''value''' (<code>bool</code>) | ||
== set == | == set == | ||
| Line 211: | Line 227: | ||
=== Returns === | === Returns === | ||
<code>bool</code> | * '''value''' (<code>bool</code>) | ||
== error == | == error == | ||
| Line 227: | Line 243: | ||
=== Returns === | === Returns === | ||
<code>string</code> | * '''value''' (<code>string</code>) | ||
== try == | == try == | ||
| Line 239: | Line 255: | ||
* '''func''' (<code>func</code>): function with no parameters that will be called | * '''func''' (<code>func</code>): function with no parameters that will be called | ||
* '''errorhandler''' (<code>func | ** '''Returns''' | ||
*** '''value''' (<code>any</code>) | |||
* '''errorhandler''' (<code>func</code>): function that takes the error as parameter | |||
** '''Parameters''' | |||
*** '''error''' (<code>any</code>) | |||
** '''Returns''' | |||
*** '''value''' (<code>any</code>) | |||
<span id="returns-13"></span> | <span id="returns-13"></span> | ||
=== Returns === | === Returns === | ||
<code>any</code> | * '''value''' (<code>any</code>) | ||
== apply == | == apply == | ||
| Line 256: | Line 278: | ||
* '''function''' (<code>func</code>): function to execute | * '''function''' (<code>func</code>): function to execute | ||
** '''Parameters''' | |||
*** '''argument''' (<code>any</code>) ''(variadic)'' | |||
** '''Returns''' | |||
*** '''result''' (<code>any</code>) | |||
* '''arguments''' (<code>list</code>): list of arguments to apply | * '''arguments''' (<code>list</code>): list of arguments to apply | ||
| Line 261: | Line 287: | ||
=== Returns === | === Returns === | ||
<code>any</code> | * '''value''' (<code>any</code>) | ||
== apply_assoc == | == apply_assoc == | ||
| Line 273: | Line 299: | ||
* '''function''' (<code>func</code>): function to execute (must be a lambda) | * '''function''' (<code>func</code>): function to execute (must be a lambda) | ||
** '''Parameters''' | |||
*** '''named argument''' (<code>any</code>) ''(variadic)'' | |||
** '''Returns''' | |||
*** '''result''' (<code>any</code>) | |||
* '''arguments''' (<code>list</code>): assoc list of arguments to apply | * '''arguments''' (<code>list</code>): assoc list of arguments to apply | ||
| Line 278: | Line 308: | ||
=== Returns === | === Returns === | ||
<code>symbol</code> | * '''value''' (<code>symbol</code>) | ||
== symbol == | == symbol == | ||
| Line 294: | Line 324: | ||
=== Returns === | === Returns === | ||
<code>symbol</code> | * '''value''' (<code>symbol</code>) | ||
== list == | == list == | ||
| Line 310: | Line 340: | ||
=== Returns === | === Returns === | ||
<code>list</code> | * '''value''' (<code>list</code>) | ||
== for == | == for == | ||
| Line 327: | Line 357: | ||
* '''init''' (<code>list</code>): initial state as a list | * '''init''' (<code>list</code>): initial state as a list | ||
* '''condition''' (<code>func | * '''condition''' (<code>func</code>): func that receives the current state as parameters and must return true if the loop shall be continued | ||
* '''step''' (<code>func | ** '''Parameters''' | ||
*** '''state''' (<code>any</code>) ''(variadic)'' | |||
** '''Returns''' | |||
*** '''value''' (<code>bool</code>) | |||
* '''step''' (<code>func</code>): step func that returns the next state as a list | |||
** '''Parameters''' | |||
*** '''state''' (<code>any</code>) ''(variadic)'' | |||
** '''Returns''' | |||
*** '''value''' (<code>list</code>) | |||
<span id="returns-18"></span> | <span id="returns-18"></span> | ||
=== Returns === | === Returns === | ||
<code>list</code> | * '''value''' (<code>list</code>) | ||
== string == | == string == | ||
| Line 349: | Line 387: | ||
=== Returns === | === Returns === | ||
<code>string</code> | * '''value''' (<code>string</code>) | ||
== match == | == match == | ||
| Line 377: | Line 415: | ||
=== Returns === | === Returns === | ||
<code>any</code> | * '''value''' (<code>any</code>) | ||
== lambda == | == lambda == | ||
| Line 395: | Line 433: | ||
=== Returns === | === Returns === | ||
<code>func</code> | * '''lambda''' (<code>func</code>): function constructed from parameters and code | ||
** '''Parameters''' | |||
*** '''argument''' (<code>any</code>): value bound to the corresponding declared parameter ''(variadic)'' | |||
** '''Returns''' | |||
*** '''result''' (<code>any</code>): value produced by code | |||
== begin == | == begin == | ||
| Line 411: | Line 453: | ||
=== Returns === | === Returns === | ||
<code>any</code> | * '''value''' (<code>any</code>) | ||
== parallel == | == parallel == | ||
| Line 427: | Line 469: | ||
=== Returns === | === Returns === | ||
<code>any</code> | * '''value''' (<code>any</code>) | ||
== source == | == source == | ||
| Line 446: | Line 488: | ||
=== Returns === | === Returns === | ||
<code>returntype</code> | * '''value''' (<code>returntype</code>) | ||
== source_coverage_report == | == source_coverage_report == | ||
| Line 462: | Line 504: | ||
=== Returns === | === Returns === | ||
<code>assoc</code> | * '''value''' (<code>assoc</code>) | ||
== scheme == | == scheme == | ||
| Line 479: | Line 521: | ||
=== Returns === | === Returns === | ||
<code>any</code> | * '''value''' (<code>any</code>) | ||
== serialize == | == serialize == | ||
| Line 495: | Line 537: | ||
=== Returns === | === Returns === | ||
<code>string</code> | * '''value''' (<code>string</code>) | ||
== pretty_print == | == pretty_print == | ||
| Line 512: | Line 554: | ||
=== Returns === | === Returns === | ||
<code>string</code> | * '''value''' (<code>string</code>) | ||
Latest revision as of 11:59, 28 August 2026
SCM Builtins
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)
- budget_remaining (
- parameter (
- Returns
- value (
any)
- value (
- Parameters
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)
- value (
- Returns
- errorhandler (
func): function that takes the error as parameter- Parameters
- error (
any)
- error (
- Returns
- value (
any)
- value (
- Parameters
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)
- argument (
- Returns
- result (
any)
- result (
- Parameters
- 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)
- named argument (
- Returns
- result (
any)
- result (
- Parameters
- 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)
- state (
- Returns
- value (
bool)
- value (
- Parameters
- step (
func): step func that returns the next state as a list- Parameters
- state (
any) (variadic)
- state (
- Returns
- value (
list)
- value (
- Parameters
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)
- argument (
- Returns
- result (
any): value produced by code
- result (
- Parameters
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)