SCM Builtins: Difference between revisions

From MemCP
Jump to navigation Jump to search
(Created page with "# SCM Builtins ## 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 param...")
 
No edit summary
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
# SCM Builtins
= SCM Builtins =


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


returns a symbol or list without evaluating it
* '''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


**Allowed number of parameters:** 1–1
This module forms the foundation upon which all other SCM functionality is built, providing the essential primitives needed for Scheme programming.


### Parameters
← Back to [[Full SCM API documentation]]


- **symbol** (`symbol`): symbol to quote
== quote ==


### Returns
returns a symbol or list without evaluating it


`symbol`
'''Allowed number of parameters:''' 1–1


## eval
'''Parameters:'''
* '''symbol''' (<code>symbol</code>): symbol to quote


executes the given scheme program in the current environment
'''Returns:''' <code>symbol</code>


**Allowed number of parameters:** 1–1
== eval ==


### Parameters
executes the given scheme program in the current environment


- **code** (`list`): list with head and optional parameters
'''Allowed number of parameters:''' 1–1


### Returns
'''Parameters:'''
* '''code''' (<code>list</code>): list with head and optional parameters


`any`
'''Returns:''' <code>any</code>


## size
== size ==


compute the memory size of a value
compute the memory size of a value


**Allowed number of parameters:** 1–1
'''Allowed number of parameters:''' 1–1


### Parameters
'''Parameters:'''
* '''value''' (<code>any</code>): value to examine


- **value** (`any`): value to examine
'''Returns:''' <code>int</code>


### Returns
== optimize ==
 
`int`
 
## optimize


optimize the given scheme program
optimize the given scheme program


**Allowed number of parameters:** 1–1
'''Allowed number of parameters:''' 1–1
 
### Parameters
 
- **code** (`list`): list with head and optional parameters


### Returns
'''Parameters:'''
* '''code''' (<code>list</code>): list with head and optional parameters


`any`
'''Returns:''' <code>any</code>


## time
== time ==


measures the time it takes to compute the first argument
measures the time it takes to compute the first argument


**Allowed number of parameters:** 1–2
'''Allowed number of parameters:''' 1–2
 
### Parameters
 
- **code** (`any`): code to execute
- **label** (`string`): label to print in the log or trace


### Returns
'''Parameters:'''
* '''code''' (<code>any</code>): code to execute
* '''label''' (<code>string</code>): label to print in the log or trace


`any`
'''Returns:''' <code>any</code>


## if
== if ==


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–1000


### Parameters
'''Parameters:'''
* '''condition...''' (<code>bool</code>): condition to evaluate
* '''true-branch...''' (<code>returntype</code>): code to evaluate if condition is true
* '''false-branch''' (<code>returntype</code>): code to evaluate if condition is false


- **condition...** (`bool`): condition to evaluate
'''Returns:''' <code>returntype</code>
- **true-branch...** (`returntype`): code to evaluate if condition is true
- **false-branch** (`returntype`): code to evaluate if condition is false


### Returns
== and ==
 
`returntype`
 
## and


returns true if all conditions evaluate to true
returns true if all conditions evaluate to true


**Allowed number of parameters:** 1–1000
'''Allowed number of parameters:''' 1–1000


### Parameters
'''Parameters:'''
* '''condition''' (<code>bool</code>): condition to evaluate


- **condition** (`bool`): condition to evaluate
'''Returns:''' <code>bool</code>


### Returns
== or ==
 
`bool`
 
## or


returns true if at least one condition evaluates to true
returns true if at least one condition evaluates to true


**Allowed number of parameters:** 1–1000
'''Allowed number of parameters:''' 1–1000


### Parameters
'''Parameters:'''
* '''condition''' (<code>any</code>): condition to evaluate


- **condition** (`any`): condition to evaluate
'''Returns:''' <code>bool</code>


### Returns
== coalesce ==
 
`bool`
 
## coalesce


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:''' 1–1000
 
### Parameters


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


### Returns
'''Returns:''' <code>returntype</code>


`returntype`
== 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:''' 1–1000


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


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


### Returns
== define ==
 
`returntype`
 
## define


defines or sets a variable in the current environment
defines or sets a variable in the current environment


**Allowed number of parameters:** 2–2
'''Allowed number of parameters:''' 2–2


### Parameters
'''Parameters:'''
* '''variable''' (<code>symbol</code>): variable to set
* '''value''' (<code>returntype</code>): value to set the variable to


- **variable** (`symbol`): variable to set
'''Returns:''' <code>bool</code>
- **value** (`returntype`): value to set the variable to


### Returns
== set ==
 
`bool`
 
## set


defines or sets a variable in the current environment
defines or sets a variable in the current environment


**Allowed number of parameters:** 2–2
'''Allowed number of parameters:''' 2–2
 
### Parameters
 
- **variable** (`symbol`): variable to set
- **value** (`returntype`): value to set the variable to


### Returns
'''Parameters:'''
* '''variable''' (<code>symbol</code>): variable to set
* '''value''' (<code>returntype</code>): value to set the variable to


`bool`
'''Returns:''' <code>bool</code>


## error
== error ==


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:''' 1–1000
 
### Parameters


- **value...** (`any`): value or message to throw
'''Parameters:'''
* '''value...''' (<code>any</code>): value or message to throw


### Returns
'''Returns:''' <code>string</code>


`string`
== try ==
 
## 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
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
'''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
'''Parameters:'''
* '''func''' (<code>func</code>): function with no parameters that will be called
* '''errorhandler''' (<code>func</code>): function that takes the error as parameter


`any`
'''Returns:''' <code>any</code>


## apply
== apply ==


runs the function with its arguments
runs the function with its arguments


**Allowed number of parameters:** 2–2
'''Allowed number of parameters:''' 2–2
 
### Parameters
 
- **function** (`func`): function to execute
- **arguments** (`list`): list of arguments to apply


### Returns
'''Parameters:'''
* '''function''' (<code>func</code>): function to execute
* '''arguments''' (<code>list</code>): list of arguments to apply


`any`
'''Returns:''' <code>any</code>


## apply_assoc
== apply_assoc ==


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


**Allowed number of parameters:** 2–2
'''Allowed number of parameters:''' 2–2


### Parameters
'''Parameters:'''
* '''function''' (<code>func</code>): function to execute (must be a lambda)
* '''arguments''' (<code>list</code>): assoc list of arguments to apply


- **function** (`func`): function to execute (must be a lambda)
'''Returns:''' <code>symbol</code>
- **arguments** (`list`): assoc list of arguments to apply


### Returns
== symbol ==
 
`symbol`
 
## symbol


returns a symbol built from that string
returns a symbol built from that string


**Allowed number of parameters:** 1–1
'''Allowed number of parameters:''' 1–1
 
### Parameters
 
- **value** (`string`): string value that will be converted into a symbol


### Returns
'''Parameters:'''
* '''value''' (<code>string</code>): string value that will be converted into a symbol


`symbol`
'''Returns:''' <code>symbol</code>


## list
== list ==


returns a list containing the parameters as alements
returns a list containing the parameters as alements


**Allowed number of parameters:** 0–10000
'''Allowed number of parameters:''' 0–10000
 
### Parameters
 
- **value...** (`any`): value for the list


### Returns
'''Parameters:'''
* '''value...''' (<code>any</code>): value for the list


`list`
'''Returns:''' <code>list</code>


## string
== string ==


converts the given value into string
converts the given value into string


**Allowed number of parameters:** 1–1
'''Allowed number of parameters:''' 1–1


### Parameters
'''Parameters:'''
* '''value''' (<code>any</code>): any value


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


### Returns
== match ==


`string`
takes a value evaluates the branch that first matches the given pattern


## match
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)
* "string" (matches only this string)
- number (matches only this value)
* number (matches only this value)
- (symbol "something") will only match the symbol 'something'
* (symbol "something") 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: "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
* (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 "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


**Allowed number of parameters:** 3–10000
'''Parameters:'''
* '''value''' (<code>any</code>): value to evaluate
* '''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
* '''default''' (<code>any</code>): (optional) value that is returned when no pattern matches


### Parameters
'''Returns:''' <code>any</code>


- **value** (`any`): value to evaluate
== lambda ==
- **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
returns a function (func) constructed from the given code


**Allowed number of parameters:** 2–3
'''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
'''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
* '''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.


`func`
'''Returns:''' <code>func</code>


## begin
== begin ==


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


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


### Parameters
'''Parameters:'''
* '''expression...''' (<code>any</code>): expressions to evaluate


- **expression...** (`any`): expressions to evaluate
'''Returns:''' <code>any</code>


### Returns
== parallel ==
 
`any`
 
## parallel


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:''' 1–10000


### Parameters
'''Parameters:'''
* '''expression...''' (<code>any</code>): expressions to evaluate in parallel


- **expression...** (`any`): expressions to evaluate in parallel
'''Returns:''' <code>any</code>


### Returns
== source ==
 
`any`
 
## source


annotates the node with filename and line information for better backtraces
annotates the node with filename and line information for better backtraces


**Allowed number of parameters:** 4–4
'''Allowed number of parameters:''' 4–4


### Parameters
'''Parameters:'''
* '''filename''' (<code>string</code>): Filename of the code
* '''line''' (<code>number</code>): Line of the code
* '''column''' (<code>number</code>): Column of the code
* '''code''' (<code>returntype</code>): code


- **filename** (`string`): Filename of the code
'''Returns:''' <code>returntype</code>
- **line** (`number`): Line of the code
- **column** (`number`): Column of the code
- **code** (`returntype`): code


### Returns
== scheme ==
 
`returntype`
 
## scheme


parses a scheme expression into a list
parses a scheme expression into a list


**Allowed number of parameters:** 1–2
'''Allowed number of parameters:''' 1–2
 
### Parameters
 
- **code** (`string`): Scheme code
- **filename** (`string`): optional filename


### Returns
'''Parameters:'''
* '''code''' (<code>string</code>): Scheme code
* '''filename''' (<code>string</code>): optional filename


`any`
'''Returns:''' <code>any</code>


## serialize
== 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)
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
'''Allowed number of parameters:''' 1–1
 
### Parameters
 
- **code** (`list`): Scheme code


### Returns
'''Parameters:'''
* '''code''' (<code>list</code>): Scheme code


`string`
'''Returns:''' <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

Retrieved from "https://www.memcp.org/index.php?title=SCM_Builtins&oldid=220"