Builtins reference

Every builtin the language server knows: special forms, type constructors, and grounded functions. Hovering a builtin in your editor links here to its entry. Every builtin, including punctuation operators such as + and ->, has its own anchor.

Special forms and macros

: {#3a}

(: symbol type) -> type-declaration

Attach a MeTTa type declaration to a symbol.

! {#21}

(! expression) -> result

Evaluate a top-level MeTTa query. The language server indexes bang forms but never executes them.

= {#3d}

(-> $t $t %Undefined%)

Defines a reduction rule for expressions

Parameters

• $t — Pattern to match against the expression to reduce
• $t — Result of reduction or transformation of the pattern

Returns %Undefined% — Not reduced itself unless custom equalities over equalities are added

bind!

(-> Atom %Undefined% (->))

Registers a token replaced by an atom during parsing of the rest of the program

Parameters

• Atom — Token name
• %Undefined% — Atom associated with the token after reduction

Returns (->) — Unit atom

case

(-> Atom Expression %Undefined%)

Tests pattern-matching conditions for a value in sequence

Parameters

• Atom — Atom to evaluate
• Expression — Tuple of pattern-to-result pairs

Returns %Undefined% — The result of the first matching condition

chain

(-> Atom Variable Atom %Undefined%)

Evaluates the first argument, binds it to the variable, then evaluates the template

Parameters

• Atom — Atom to evaluate
• Variable — Variable
• Atom — Atom evaluated at the end

Returns %Undefined% — Result of evaluating the template

if

(-> Bool Atom Atom $t)

Replaces itself by one of the arguments depending on the condition

Parameters

• Bool — Boolean condition
• Atom — Result when condition is True
• Atom — Result when condition is False

Returns $t — Second or third argument

import!

(-> Atom Atom (->))

Imports a module by relative path, binding it to a token; &self imports into the current space

Parameters

• Atom — Symbol turned into the token for the imported space
• Atom — Module name or relative path

Returns (->) — Unit atom

include

(-> Atom %Undefined%)

Includes a MeTTa script into the current space, like import! with &self

Parameters

• Atom — Name of the MeTTa script to include

Returns %Undefined% — Unit atom

include!

(include! "path/to/file.metta") -> Unit

Include another MeTTa file. Treated as an import alias for language-service visibility.

let

(-> Atom %Undefined% Atom %Undefined%)

Unifies the first two arguments and evaluates the third under the resulting bindings

Parameters

• Atom — First atom to unify
• %Undefined% — Second atom to unify, evaluated first
• Atom — Expression evaluated if the two unify

Returns %Undefined% — The third argument, or Empty

let*

(-> Expression Atom %Undefined%)

Sequentially unifies a list of pairs, then evaluates a body

Parameters

• Expression — List of pairs of atoms to unify
• Atom — Expression evaluated if every pair unifies

Returns %Undefined% — The body, or Empty

pragma!

Changes the value of a global key, such as type-check, interpreter, max-stack-depth, mettascript-max-steps, or log-level

Parameters

• %Undefined% — Key name
• %Undefined% — New value

Returns %Undefined% — Unit atom

quote

(-> Atom Atom)

Prevents an atom from being reduced

Parameters

• Atom — Atom

Returns Atom — Quoted atom

register-module!

Loads a module into the runner from a file system path

Parameters

• %Undefined% — File system path

Returns %Undefined% — Unit atom

unquote

(unquote expression) -> Atom

Unquotes a quoted atom

Parameters

• %Undefined% — Quoted atom

Returns %Undefined% — Unquoted atom

Type constructors

-> {#-3e}

(-> A B) -> FunctionType

Function type constructor. The last argument is the return type; preceding arguments are parameters.

%Undefined% {#25_Undefined_25}

(: %Undefined% Type)

Standard MeTTa type %Undefined%.

%void% {#25_void_25}

(: %void% Type)

Standard MeTTa type %void%.

Any

(: Any Type)

Standard MeTTa type Any.

Atom

(: Atom Type)

Standard MeTTa type Atom.

Bool

(: Bool Type)

Standard MeTTa type Bool.

Char

(: Char Type)

Standard MeTTa type Char.

Empty

(: Empty Type)

Standard MeTTa type Empty.

Error

(-> Atom Atom ErrorType)

Constructs an error atom

Parameters

• Atom — Atom that failed
• Atom — Error description

Returns ErrorType — Error atom

Expression

(: Expression Type)

Standard MeTTa type Expression.

False

(: False Type)

Standard MeTTa type False.

Float

(: Float Type)

Standard MeTTa type Float.

Function

(: Function Type)

Standard MeTTa type Function.

Grounded

(: Grounded Type)

Standard MeTTa type Grounded.

Int

(: Int Type)

Standard MeTTa type Int.

Integer

(: Integer Type)

Standard MeTTa type Integer.

List

(: List Type)

Standard MeTTa type List.

Map

(: Map Type)

Standard MeTTa type Map.

Maybe

(: Maybe Type)

Standard MeTTa type Maybe.

Nat

(: Nat Type)

Standard MeTTa type Nat.

Number

(: Number Type)

Standard MeTTa type Number.

Pair

(: Pair Type)

Standard MeTTa type Pair.

Query

(: Query Type)

Standard MeTTa type Query.

Result

(: Result Type)

Standard MeTTa type Result.

Space

(: Space Type)

Standard MeTTa type Space.

String

(: String Type)

Standard MeTTa type String.

Symbol

(: Symbol Type)

Standard MeTTa type Symbol.

True

(: True Type)

Standard MeTTa type True.

Type

(: Type Type)

Standard MeTTa type Type.

Undefined

(: Undefined Type)

Standard MeTTa type Undefined.

Unit

(: Unit Type)

Standard MeTTa type Unit.

Value

(: Value Type)

Standard MeTTa type Value.

Variable

(: Variable Type)

Standard MeTTa type Variable.

Functions and operators

-

(-> Number Number Number)

Subtracts second argument from first one

Parameters

• Number — Minuend
• Number — Deductible

Returns Number — Difference

!= {#21__3d}

(-> $t $t Bool)

Checks inequality of two arguments of the same type

Parameters

• $t — First argument
• $t — Second argument

Returns Bool — True if the two arguments are not equal, False otherwise

* {#2a}

(-> Number Number Number)

Multiplies two numbers

Parameters

• Number — Multiplier
• Number — Multiplicand

Returns Number — Product

/ {#2f}

(-> Number Number Number)

Divides first argument by second one

Parameters

• Number — Dividend
• Number — Divisor

Returns Number — Fraction

% {#25}

(-> Number Number Number)

Modulo operator. Returns the remainder of dividing the first argument by the second

Parameters

• Number — Dividend
• Number — Divisor

Returns Number — Remainder

+ {#2b}

(-> Number Number Number)

Sums two numbers

Parameters

• Number — Addend
• Number — Augend

Returns Number — Sum

< {#3c}

(-> Number Number Bool)

Less than. Checks whether the first argument is less than the second

Parameters

• Number — First number
• Number — Second number

Returns Bool — True if the first argument is less than the second, False otherwise

<= {#3c__3d}

(-> Number Number Bool)

Less than or equal. Checks whether the first argument is less than or equal to the second

Parameters

• Number — First number
• Number — Second number

Returns Bool — True if the first argument is less than or equal to the second, False otherwise

== {#3d__3d}

(-> $t $t Bool)

Checks equality of two arguments of the same type

Parameters

• $t — First argument
• $t — Second argument

Returns Bool — True if the two arguments are equal, False otherwise

> {#3e}

(-> Number Number Bool)

Greater than. Checks whether the first argument is greater than the second

Parameters

• Number — First number
• Number — Second number

Returns Bool — True if the first argument is greater than the second, False otherwise

>= {#3e__3d}

(-> Number Number Bool)

Greater than or equal. Checks whether the first argument is greater than or equal to the second

Parameters

• Number — First number
• Number — Second number

Returns Bool — True if the first argument is greater than or equal to the second, False otherwise

|-> {#7c-3e}

(-> Expression Atom Atom)

Lambda abstraction. Applying it unifies each parameter pattern with the matching argument and evaluates the body; a parameter that does not unify yields no result. Unapplied it is a value, so it can be bound, passed and matched on

Parameters

• Expression — Parameter patterns, as one expression
• Atom — Body, carried unevaluated

Returns Atom — The lambda value

_assert-results-are-alpha-equal

_assert-results-are-alpha-equal-msg

_assert-results-are-equal

_assert-results-are-equal-msg

_fuzz-eval-case

@desc

(-> String DocDescription)

Wraps documentation text

@doc

(-> Atom DocDescription DocInformal)

Stores informal documentation for a symbol

@doc-formal

(-> DocItem DocKindFunction DocType DocDescription DocParameters DocReturn DocFormal)

Represents documentation after get-doc has attached kinds, types, params, and return info

@item

(-> Atom DocItem)

Wraps the documented item name

@kind

(-> Atom DocKindFunction)

Wraps the documented item kind

@param

(-> String DocParameterInformal)

Wraps a parameter description

@params

(-> Expression DocParameters)

Wraps the informal parameter list

@return

(-> String DocReturnInformal)

Wraps a return description

@type

(-> Type DocType)

Wraps a type annotation in formal documentation

=alpha

Checks alpha equality of two expressions

Parameters

• %Undefined% — First expression
• %Undefined% — Second expression

Returns %Undefined% — True if both expressions are alpha equal, False otherwise

abs-math

(-> Number Number)

Returns the absolute value of the input number

Parameters

• Number — Input number

Returns Number — Absolute value

acos-math

(-> Number Number)

Returns the arccosine of the input value

Parameters

• Number — Float number

Returns Number — Result of the arccosine function

add-atom

(-> SpaceType Atom (->))

Adds an atom to a space without reducing it

Parameters

• SpaceType — Space to add the atom to
• Atom — Atom to add

Returns (->) — Unit atom

add-atoms

(-> SpaceType Expression (->))

Adds the atoms of an expression to a space without reducing them

Parameters

• SpaceType — Space
• Expression — Expression of atoms to add

Returns (->) — Unit atom

add-reduct

(-> SpaceType %Undefined% (->))

Reduces an atom and adds the result to a space

Parameters

• SpaceType — Space to add the atom to
• %Undefined% — Atom to reduce and add

Returns (->) — Unit atom

add-reducts

(-> SpaceType %Undefined% (->))

Reduces the atoms of an expression and adds the results to a space

Parameters

• SpaceType — Space
• %Undefined% — Expression to reduce and add

Returns (->) — Unit atom

all-true

(-> Atom %Undefined% Bool)

True when applying a check to every element of an expression answers True. This is what forall runs once its generator has been collected, and it works on an expression you already have

Parameters

• Atom — Check applied to each element
• %Undefined% — Expression of elements to test

Returns Bool — True if every element passes, False as soon as one does not

alpha-unique-atom

Removes elements that repeat an earlier one up to alpha-equivalence, so two expressions differing only in variable names count as one. First occurrence wins and the surviving order is kept

Parameters

• %Undefined% — Expression to deduplicate

Returns %Undefined% — The expression without its alpha-equivalent repeats

and

(-> Bool Bool Bool)

Logical conjunction of two arguments

Parameters

• Bool — First argument
• Bool — Second argument

Returns Bool — True if both arguments are True, False otherwise

append

(-> %Undefined% %Undefined% Expression)

Concatenates two expressions

Parameters

• %Undefined% — First expression
• %Undefined% — Second expression

Returns Expression — Concatenated expression

asin-math

(-> Number Number)

Returns the arcsine of the input value

Parameters

• Number — Float number

Returns Number — Result of the arcsine function

assert

(-> Atom (->))

Evaluates an atom and succeeds quietly when it answers True

Parameters

• Atom — Atom to evaluate

Returns (->) — Unit if the atom evaluates to True, otherwise an Error naming the atom

assertAlphaEqual

(-> Atom Atom (->))

Compares the results of evaluating two expressions using alpha equality

Parameters

• Atom — First expression
• Atom — Second expression

Returns (->) — Unit atom if the results are alpha equal, an error otherwise

assertAlphaEqualMsg

(-> Atom Atom Atom (->))

Alpha-compares the results of evaluating two expressions, returning a message on failure

Parameters

• Atom — First expression
• Atom — Second expression
• Atom — Message to return on failure

Returns (->) — Unit atom if alpha equal, the message otherwise

assertAlphaEqualToResult

(-> Atom Atom (->))

Alpha-compares the results of evaluating the first expression to the unevaluated second

Parameters

• Atom — First expression, evaluated
• Atom — Second expression, not evaluated

Returns (->) — Unit atom if alpha equal, an error otherwise

assertAlphaEqualToResultMsg

(-> Atom Atom Atom (->))

Alpha-compares evaluation results to an unevaluated expected value, returning a message on failure

Parameters

• Atom — First expression, evaluated
• Atom — Second expression, not evaluated
• Atom — Message to return on failure

Returns (->) — Unit atom if alpha equal, the message otherwise

assertaPredicate

(assertaPredicate Atom) -> Bool

Assert a Prolog predicate at the front of the dynamic database.

assertEqual

(-> Atom Atom (->))

Compares the results of evaluating two expressions

Parameters

• Atom — First expression
• Atom — Second expression

Returns (->) — Unit atom if the results are equal, an error otherwise

assertEqualMsg

(-> Atom Atom Atom (->))

Compares the results of evaluating two expressions, returning a message on failure

Parameters

• Atom — First expression
• Atom — Second expression
• Atom — Message to return on failure

Returns (->) — Unit atom if equal, the message otherwise

assertEqualToResult

(-> Atom Atom (->))

Compares the results of evaluating the first expression to the unevaluated second expression

Parameters

• Atom — First expression, evaluated
• Atom — Second expression with the expected results, not evaluated

Returns (->) — Unit atom if equal, an error otherwise

assertEqualToResultMsg

(-> Atom Atom Atom (->))

Compares evaluation results to an unevaluated expected value, returning a message on failure

Parameters

• Atom — First expression, evaluated
• Atom — Second expression, not evaluated
• Atom — Message to return on failure

Returns (->) — Unit atom if equal, the message otherwise

assertIncludes

(-> Atom Expression (->))

Checks that the second argument is included in the results of evaluating the first

Parameters

• Atom — First expression
• Expression — Second expression

Returns (->) — Unit atom if included, an error otherwise

assertzPredicate

(assertzPredicate Atom) -> Bool

Assert a Prolog predicate at the end of the dynamic database.

atan-math

(-> Number Number)

Returns the arctangent of the input value

Parameters

• Number — Float number

Returns Number — Result of the arctangent function

atom_concat

Joins any number of arguments into one Symbol. A symbol contributes its name, a String its contents, and anything else its printed form. The symbol-producing counterpart of concat

Parameters

• %Undefined% — The values to join

Returns %Undefined% — The concatenation, as a Symbol

atom-subst

(-> Atom Variable Atom Atom)

Substitutes a variable in a template with a value

Parameters

• Atom — Value to substitute in
• Variable — Variable to replace
• Atom — Template containing the variable

Returns Atom — The template with the variable substituted

BadArgType

(-> Number Type Type ErrorDescription)

Constructs an error description for an argument with the wrong type

Parameters

• Number — Argument position
• Type — Expected type
• Type — Actual type

Returns ErrorDescription — BadArgType error description

BadType

(-> Type Type ErrorDescription)

Constructs an error description for an expected type and an actual type

Parameters

• Type — Expected type
• Type — Actual type

Returns ErrorDescription — BadType error description

callPredicate

(callPredicate Atom) -> Bool

Return True for each Prolog solution of the given predicate goal.

capture

Wraps an atom and captures the current space

Parameters

• %Undefined% — Function name whose space to capture

Returns %Undefined% — Function

car-atom

(-> Expression %Undefined%)

Extracts the first atom of an expression as a tuple

Parameters

• Expression — Expression

Returns %Undefined% — First atom of an expression

cdr-atom

(-> Expression Expression)

Extracts the tail of an expression (all but the first atom)

Parameters

• Expression — Expression

Returns Expression — Tail of an expression

ceil-math

(-> Number Number)

Returns the smallest integer greater than or equal to the input value

Parameters

• Number — Float value

Returns Number — Integer greater than or equal to the input

change-state!

(-> (StateMonad $t) $t (StateMonad $t))

Replaces the wrapped atom of a state with a new value

Parameters

• (StateMonad $t) — State created by new-state
• $t — Atom to replace the wrapped atom

Returns (StateMonad $t) — State with the replaced atom

charsToString

(-> Expression String)

Joins an expression of single-character symbols back into a String. Every element has to be a one-character symbol, which is exactly what stringToChars produces; anything else is an error rather than a plausible-looking string

Parameters

• Expression — Expression of one-character symbols

Returns String — The characters as a String

collapse

(-> Atom Atom)

Converts a nondeterministic result into a tuple

Parameters

• Atom — Atom to evaluate

Returns Atom — Tuple

collapse-bind

(-> Atom Expression)

Evaluates the atom and returns all alternative evaluations as atom-and-bindings pairs

Parameters

• Atom — Minimal MeTTa operation to evaluate

Returns Expression — All alternative evaluations

collapse-extract

Keeps the atoms out of collapse-bind's result, which is an expression of atom-and-bindings pairs, discarding the bindings. Order and multiplicity are preserved

Parameters

• %Undefined% — Expression of atom-and-bindings pairs

Returns %Undefined% — An expression of just the atoms, or the empty expression for no results

concat

Joins any number of arguments into one String. A String contributes its contents and anything else its printed form

Parameters

• %Undefined% — The values to join

Returns %Undefined% — The concatenation, as a String

cons

Prepends an atom to an expression. PeTTa's spelling of cons-atom

Parameters

• %Undefined% — Head atom
• %Undefined% — Expression to prepend it to

Returns %Undefined% — The expression with the head in front

cons-atom

(-> Atom Expression Atom)

Constructs an expression from a head and a tail

Parameters

• Atom — Head of the expression
• Expression — Tail of the expression

Returns Atom — New expression with the head prepended to the tail

context-space

Returns the space used as the context in atom evaluation

Returns %Undefined% — The context space

cos

(-> Number Number)

Returns the cosine of the input value in radians

Parameters

• Number — Angle in radians

Returns Number — Cosine of the input

cos-math

(-> Number Number)

Returns the cosine of the input value in radians

Parameters

• Number — Angle in radians

Returns Number — Result of the cosine function

current-time

(-> Number)

Returns the current Unix time in seconds

Returns Number — Current Unix time

decons-atom

(-> Expression Atom)

Splits a non-empty expression into its head and tail

Parameters

• Expression — Expression

Returns Atom — Deconstructed expression as head and tail

DocDescription

DocFormal

DocInformal

DocItem

DocKindAtom

DocKindFunction

DocParameter

DocParameterInformal

DocParameters

DocReturn

DocReturnInformal

DocType

empty

Answers no results at all, which removes this branch from a nondeterministic evaluation. It is what a failed let reduces to, and what a pattern that does not match yields

Returns %Undefined% — Nothing

ErrorDescription

Type of values that describe an error

ErrorType

Type of error atoms

eval

(-> Atom Atom)

Performs one step of evaluation of the input atom

Parameters

• Atom — Atom to evaluate, reducible by an equality or a grounded call

Returns Atom — Result of one evaluation step

evalc

(-> Atom SpaceType Atom)

Performs one step of evaluation of the input atom in the context of a space

Parameters

• Atom — Atom to evaluate
• SpaceType — Space to evaluate the atom in

Returns Atom — Result of one evaluation step

exclude-item

(-> %Undefined% %Undefined% Expression)

Returns an expression with every occurrence of an atom removed

Parameters

• %Undefined% — Atom to remove
• %Undefined% — Expression to filter

Returns Expression — Filtered expression

exp

(-> Number Number)

Returns e raised to the input number

Parameters

• Number — Input number

Returns Number — Exponential value

filter-atom

(-> Expression Variable Atom Expression)

Keeps the atoms of a list that satisfy a predicate

Parameters

• Expression — List of atoms
• Variable — Variable
• Atom — Filter predicate

Returns Expression — Filtered list

find

Whether a pattern matches anything in a space, as a Bool. Cheaper than collecting the matches when only their existence matters

Parameters

• %Undefined% — Space to search
• %Undefined% — Pattern to look for

Returns %Undefined% — True if the pattern matches at least one atom, False otherwise

first

(-> %Undefined% Atom)

Returns the first atom in a non-empty expression

Parameters

• %Undefined% — Expression

Returns Atom — First atom

first-from-pair

(-> Expression Atom)

Returns the first atom of a pair

Parameters

• Expression — Pair

Returns Atom — First atom of the pair

floor-math

(-> Number Number)

Returns the largest integer less than or equal to the input value

Parameters

• Number — Float value

Returns Number — Integer less than or equal to the input

fold-over

(-> Atom %Undefined% Atom %Undefined%)

foldall

(-> Atom Atom Atom %Undefined%)

Folds an aggregator over ALL nondeterministic results of a generator. The generator runs once and its results are collected, so this turns a nondeterministic computation into a single value

Parameters

• Atom — Aggregator of the accumulator and one result
• Atom — Generator, passed unevaluated
• Atom — Starting accumulator

Returns %Undefined% — The accumulator after every result

foldl

(-> Atom %Undefined% %Undefined% %Undefined%)

Folds a function over an expression from the left, applying it to an element and the accumulator in that order

Parameters

• Atom — Function of an element and the accumulator
• %Undefined% — Expression to fold over
• %Undefined% — Starting accumulator

Returns %Undefined% — The accumulator after the last element

foldl-atom

(-> Expression Atom Variable Variable Atom %Undefined%)

Folds an operation across a list from an initial value

Parameters

• Expression — List of values
• Atom — Initial value
• Variable — Variable
• Variable — Variable
• Atom — Operation

Returns %Undefined% — Result of folding the operation across the list

for-each-in-atom

(-> Expression Atom (->))

Applies a function to each atom in an expression

Parameters

• Expression — Expression whose atoms the function is applied to
• Atom — Function to apply

Returns (->) — Unit atom

forall

(-> Atom Atom Bool)

True when every nondeterministic result of a generator passes a check. The generator runs once and every result is tested; a False stops the walk

Parameters

• Atom — Generator, passed unevaluated
• Atom — Check applied to each result

Returns Bool — True if every result passes, False as soon as one does not

fork-space

format-args

(-> String Expression String)

Fills the placeholders in a string with atoms from an expression

Parameters

• String — String with placeholders to replace
• Expression — Atoms to place into the string

Returns String — The string with placeholders replaced

function

(-> Atom Atom)

Evaluates its argument until it becomes a return, then reduces to the returned value

Parameters

• Atom — Atom to evaluate

Returns Atom — Result of the atom's evaluation

get-atoms

Returns all atoms in a space

Parameters

• %Undefined% — Reference to the space

Returns %Undefined% — List of all atoms in the space

get-doc

(-> Atom %Undefined%)

Returns documentation for an atom or function

Parameters

• Atom — Atom or function name to document

Returns %Undefined% — Documentation for the atom or function

get-doc-atom

Gets documentation for a non-function atom

Parameters

• %Undefined% — Space to search for documentation
• %Undefined% — Atom name to document

Returns %Undefined% — Documentation for the atom

get-doc-function

Gets documentation for a function, or default documentation if none exists

Parameters

• %Undefined% — Space to search for documentation
• %Undefined% — Function name to document
• %Undefined% — Type notation for the function

Returns %Undefined% — Documentation for the function

get-doc-params

Builds a function's parameter and return documentation, each augmented with its type

Parameters

• %Undefined% — List of parameter descriptions
• %Undefined% — Return description
• %Undefined% — Type notation without the leading arrow

Returns %Undefined% — United list of parameters and return, each with its type

get-doc-single-atom

Gets documentation for either a function or an atom, dispatching on which it is

Parameters

• %Undefined% — Space to search for documentation
• %Undefined% — Atom or function name to document

Returns %Undefined% — Documentation for the atom or function

get-metatype

(-> Atom Atom)

Returns the metatype of the input atom

Parameters

• Atom — Atom to get the metatype for

Returns Atom — The metatype of the input atom

get-mettatype

(-> Atom Atom)

Returns the implementation metatype of the input atom

Parameters

• Atom — Atom to inspect

Returns Atom — Variable, Grounded, Expression, or Symbol

get-state

Returns the atom wrapped by a state

Parameters

• %Undefined% — State

Returns %Undefined% — Atom wrapped by the state

get-type

(-> Atom %Undefined%)

Returns the type notation of the input atom

Parameters

• Atom — Atom to get the type for

Returns %Undefined% — Type notation, or %Undefined% if the atom has no type

get-type-space

Returns the type notation of an atom relative to a specified space

Parameters

• %Undefined% — Space to search for the type
• %Undefined% — Atom to get the type for

Returns %Undefined% — Type notation, or %Undefined% if the atom has no type in the space

git-module!

(-> Atom (->))

Returns an error because git modules are not supported in @metta-ts

Parameters

• Atom — Git module URL

Returns (->) — Unsupported-module error

help-param!

Prints a single parameter's documentation, used by help!

Parameters

• %Undefined% — Parameter to print

Returns %Undefined% — Unit atom

help-space!

(-> SpaceType (->))

Prints documentation for every atom in a space

Parameters

• SpaceType — Space to document

Returns (->) — Unit atom

help!

(-> Atom %Undefined%)

Prints documentation for an atom or module; with no argument prints the corelib functions

Parameters

• Atom — Atom or module to document

Returns %Undefined% — Unit atom

hyperpose

(-> %Undefined% %Undefined%)

Turns an expression into nondeterministic results

Parameters

• %Undefined% — Expression to convert

Returns %Undefined% — The expression items as nondeterministic results

id

(-> $t $t)

Returns its argument unchanged

Parameters

• $t — Input argument

Returns $t — The input argument

if-decons-expr

(-> Expression Variable Variable Atom Atom %Undefined%)

Deconstructs a non-empty expression into head and tail and evaluates a template, or a default otherwise

Parameters

• Expression — Expression to deconstruct
• Variable — Head variable
• Variable — Tail variable
• Atom — Template if the expression is non-empty
• Atom — Default otherwise

Returns %Undefined% — The template with head and tail, or the default

if-equal

Checks whether the first two arguments are equal and evaluates the third if so, the fourth otherwise

Parameters

• %Undefined% — First argument
• %Undefined% — Second argument
• %Undefined% — Evaluated if equal
• %Undefined% — Evaluated if not equal

Returns %Undefined% — The evaluated third or fourth argument

if-error

(-> Atom Atom Atom %Undefined%)

Checks whether the first argument is an error and returns the second if so, the third otherwise

Parameters

• Atom — Atom to check for an error
• Atom — Value if the first is an error
• Atom — Value otherwise

Returns %Undefined% — The second or third argument

implies

Logical implication over two Bools: False only when the first is True and the second is False

Parameters

• %Undefined% — Antecedent
• %Undefined% — Consequent

Returns %Undefined% — False if the first is True and the second False, otherwise True

import_prolog_function

(import_prolog_function Atom) -> Bool

Inspect a Prolog predicate's arities and install MeTTa function wrappers for its result argument.

import_prolog_functions_from_file

(import_prolog_functions_from_file Atom Expression) -> Bool

Consult a .pl file and install MeTTa wrappers for the named Prolog predicates.

IncorrectNumberOfArguments

Error description used when a function is called with the wrong number of arguments

index-atom

Returns the atom at the given index of an expression, or an error if out of bounds

Parameters

• %Undefined% — Expression
• %Undefined% — Index

Returns %Undefined% — Atom at the index, or an error

interpret-tuple

(-> Atom Atom Atom)

intersection

(-> Atom Atom %Undefined%)

Returns the intersection of two nondeterministic inputs

Parameters

• Atom — Nondeterministic set of values
• Atom — Another nondeterministic set of values

Returns %Undefined% — Intersection of the sets

intersection-atom

Returns the intersection of two tuples

Parameters

• %Undefined% — List of values
• %Undefined% — List of values

Returns %Undefined% — Intersection of the tuples

is-alpha-member

(-> %Undefined% %Undefined% Bool)

Checks whether an atom is alpha-equal to a member of an expression

Parameters

• %Undefined% — Atom to search for
• %Undefined% — Expression to search

Returns Bool — True if an alpha-equal atom is present, False otherwise

is-expr

(-> Atom Bool)

Checks whether the input atom is an expression

Parameters

• Atom — Atom to check

Returns Bool — True if the atom is an expression, False otherwise

is-function

(-> Type Bool)

Checks whether the input type is a function type

Parameters

• Type — Type atom

Returns Bool — True if the type is a function type, False otherwise

is-ground

(-> Atom Bool)

Checks whether the input atom contains no variables

Parameters

• Atom — Atom to check

Returns Bool — True if the atom contains no variables, False otherwise

is-member

(-> %Undefined% %Undefined% Bool)

Checks whether an atom is a member of an expression

Parameters

• %Undefined% — Atom to search for
• %Undefined% — Expression to search

Returns Bool — True if the atom is present, False otherwise

is-space

(-> Atom Bool)

Checks whether the input atom is a space reference

Parameters

• Atom — Atom to check

Returns Bool — True if the atom is a space reference, False otherwise

is-var

(-> Atom Bool)

Checks whether the input atom is a variable

Parameters

• Atom — Atom to check

Returns Bool — True if the atom is a variable, False otherwise

isinf-math

(-> Number Bool)

Checks whether the input value is positive or negative infinity

Parameters

• Number — Number

Returns Bool — True or False

isnan-math

(-> Number Bool)

Checks whether the input value is NaN

Parameters

• Number — Number

Returns Bool — True or False

iterate

Applies a step function to a state a fixed number of times, counting an index up. Each round evaluates the step on the index and the state to get the next state

Parameters

• %Undefined% — Starting index
• %Undefined% — Number of rounds left
• %Undefined% — Starting state
• %Undefined% — Step function of the index and the state

Returns %Undefined% — The state after the last round

lambda-alpha

(-> Atom Atom)

Gives a lambda a private copy of its variables, renaming capture-avoidingly: it stops at any nested lambda that rebinds a name, so an inner parameter shadowing an outer one keeps its own identity. Used by every lambda application; sealed cannot do this because it renames names rather than binders

Parameters

• Atom — A (|-> (<patterns>) <body>) lambda

Returns Atom — The same lambda with its variables made fresh

last

(-> %Undefined% Atom)

Returns the last atom in a non-empty expression

Parameters

• %Undefined% — Expression

Returns Atom — Last atom

length

(-> %Undefined% Number)

Returns the number of atoms in an expression

Parameters

• %Undefined% — Expression

Returns Number — Number of atoms

list_to_set

(-> %Undefined% Expression)

Removes duplicate atoms from an expression, preserving first occurrences

Parameters

• %Undefined% — Expression

Returns Expression — Expression with duplicates removed

log

(-> Number Number Number)

Returns the logarithm of a number in a base

Parameters

• Number — Base
• Number — Input number

Returns Number — Logarithm

log-enabled?

(-> Symbol Bool)

Whether the current log level admits this one, for a caller that wants its own sink and still wants the guard to cost only a comparison

Parameters

• Symbol — Level: error, warn, info, debug, or trace

Returns Bool — True when the level is admitted

log-math

(-> Number Number Number)

Returns the logarithm of a number given a base

Parameters

• Number — Base
• Number — Input number

Returns Number — Result of the logarithm function

log!

(-> Symbol Atom (->))

Prints the payload tagged with its level, but only when (pragma! log-level ...) admits that level. The payload is not reduced otherwise, so a log call in a hot path costs nothing until logging is turned on

Parameters

• Symbol — Level: error, warn, info, debug, or trace
• Atom — Payload atom, reduced only when the level is admitted

Returns (->) — Unit atom

map-atom

(-> Expression Variable Atom Expression)

Evaluates a template for each atom in a list

Parameters

• Expression — List of atoms
• Variable — Variable name
• Atom — Template using the variable

Returns Expression — List of results

maplist

(-> Atom Atom %Undefined%)

Applies a function to every element of an expression. The function is a symbol or a lambda, and it is applied rather than substituted, so it may be nondeterministic

Parameters

• Atom — Function to apply
• Atom — Expression to map over

Returns %Undefined% — An expression of the results, in the same order

match

(-> SpaceType Atom Atom %Undefined%)

Searches a space (first argument) for atoms matching a pattern (second argument) and returns the output template (third argument)

Parameters

• SpaceType — Atomspace to search
• Atom — Pattern atom to match
• Atom — Output template, typically containing variables from the pattern

Returns %Undefined% — The template with matched variables filled, or Empty

match-count

How many atoms in a space a pattern matches. The matches are counted as they are produced rather than collected, so the whole result set is never held at once

Parameters

• %Undefined% — Space to search
• %Undefined% — Pattern to look for

Returns %Undefined% — The number of matches, as a Number

match-type-or

(-> Bool Atom Type Bool)

Unifies two types and ORs the result with a boolean

Parameters

• Bool — Boolean value
• Atom — First type
• Type — Second type

Returns Bool — True or False

match-types

(-> Type Type Atom Atom %Undefined%)

Unifies two types and returns the third argument if they unify, the fourth otherwise

Parameters

• Type — First type
• Type — Second type
• Atom — Returned if the types unify
• Atom — Returned if the types do not unify

Returns %Undefined% — The third or fourth argument

max

(-> Number Number Number)

Returns the larger of two numbers

Parameters

• Number — First number
• Number — Second number

Returns Number — Larger number

max-atom

(-> %Undefined% Number)

Returns the maximum value in an expression of numbers

Parameters

• %Undefined% — Expression of Number atoms

Returns Number — Maximum value, or an error if the expression is non-numeric or empty

member

(-> %Undefined% %Undefined% Bool)

Succeeds with True when an atom is a member of an expression

Parameters

• %Undefined% — Atom to search for
• %Undefined% — Expression to search

Returns Bool — True if the atom is present, otherwise Empty

metta

(-> Atom Type SpaceType Atom)

Runs the MeTTa interpreter on an atom

Parameters

• Atom — Atom to interpret
• Type — Expected type of the atom
• SpaceType — Space to interpret the atom in

Returns Atom — Result of interpretation

metta-thread

(-> Atom Atom Atom Atom)

Runs the MeTTa interpreter on an atom and threads its bindings into the current evaluation

Parameters

• Atom — Atom to interpret
• Atom — Expected type of the atom
• Atom — Space to interpret the atom in

Returns Atom — Result of interpretation

min

(-> Number Number Number)

Returns the smaller of two numbers

Parameters

• Number — First number
• Number — Second number

Returns Number — Smaller number

min-atom

(-> %Undefined% Number)

Returns the minimum value in an expression of numbers

Parameters

• %Undefined% — Expression of Number atoms

Returns Number — Minimum value, or an error if the expression is non-numeric or empty

mod-space!

(-> Atom SpaceType)

Returns the space of a module, loading the module if it is not yet loaded

Parameters

• Atom — Module name

Returns SpaceType — The module's space

module-space-no-deps

(-> SpaceType SpaceType)

Returns a module space without its dependencies

Parameters

• SpaceType — Module space

Returns SpaceType — The space without its included dependencies

msort

(-> %Undefined% Expression)

Sorts an expression by standard atom order, preserving duplicates

Parameters

• %Undefined% — Expression

Returns Expression — Sorted expression

new-mork-space

new-space

Creates a new atomspace usable as a separate space from &self

Returns %Undefined% — Reference to a new space

new-state

(-> $t (StateMonad $t))

Creates a new state atom wrapping its argument

Parameters

• $t — Atom to wrap

Returns (StateMonad $t) — A state wrapping the argument

noeval

(-> Atom Atom)

Returns its argument unevaluated

Parameters

• Atom — Input argument

Returns Atom — The input argument

nop

(nop) -> Unit

Outputs the unit atom

Returns %Undefined% — Unit atom

noreduce-eq

(-> Atom Atom Bool)

Checks equality of two atoms without reducing them

Parameters

• Atom — First atom
• Atom — Second atom

Returns Bool — True if the unreduced atoms are equal, False otherwise

not

(-> Bool Bool)

Logical negation

Parameters

• Bool — Argument

Returns Bool — The negated boolean input

once

(-> Atom %Undefined%)

Evaluates an atom and keeps only its first result

Parameters

• Atom — Atom to evaluate

Returns %Undefined% — First result, or Empty if there is no result

or

(-> Bool Bool Bool)

Logical disjunction of two arguments

Parameters

• Bool — First argument
• Bool — Second argument

Returns Bool — True if any argument is True, False otherwise

par

parse

(-> String Atom)

Parses a string of MeTTa source and returns its first atom

Parameters

• String — Source string

Returns Atom — First parsed atom, or the empty expression if the string has no atoms

partial

(-> Atom Expression Atom)

The closure an under-applied function becomes. Applying it to the remaining arguments rebuilds the fuller call and evaluates that, so a function can be applied a few arguments at a time

Parameters

• Atom — The function that was under-applied
• Expression — The arguments it has been given so far

Returns Atom — A closure that takes the rest of the arguments

pow-math

(-> Number Number Number)

Returns the base raised to the given power

Parameters

• Number — Base
• Number — Power

Returns Number — Result of the power function

Predicate

(Predicate Atom) -> %Undefined%

Mark a MeTTa expression as a Prolog predicate term for callPredicate-style interop.

print-mods!

(-> (->))

Prints all modules with their corresponding spaces

Returns (->) — Unit atom

print!

(-> %Undefined% (->))

Prints text to the console without adding a newline

Parameters

• %Undefined% — Expression or atom to print

Returns (->) — Unit atom

println!

(-> %Undefined% (->))

Prints a line of text to the console

Parameters

• %Undefined% — Expression or atom to print

Returns (->) — Unit atom

prog1

Evaluates every argument in order and answers the first. The mirror of progn: the later arguments run for their effects and their values are dropped

Parameters

• %Undefined% — The atoms to evaluate in order

Returns %Undefined% — The value of the first argument

progn

Evaluates every argument in order and answers the last. Arguments evaluate applicatively, so the earlier ones run for their effects

Parameters

• %Undefined% — The atoms to evaluate in order

Returns %Undefined% — The value of the last argument

prolog-asserta

(prolog-asserta Atom) -> Bool

Assert a Prolog predicate at the front of the dynamic database.

prolog-assertz

(prolog-assertz Atom) -> Bool

Assert a Prolog predicate at the end of the dynamic database.

prolog-call

(prolog-call Atom) -> Atom

Run a Prolog goal through the configured Prolog bridge and return each solved goal as a MeTTa atom.

prolog-consult

(prolog-consult Atom) -> Bool

Consult a .pl file through the Prolog bridge, resolving the path like metta-ts --prolog.

prolog-function

(prolog-function Atom Expression) -> Atom

Call an imported Prolog predicate as a MeTTa function, treating the final Prolog argument as the result.

prolog-match

(prolog-match Atom Atom) -> Atom

Run a Prolog goal and project each answer through a MeTTa template, PeTTa-style.

prolog-retract

(prolog-retract Atom) -> Bool

Retract the first matching Prolog predicate and return True when one was removed.

py-atom

(py-atom path) -> Atom

Resolve a dotted Python path to an atom: a value reads as itself (!(py-atom math.pi) → 3.141592653589793) and a callable applies like a function (!((py-atom operator.add) 40 2) → 42). The optional second argument declares the atom's MeTTa type.

py-call

(py-call (fn args...)) -> Atom

Call Python, dispatching on the head of the argument the way PeTTa does: a bare name is a builtin ((py-call (str 42))), a dotted name is a module function (!(py-call (math.gcd 12 18)) → 6), and a leading-dot name is a method on a live object.

py-chain

(py-chain (values...)) -> Atom

Fold the expression's values left to right with Python's | operator (operator.or_), Hyperon's py-chain.

py-dict

(py-dict ((key value)...)) -> Atom

Build a Python dict from (key value) pairs; a symbol key becomes a string, other keys marshal as values.

py-dot

(py-dot object attr) -> Atom

Read an attribute (or bound method) off a live Python handle, getattr-style. The optional third argument declares the result's MeTTa type.

py-eval

(py-eval String) -> Atom

Run a Python expression string: !(py-eval "2 ** 10") → 1024.

py-import

(py-import module) -> Unit

Import a Python module by dotted name, or a .py file by path, so later py-atom / py-call forms resolve against it.

py-list

(py-list (items...)) -> Atom

Build a Python list from a MeTTa expression's elements.

py-str

(py-str Expression) -> String

Fold a MeTTa list into one Python string, str()-ing each element.

py-tuple

(py-tuple (items...)) -> Atom

Build a Python tuple from a MeTTa expression's elements.

race

random-float

(-> Number Number Number)

Returns a random float in the half-open interval from the lower bound to the upper bound

Parameters

• Number — Lower bound
• Number — Upper bound

Returns Number — Random float

random-int

(-> Number Number Number)

Returns a random integer in the half-open interval from the lower bound to the upper bound

Parameters

• Number — Lower bound
• Number — Upper bound

Returns Number — Random integer

reduce

Evaluates its argument to a normal form. Its parameter type is the evaluated one, so the operation itself is the identity; it exists because PeTTa spells full evaluation this way, where Hyperon's eval is a single step

Parameters

• %Undefined% — Atom to evaluate

Returns %Undefined% — The fully evaluated atom

remove-atom

(-> SpaceType Atom (->))

Removes an atom from a space

Parameters

• SpaceType — Space to remove the atom from
• Atom — Atom to remove

Returns (->) — Unit atom

repr

(-> Atom String)

Returns the textual representation of an atom

Parameters

• Atom — Atom to render

Returns String — String representation

retractPredicate

(retractPredicate Atom) -> Bool

Retract the first matching Prolog predicate and return True when one was removed.

return

(-> $t $t)

Returns a value from an enclosing function expression

Parameters

• $t — Value to return

Returns $t — The passed argument

return-on-error

(-> Atom Atom %Undefined%)

Returns the first argument if it is Empty or an error, the second otherwise

Parameters

• Atom — Previous evaluation result
• Atom — Atom for further evaluation

Returns %Undefined% — The previous result if it is an error or Empty, otherwise the second argument

reverse

(-> %Undefined% Expression)

Returns the atoms of an expression in reverse order

Parameters

• %Undefined% — Expression

Returns Expression — Reversed expression

round-math

(-> Number Number)

Returns the nearest integer to the input float value

Parameters

• Number — Float value

Returns Number — Nearest integer to the input

sealed

(-> Expression Atom Atom)

Replaces every variable in an atom with a unique variable, except those to ignore

Parameters

• Expression — Variable list to ignore
• Atom — Atom that uses the variables

Returns Atom — The atom with its variables made unique

second-from-pair

(-> %Undefined% Atom)

Returns the second atom of a pair

Parameters

• %Undefined% — Pair

Returns Atom — Second atom of the pair

sin

(-> Number Number)

Returns the sine of the input value in radians

Parameters

• Number — Angle in radians

Returns Number — Sine of the input

sin-math

(-> Number Number)

Returns the sine of the input value in radians

Parameters

• Number — Angle in radians

Returns Number — Result of the sine function

size-atom

(-> Expression Number)

Returns the size of an expression

Parameters

• %Undefined% — Expression

Returns %Undefined% — Size of the expression

sort

(-> %Undefined% Expression)

Sorts an expression by standard atom order and removes duplicate atoms

Parameters

• %Undefined% — Expression

Returns Expression — Sorted expression with duplicates removed

sort-atom

Sorts the elements of an expression by their printed form

Parameters

• %Undefined% — Expression to sort

Returns %Undefined% — The same elements in sorted order

sort-strings

Sorts an expression of strings in alphabetical order

Parameters

• %Undefined% — List of strings

Returns %Undefined% — Sorted list of strings

SpaceType

Type of atomspace references

sqrt

(-> Number Number)

Returns the square root of the input number

Parameters

• Number — Input number

Returns Number — Square root

sqrt-math

(-> Number Number)

Returns the square root of the input number

Parameters

• Number — Input number

Returns Number — Result of the square root function

sread

(-> String Atom)

Parses a string of MeTTa source and returns its first atom

Parameters

• String — Source string

Returns Atom — First parsed atom, or the empty expression if the string has no atoms

stringToChars

(-> String Expression)

Splits a String into an expression of single-character symbols. Astral characters stay whole, so a surrogate pair is one element rather than two

Parameters

• String — String to split

Returns Expression — An expression of one-character symbols

subtraction

(-> Atom Atom %Undefined%)

Returns the subtraction of two nondeterministic inputs

Parameters

• Atom — Nondeterministic set of values
• Atom — Another nondeterministic set of values

Returns %Undefined% — Subtraction of the sets

subtraction-atom

Returns the subtraction of two tuples

Parameters

• %Undefined% — List of values
• %Undefined% — List of values

Returns %Undefined% — Subtraction of the tuples

superpose

(-> Expression %Undefined%)

Turns a tuple into a nondeterministic result

Parameters

• Expression — Tuple to convert

Returns %Undefined% — The argument as a nondeterministic result

superpose-bind

(-> Expression Atom)

Puts a list of atom-and-bindings results back into the interpreter plan

Parameters

• Expression — Expression of atom-and-bindings pairs

Returns Atom — Nondeterministic list of atoms

switch

(-> %Undefined% Expression %Undefined%)

Tests pattern-matching conditions for a value in sequence

Parameters

• %Undefined% — Atom to match against the patterns
• Expression — Tuple of pattern-to-result pairs

Returns %Undefined% — The result for the first matching pattern

switch-internal

(-> Atom Expression Atom)

Tests one case of a switch and recurses if the condition is not met

Parameters

• Atom — Atom to evaluate
• Expression — Deconsed tuple of pattern-to-result pairs

Returns Atom — The result of the matched condition

switch-minimal

(-> Atom Expression Atom)

tan-math

(-> Number Number)

Returns the tangent of the input value in radians

Parameters

• Number — Angle in radians

Returns Number — Result of the tangent function

test

Compares two atoms up to alpha-equivalence, prints what it got beside what it should have got with a tick or a cross, and reduces to unit when they agree

Parameters

• %Undefined% — Actual atom
• %Undefined% — Expected atom

Returns %Undefined% — Unit if the two are alpha-equivalent, otherwise an Error carrying test-failed

trace!

(-> %Undefined% Atom %Undefined%)

Prints the first argument and returns the second; both are evaluated

Parameters

• %Undefined% — Atom to print
• Atom — Atom to return

Returns %Undefined% — The evaluated second argument

transaction

trunc-math

(-> Number Number)

Returns the integer part of the input value

Parameters

• Number — Float value

Returns Number — Integer part of the input

type-cast

(-> Atom Type Space %Undefined%)

Casts an atom to a type using a space as context

Parameters

• Atom — Atom to cast
• Type — Type to cast to
• Space — Context space

Returns %Undefined% — The atom if the cast succeeds, otherwise a BadType error

type-cast-error-or-bad-type

(-> Atom Expression Atom)

undefined-doc-function-type

Builds a placeholder type list for a function with no type notation

Parameters

• %Undefined% — List of parameters for the function

Returns %Undefined% — A list of %Undefined% types sized to the parameters

unify

(-> Atom Atom Atom Atom %Undefined%)

Matches the first two arguments and returns the third if they match, the fourth otherwise

Parameters

• Atom — First atom to unify
• Atom — Second atom to unify
• Atom — Result if they match
• Atom — Result otherwise

Returns %Undefined% — The third argument if matched, otherwise the fourth

union

(-> Atom Atom %Undefined%)

Returns the union of two nondeterministic inputs

Parameters

• Atom — Nondeterministic set of values
• Atom — Another nondeterministic set of values

Returns %Undefined% — Union of the sets

union-atom

Returns the union of two tuples

Parameters

• %Undefined% — List of values
• %Undefined% — List of values

Returns %Undefined% — Union of the tuples

unique

(-> Atom %Undefined%)

Returns only the unique values from a nondeterministic input

Parameters

• Atom — Nondeterministic set of values

Returns %Undefined% — Unique values

unique-atom

Returns only the unique values from a tuple

Parameters

• %Undefined% — List of values

Returns %Undefined% — Unique values

with_mutex

(-> Atom Atom %Undefined%)

PeTTa-compatible single-threaded wrapper that evaluates its body

Parameters

• Atom — Mutex name
• Atom — Body to evaluate

Returns %Undefined% — Body result

with-mutex

(-> Atom Atom %Undefined%)

Evaluates a body while holding a mutex with the given name

Parameters

• Atom — Mutex name
• Atom — Body to evaluate

Returns %Undefined% — Body result

xor

(-> Bool Bool Bool)

Logical exclusive or

Parameters

• Bool — First argument
• Bool — Second argument

Returns Bool — True if exactly one input is True