SCM Builtins: Difference between revisions
Jump to navigation
Jump to search
No edit summary |
No edit summary |
||
| (One intermediate revision by the same user not shown) | |||
| Line 1: | Line 1: | ||
= 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: | |||
* '''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 == | == quote == | ||
| Line 7: | Line 19: | ||
'''Allowed number of parameters:''' 1–1 | '''Allowed number of parameters:''' 1–1 | ||
'''Parameters:''' | |||
* '''symbol''' (<code>symbol</code>): symbol to quote | * '''symbol''' (<code>symbol</code>): symbol to quote | ||
'''Returns:''' <code>symbol</code> | |||
<code>symbol</code> | |||
== eval == | == eval == | ||
| Line 21: | Line 30: | ||
'''Allowed number of parameters:''' 1–1 | '''Allowed number of parameters:''' 1–1 | ||
'''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> | |||
<code>any</code> | |||
== size == | == size == | ||
| Line 35: | Line 41: | ||
'''Allowed number of parameters:''' 1–1 | '''Allowed number of parameters:''' 1–1 | ||
'''Parameters:''' | |||
* '''value''' (<code>any</code>): value to examine | * '''value''' (<code>any</code>): value to examine | ||
'''Returns:''' <code>int</code> | |||
<code>int</code> | |||
== optimize == | == optimize == | ||
| Line 49: | Line 52: | ||
'''Allowed number of parameters:''' 1–1 | '''Allowed number of parameters:''' 1–1 | ||
'''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> | |||
<code>any</code> | |||
== time == | == time == | ||
| Line 63: | Line 63: | ||
'''Allowed number of parameters:''' 1–2 | '''Allowed number of parameters:''' 1–2 | ||
'''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 | ||
'''Returns:''' <code>any</code> | |||
<code>any</code> | |||
== if == | == if == | ||
| Line 78: | Line 75: | ||
'''Allowed number of parameters:''' 2–1000 | '''Allowed number of parameters:''' 2–1000 | ||
'''Parameters:''' | |||
* '''condition...''' (<code>bool</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>returntype</code>): code to evaluate if condition is false | ||
'''Returns:''' <code>returntype</code> | |||
<code>returntype</code> | |||
== and == | == and == | ||
| Line 94: | Line 88: | ||
'''Allowed number of parameters:''' 1–1000 | '''Allowed number of parameters:''' 1–1000 | ||
'''Parameters:''' | |||
* '''condition''' (<code>bool</code>): condition to evaluate | * '''condition''' (<code>bool</code>): condition to evaluate | ||
'''Returns:''' <code>bool</code> | |||
<code>bool</code> | |||
== or == | == or == | ||
| Line 108: | Line 99: | ||
'''Allowed number of parameters:''' 1–1000 | '''Allowed number of parameters:''' 1–1000 | ||
'''Parameters:''' | |||
* '''condition''' (<code>any</code>): condition to evaluate | * '''condition''' (<code>any</code>): condition to evaluate | ||
'''Returns:''' <code>bool</code> | |||
<code>bool</code> | |||
== coalesce == | == coalesce == | ||
| Line 122: | Line 110: | ||
'''Allowed number of parameters:''' 1–1000 | '''Allowed number of parameters:''' 1–1000 | ||
'''Parameters:''' | |||
* '''value''' (<code>returntype</code>): value to examine | * '''value''' (<code>returntype</code>): value to examine | ||
'''Returns:''' <code>returntype</code> | |||
<code>returntype</code> | |||
== coalesceNil == | == coalesceNil == | ||
| Line 136: | Line 121: | ||
'''Allowed number of parameters:''' 1–1000 | '''Allowed number of parameters:''' 1–1000 | ||
'''Parameters:''' | |||
* '''value''' (<code>returntype</code>): value to examine | * '''value''' (<code>returntype</code>): value to examine | ||
'''Returns:''' <code>returntype</code> | |||
<code>returntype</code> | |||
== define == | == define == | ||
| Line 150: | Line 132: | ||
'''Allowed number of parameters:''' 2–2 | '''Allowed number of parameters:''' 2–2 | ||
'''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> | |||
<code>bool</code> | |||
== set == | == set == | ||
| Line 165: | Line 144: | ||
'''Allowed number of parameters:''' 2–2 | '''Allowed number of parameters:''' 2–2 | ||
'''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> | |||
<code>bool</code> | |||
== error == | == error == | ||
| Line 180: | Line 156: | ||
'''Allowed number of parameters:''' 1–1000 | '''Allowed number of parameters:''' 1–1000 | ||
'''Parameters:''' | |||
* '''value...''' (<code>any</code>): value or message to throw | * '''value...''' (<code>any</code>): value or message to throw | ||
'''Returns:''' <code>string</code> | |||
<code>string</code> | |||
== try == | == try == | ||
| Line 194: | Line 167: | ||
'''Allowed number of parameters:''' 2–2 | '''Allowed number of parameters:''' 2–2 | ||
'''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 | ||
* '''errorhandler''' (<code>func</code>): function that takes the error as parameter | * '''errorhandler''' (<code>func</code>): function that takes the error as parameter | ||
'''Returns:''' <code>any</code> | |||
<code>any</code> | |||
== apply == | == apply == | ||
| Line 209: | Line 179: | ||
'''Allowed number of parameters:''' 2–2 | '''Allowed number of parameters:''' 2–2 | ||
'''Parameters:''' | |||
* '''function''' (<code>func</code>): function to execute | * '''function''' (<code>func</code>): function to execute | ||
* '''arguments''' (<code>list</code>): list of arguments to apply | * '''arguments''' (<code>list</code>): list of arguments to apply | ||
'''Returns:''' <code>any</code> | |||
<code>any</code> | |||
== apply_assoc == | == apply_assoc == | ||
| Line 224: | Line 191: | ||
'''Allowed number of parameters:''' 2–2 | '''Allowed number of parameters:''' 2–2 | ||
'''Parameters:''' | |||
* '''function''' (<code>func</code>): function to execute (must be a lambda) | * '''function''' (<code>func</code>): function to execute (must be a lambda) | ||
* '''arguments''' (<code>list</code>): assoc list of arguments to apply | * '''arguments''' (<code>list</code>): assoc list of arguments to apply | ||
'''Returns:''' <code>symbol</code> | |||
<code>symbol</code> | |||
== symbol == | == symbol == | ||
| Line 239: | Line 203: | ||
'''Allowed number of parameters:''' 1–1 | '''Allowed number of parameters:''' 1–1 | ||
'''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> | |||
<code>symbol</code> | |||
== list == | == list == | ||
| Line 253: | Line 214: | ||
'''Allowed number of parameters:''' 0–10000 | '''Allowed number of parameters:''' 0–10000 | ||
'''Parameters:''' | |||
* '''value...''' (<code>any</code>): value for the list | * '''value...''' (<code>any</code>): value for the list | ||
'''Returns:''' <code>list</code> | |||
<code>list</code> | |||
== string == | == string == | ||
| Line 267: | Line 225: | ||
'''Allowed number of parameters:''' 1–1 | '''Allowed number of parameters:''' 1–1 | ||
'''Parameters:''' | |||
* '''value''' (<code>any</code>): any value | * '''value''' (<code>any</code>): any value | ||
'''Returns:''' <code>string</code> | |||
<code>string</code> | |||
== match == | == match == | ||
| Line 291: | Line 246: | ||
'''Allowed number of parameters:''' 3–10000 | '''Allowed number of parameters:''' 3–10000 | ||
'''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 | ||
| Line 298: | Line 252: | ||
* '''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 | ||
'''Returns:''' <code>any</code> | |||
<code>any</code> | |||
== lambda == | == lambda == | ||
| Line 308: | Line 260: | ||
'''Allowed number of parameters:''' 2–3 | '''Allowed number of parameters:''' 2–3 | ||
'''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. | ||
'''Returns:''' <code>func</code> | |||
<code>func</code> | |||
== begin == | == begin == | ||
| Line 324: | Line 273: | ||
'''Allowed number of parameters:''' 0–10000 | '''Allowed number of parameters:''' 0–10000 | ||
'''Parameters:''' | |||
* '''expression...''' (<code>any</code>): expressions to evaluate | * '''expression...''' (<code>any</code>): expressions to evaluate | ||
'''Returns:''' <code>any</code> | |||
<code>any</code> | |||
== parallel == | == parallel == | ||
| Line 338: | Line 284: | ||
'''Allowed number of parameters:''' 1–10000 | '''Allowed number of parameters:''' 1–10000 | ||
'''Parameters:''' | |||
* '''expression...''' (<code>any</code>): expressions to evaluate in parallel | * '''expression...''' (<code>any</code>): expressions to evaluate in parallel | ||
'''Returns:''' <code>any</code> | |||
<code>any</code> | |||
== source == | == source == | ||
| Line 352: | Line 295: | ||
'''Allowed number of parameters:''' 4–4 | '''Allowed number of parameters:''' 4–4 | ||
'''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 359: | Line 301: | ||
* '''code''' (<code>returntype</code>): code | * '''code''' (<code>returntype</code>): code | ||
'''Returns:''' <code>returntype</code> | |||
<code>returntype</code> | |||
== scheme == | == scheme == | ||
| Line 369: | Line 309: | ||
'''Allowed number of parameters:''' 1–2 | '''Allowed number of parameters:''' 1–2 | ||
'''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 | ||
'''Returns:''' <code>any</code> | |||
<code>any</code> | |||
== serialize == | == serialize == | ||
| Line 384: | Line 321: | ||
'''Allowed number of parameters:''' 1–1 | '''Allowed number of parameters:''' 1–1 | ||
'''Parameters:''' | |||
* '''code''' (<code>list</code>): Scheme code | * '''code''' (<code>list</code>): Scheme code | ||
'''Returns:''' <code>string</code> | |||
<code>string</code> | |||
Latest revision as of 18:27, 25 August 2025
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
Allowed number of parameters: 1–1
Parameters:
- code (
list): list with head and optional parameters
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
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–1000
Parameters:
- condition... (
bool): condition to evaluate - true-branch... (
returntype): code to evaluate if condition is true - false-branch (
returntype): code to evaluate if condition is false
Returns: returntype
and
returns true if all conditions evaluate to true
Allowed number of parameters: 1–1000
Parameters:
- condition (
bool): condition to evaluate
Returns: bool
or
returns true if at least one condition evaluates to true
Allowed number of parameters: 1–1000
Parameters:
- condition (
any): condition to evaluate
Returns: bool
coalesce
returns the first value that has a non-zero value
Allowed number of parameters: 1–1000
Parameters:
- value (
returntype): value to examine
Returns: returntype
coalesceNil
returns the first value that has a non-nil value
Allowed number of parameters: 1–1000
Parameters:
- value (
returntype): value to examine
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: 1–1000
Parameters:
- value... (
any): value or message to throw
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): 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
returns a list containing the parameters as alements
Allowed number of parameters: 0–10000
Parameters:
- value... (
any): value for the 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
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.
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
Returns: any
parallel
executes all parameters in parallel and returns nil if they are finished
Allowed number of parameters: 1–10000
Parameters:
- expression... (
any): expressions to evaluate in parallel
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
scheme
parses a scheme expression into a list
Allowed number of parameters: 1–2
Parameters:
- code (
string): Scheme code - filename (
string): optional filename
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