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!

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

Parameters

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

Returns %Undefined% — 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!

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

Parameters

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

Returns %Undefined% — 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, or max-stack-depth

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

* {#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

@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

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

alpha-unique-atom

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 (->))

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

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

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

concat

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

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

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

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

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

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

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

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

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

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

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-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)

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

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

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

sort

(-> %Undefined% Expression)

Sorts an expression by standard atom order and removes duplicate atoms

Parameters

• %Undefined% — Expression

Returns Expression — Sorted expression with duplicates removed

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

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

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

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)

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

unique

(-> Atom %Undefined%)

Returns only the unique values from a nondeterministic input

Parameters

• Atom — Nondeterministic set 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