SCM Builtins: Difference between revisions

From MemCP
Jump to navigation Jump to search
No edit summary
(Refresh MemCP documentation: accuracy, operational guidance, performance profile and maintained API reference)
 
(One intermediate revision by one other user not shown)
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 =


The '''SCM Builtins''' module provides the core foundational functions for the SCM (Scheme) programming language implementation. These built-in functions handle essential operations including:
<!-- 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>


* '''Language constructs''': Control flow (if, and, or), variable management (define, set), and code evaluation (eval, quote)
'''SCM Builtins''' form the core MemCP Scheme language. They include:
* '''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.
* 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.


← Back to [[Full SCM API documentation]]
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 19: Line 24:
'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters"></span>
=== Parameters ===
 
* '''symbol''' (<code>symbol</code>): symbol to quote
* '''symbol''' (<code>symbol</code>): symbol to quote


'''Returns:''' <code>symbol</code>
<span id="returns"></span>
=== Returns ===
 
* '''value''' (<code>symbol</code>)


== eval ==
== eval ==
Line 30: Line 40:
'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-1"></span>
=== Parameters ===
 
* '''code''' (<code>list</code>): list with head and optional parameters
* '''code''' (<code>list</code>): list with head and optional parameters


'''Returns:''' <code>any</code>
<span id="returns-1"></span>
=== Returns ===
 
* '''value''' (<code>any</code>)


== size ==
== size ==
Line 41: Line 56:
'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-2"></span>
=== Parameters ===
 
* '''value''' (<code>any</code>): value to examine
* '''value''' (<code>any</code>): value to examine


'''Returns:''' <code>int</code>
<span id="returns-2"></span>
=== Returns ===
 
* '''value''' (<code>int</code>)


== optimize ==
== optimize ==


optimize the given scheme program
optimize the given scheme program and optionally report telemetry after completion


'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–2
 
<span id="parameters-3"></span>
=== Parameters ===


'''Parameters:'''
* '''code''' (<code>list</code>): list with head and optional parameters
* '''code''' (<code>list</code>): list with head and optional parameters
* '''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>
=== Returns ===


'''Returns:''' <code>any</code>
* '''value''' (<code>any</code>)


== time ==
== time ==
Line 63: Line 101:
'''Allowed number of parameters:''' 1–2
'''Allowed number of parameters:''' 1–2


'''Parameters:'''
<span id="parameters-4"></span>
=== Parameters ===
 
* '''code''' (<code>any</code>): code to execute
* '''code''' (<code>any</code>): code to execute
* '''label''' (<code>string</code>): label to print in the log or trace
* '''label''' (<code>string</code>): label to print in the log or trace ''(optional)''


'''Returns:''' <code>any</code>
<span id="returns-4"></span>
=== Returns ===
 
* '''value''' (<code>any</code>)


== if ==
== if ==
Line 73: Line 116:
checks a condition and then conditionally evaluates code branches; there might be multiple condition+true-branch clauses
checks a condition and then conditionally evaluates code branches; there might be multiple condition+true-branch clauses


'''Allowed number of parameters:''' 2–1000
'''Allowed number of parameters:''' 2–10000
 
<span id="parameters-5"></span>
=== Parameters ===


'''Parameters:'''
* '''condition...''' (<code>any</code>): condition to evaluate
* '''condition...''' (<code>bool</code>): condition to evaluate
* '''true-branch...''' (<code>returntype</code>): code to evaluate if condition is true
* '''true-branch...''' (<code>returntype</code>): code to evaluate if condition is true
* '''false-branch''' (<code>returntype</code>): code to evaluate if condition is false
* '''false-branch''' (<code>any</code>): code to evaluate if condition is false ''(variadic)''
 
<span id="returns-5"></span>
=== Returns ===


'''Returns:''' <code>returntype</code>
* '''value''' (<code>returntype</code>)


== and ==
== and ==


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


'''Allowed number of parameters:''' 1–1000
'''Allowed number of parameters:''' 0–10000


'''Parameters:'''
<span id="parameters-6"></span>
* '''condition''' (<code>bool</code>): condition to evaluate
=== Parameters ===


'''Returns:''' <code>bool</code>
* '''condition''' (<code>bool</code>): condition to evaluate ''(variadic)''
 
<span id="returns-6"></span>
=== Returns ===
 
* '''value''' (<code>bool</code>)


== or ==
== or ==


returns true if at least one condition evaluates to true
lazily combines conditions using SQL three-valued logic; returns true on the first true value, nil for UNKNOWN, otherwise false


'''Allowed number of parameters:''' 1–1000
'''Allowed number of parameters:''' 0–10000


'''Parameters:'''
<span id="parameters-7"></span>
* '''condition''' (<code>any</code>): condition to evaluate
=== Parameters ===


'''Returns:''' <code>bool</code>
* '''condition''' (<code>any</code>): condition to evaluate ''(variadic)''
 
<span id="returns-7"></span>
=== Returns ===
 
* '''value''' (<code>bool</code>)


== coalesce ==
== coalesce ==
Line 108: Line 166:
returns the first value that has a non-zero value
returns the first value that has a non-zero value


'''Allowed number of parameters:''' 1–1000
'''Allowed number of parameters:''' 0–10000


'''Parameters:'''
<span id="parameters-8"></span>
* '''value''' (<code>returntype</code>): value to examine
=== Parameters ===


'''Returns:''' <code>returntype</code>
* '''value''' (<code>returntype</code>): value to examine ''(variadic)''


<span id="returns-8"></span>
=== Returns ===
* '''value''' (<code>returntype</code>)
<span id="coalescenil"></span>
== coalesceNil ==
== coalesceNil ==


returns the first value that has a non-nil value
returns the first value that has a non-nil value


'''Allowed number of parameters:''' 1–1000
'''Allowed number of parameters:''' 0–10000
 
<span id="parameters-9"></span>
=== Parameters ===


'''Parameters:'''
* '''value''' (<code>returntype</code>): value to examine ''(variadic)''
* '''value''' (<code>returntype</code>): value to examine


'''Returns:''' <code>returntype</code>
<span id="returns-9"></span>
=== Returns ===
 
* '''value''' (<code>returntype</code>)


== define ==
== define ==
Line 132: Line 201:
'''Allowed number of parameters:''' 2–2
'''Allowed number of parameters:''' 2–2


'''Parameters:'''
<span id="parameters-10"></span>
=== Parameters ===
 
* '''variable''' (<code>symbol</code>): variable to set
* '''variable''' (<code>symbol</code>): variable to set
* '''value''' (<code>returntype</code>): value to set the variable to
* '''value''' (<code>returntype</code>): value to set the variable to


'''Returns:''' <code>bool</code>
<span id="returns-10"></span>
=== Returns ===
 
* '''value''' (<code>bool</code>)


== set ==
== set ==
Line 144: Line 218:
'''Allowed number of parameters:''' 2–2
'''Allowed number of parameters:''' 2–2


'''Parameters:'''
<span id="parameters-11"></span>
=== Parameters ===
 
* '''variable''' (<code>symbol</code>): variable to set
* '''variable''' (<code>symbol</code>): variable to set
* '''value''' (<code>returntype</code>): value to set the variable to
* '''value''' (<code>returntype</code>): value to set the variable to


'''Returns:''' <code>bool</code>
<span id="returns-11"></span>
=== Returns ===
 
* '''value''' (<code>bool</code>)


== error ==
== error ==
Line 154: Line 233:
halts the whole execution thread and throws an error message
halts the whole execution thread and throws an error message


'''Allowed number of parameters:''' 1–1000
'''Allowed number of parameters:''' 0–10000


'''Parameters:'''
<span id="parameters-12"></span>
* '''value...''' (<code>any</code>): value or message to throw
=== Parameters ===


'''Returns:''' <code>string</code>
* '''value...''' (<code>any</code>): value or message to throw ''(variadic)''
 
<span id="returns-12"></span>
=== Returns ===
 
* '''value''' (<code>string</code>)


== try ==
== try ==
Line 167: Line 251:
'''Allowed number of parameters:''' 2–2
'''Allowed number of parameters:''' 2–2


'''Parameters:'''
<span id="parameters-13"></span>
=== Parameters ===
 
* '''func''' (<code>func</code>): function with no parameters that will be called
* '''func''' (<code>func</code>): function with no parameters that will be called
** '''Returns'''
*** '''value''' (<code>any</code>)
* '''errorhandler''' (<code>func</code>): function that takes the error as parameter
* '''errorhandler''' (<code>func</code>): function that takes the error as parameter
** '''Parameters'''
*** '''error''' (<code>any</code>)
** '''Returns'''
*** '''value''' (<code>any</code>)


'''Returns:''' <code>any</code>
<span id="returns-13"></span>
=== Returns ===
 
* '''value''' (<code>any</code>)


== apply ==
== apply ==
Line 179: Line 274:
'''Allowed number of parameters:''' 2–2
'''Allowed number of parameters:''' 2–2


'''Parameters:'''
<span id="parameters-14"></span>
=== Parameters ===
 
* '''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


'''Returns:''' <code>any</code>
<span id="returns-14"></span>
=== Returns ===
 
* '''value''' (<code>any</code>)


== apply_assoc ==
== apply_assoc ==
Line 191: Line 295:
'''Allowed number of parameters:''' 2–2
'''Allowed number of parameters:''' 2–2


'''Parameters:'''
<span id="parameters-15"></span>
=== Parameters ===
 
* '''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


'''Returns:''' <code>symbol</code>
<span id="returns-15"></span>
=== Returns ===
 
* '''value''' (<code>symbol</code>)


== symbol ==
== symbol ==
Line 203: Line 316:
'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-16"></span>
=== Parameters ===
 
* '''value''' (<code>string</code>): string value that will be converted into a symbol
* '''value''' (<code>string</code>): string value that will be converted into a symbol


'''Returns:''' <code>symbol</code>
<span id="returns-16"></span>
=== Returns ===
 
* '''value''' (<code>symbol</code>)


== list ==
== list ==


returns a list containing the parameters as alements
constructs a list from its arguments


'''Allowed number of parameters:''' 0–10000
'''Allowed number of parameters:''' 0–10000


'''Parameters:'''
<span id="parameters-17"></span>
* '''value...''' (<code>any</code>): value for the list
=== Parameters ===


'''Returns:''' <code>list</code>
* '''items''' (<code>any</code>): items to put into the list ''(variadic)''
 
<span id="returns-17"></span>
=== Returns ===
 
* '''value''' (<code>list</code>)
 
== 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) (&lt; x 10)) (lambda (x) (list (+ x 1)))) =&gt; '(10)
* Sum 0..9: (for '(0 0) (lambda (x sum) (&lt; x 10)) (lambda (x sum) (list (+ x 1) (+ sum x)))) =&gt; '(10 45)
 
'''Allowed number of parameters:''' 3–3
 
<span id="parameters-18"></span>
=== Parameters ===
 
* '''init''' (<code>list</code>): initial state as a list
* '''condition''' (<code>func</code>): func that receives the current state as parameters and must return true if the loop shall be continued
** '''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>
=== Returns ===
 
* '''value''' (<code>list</code>)


== string ==
== string ==
Line 225: Line 379:
'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-19"></span>
=== Parameters ===
 
* '''value''' (<code>any</code>): any value
* '''value''' (<code>any</code>): any value


'''Returns:''' <code>string</code>
<span id="returns-19"></span>
=== Returns ===
 
* '''value''' (<code>string</code>)


== match ==
== match ==


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


Patterns can be any of:
* symbol matches any value and stores is into a variable
* symbol matches any value and stores is into a variable
* "string" (matches only this string)
* &quot;string&quot; (matches only this string)
* number (matches only this value)
* number (matches only this value)
* (symbol "something") will only match the symbol 'something'
* (symbol &quot;something&quot;) will only match the symbol 'something'
* '(subpattern subpattern...) matches a list with exactly these subpatterns
* '(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
* (concat str1 str2 str3) will decompose a string into one of the following patterns: &quot;prefix&quot; variable, variable &quot;postfix&quot;, variable &quot;infix&quot; 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
* (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...
* (regex &quot;pattern&quot; 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
'''Allowed number of parameters:''' 3–10000


'''Parameters:'''
<span id="parameters-20"></span>
=== Parameters ===
 
* '''value''' (<code>any</code>): value to evaluate
* '''value''' (<code>any</code>): value to evaluate
* '''pattern...''' (<code>any</code>): pattern
* '''pattern...''' (<code>any</code>): pattern
* '''result...''' (<code>returntype</code>): result value when the pattern matches; this code can use the variables matched in the pattern
* '''result...''' (<code>returntype</code>): result value when the pattern matches; this code can use the variables matched in the pattern
* '''default''' (<code>any</code>): (optional) value that is returned when no pattern matches
* '''default''' (<code>any</code>): (optional) value that is returned when no pattern matches ''(variadic)''


'''Returns:''' <code>any</code>
<span id="returns-20"></span>
=== Returns ===
 
* '''value''' (<code>any</code>)


== lambda ==
== lambda ==
Line 260: Line 423:
'''Allowed number of parameters:''' 2–3
'''Allowed number of parameters:''' 2–3


'''Parameters:'''
<span id="parameters-21"></span>
=== Parameters ===
 
* '''parameters''' (<code>symbol|list|nil</code>): 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
* '''parameters''' (<code>symbol|list|nil</code>): 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''' (<code>any</code>): value that is evaluated when the lambda is called. code can use the parameters provided in the declaration as well es the scope above
* '''code''' (<code>any</code>): 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''' (<code>number</code>): number of unnamed variables that can be accessed via (var 0) (var 1) etc.
* '''numvars''' (<code>number</code>): number of unnamed variables that can be accessed via (var 0) (var 1) etc. ''(optional)''
 
<span id="returns-21"></span>
=== 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 273: Line 445:
'''Allowed number of parameters:''' 0–10000
'''Allowed number of parameters:''' 0–10000


'''Parameters:'''
<span id="parameters-22"></span>
* '''expression...''' (<code>any</code>): expressions to evaluate
=== Parameters ===
 
* '''expression...''' (<code>any</code>): expressions to evaluate ''(variadic)''


'''Returns:''' <code>any</code>
<span id="returns-22"></span>
=== Returns ===
 
* '''value''' (<code>any</code>)


== parallel ==
== parallel ==
Line 282: Line 459:
executes all parameters in parallel and returns nil if they are finished
executes all parameters in parallel and returns nil if they are finished


'''Allowed number of parameters:''' 1–10000
'''Allowed number of parameters:''' 0–10000
 
<span id="parameters-23"></span>
=== Parameters ===
 
* '''expression...''' (<code>any</code>): expressions to evaluate in parallel ''(variadic)''


'''Parameters:'''
<span id="returns-23"></span>
* '''expression...''' (<code>any</code>): expressions to evaluate in parallel
=== Returns ===


'''Returns:''' <code>any</code>
* '''value''' (<code>any</code>)


== source ==
== source ==
Line 295: Line 477:
'''Allowed number of parameters:''' 4–4
'''Allowed number of parameters:''' 4–4


'''Parameters:'''
<span id="parameters-24"></span>
=== Parameters ===
 
* '''filename''' (<code>string</code>): Filename of the code
* '''filename''' (<code>string</code>): Filename of the code
* '''line''' (<code>number</code>): Line of the code
* '''line''' (<code>number</code>): Line of the code
Line 301: Line 485:
* '''code''' (<code>returntype</code>): code
* '''code''' (<code>returntype</code>): code


'''Returns:''' <code>returntype</code>
<span id="returns-24"></span>
=== Returns ===
 
* '''value''' (<code>returntype</code>)
 
== source_coverage_report ==
 
returns Scheme source coverage statistics, optionally filtered by source path prefix
 
'''Allowed number of parameters:''' 0–1
 
<span id="parameters-25"></span>
=== Parameters ===
 
* '''prefix''' (<code>string</code>): source path prefix ''(optional)''
 
<span id="returns-25"></span>
=== Returns ===
 
* '''value''' (<code>assoc</code>)


== scheme ==
== scheme ==
Line 309: Line 512:
'''Allowed number of parameters:''' 1–2
'''Allowed number of parameters:''' 1–2


'''Parameters:'''
<span id="parameters-26"></span>
=== Parameters ===
 
* '''code''' (<code>string</code>): Scheme code
* '''code''' (<code>string</code>): Scheme code
* '''filename''' (<code>string</code>): optional filename
* '''filename''' (<code>string</code>): optional filename ''(optional)''


'''Returns:''' <code>any</code>
<span id="returns-26"></span>
=== Returns ===
 
* '''value''' (<code>any</code>)


== serialize ==
== serialize ==
Line 321: Line 529:
'''Allowed number of parameters:''' 1–1
'''Allowed number of parameters:''' 1–1


'''Parameters:'''
<span id="parameters-27"></span>
=== Parameters ===
 
* '''code''' (<code>list</code>): Scheme code
* '''code''' (<code>list</code>): Scheme code


'''Returns:''' <code>string</code>
<span id="returns-27"></span>
=== Returns ===
 
* '''value''' (<code>string</code>)
 
== 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
 
<span id="parameters-28"></span>
=== Parameters ===
 
* '''code''' (<code>list</code>): Scheme code to format
* '''width''' (<code>int</code>): max characters before expanding (default 20) ''(optional)''
 
<span id="returns-28"></span>
=== Returns ===
 
* '''value''' (<code>string</code>)

Latest revision as of 11:59, 28 August 2026


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"