Top-level API to execute MeTTa code. More...

Classes
struct	step_result_t
	Contains the state for an in-flight interpreter operation. More...
struct	metta_t
	A top-level MeTTa runner. More...
struct	run_context_t
	An interface object providing access to the MeTTa run interface. More...
struct	runner_state_t
	Represents the state of an in-flight MeTTa execution run. More...

Functions
struct step_result_t	interpret_init (struct space_t space, const atom_ref_t expr)
	Initializes an interpreter operation and take the initial step.
struct step_result_t	interpret_step (struct step_result_t step)
	Takes a subsequent step in an in-flight interpreter operation.
uintptr_t	step_to_str (const struct step_result_t step, char buf, uintptr_t buf_len)
	Renders a text description of a step_result_t into a buffer.
bool	step_has_next (const struct step_result_t *step)
	Examines a step_result_t to determine if more work is needed.
void	step_get_result (struct step_result_t step, c_atom_vec_callback_t callback, void *context)
	Consumes a step_result_t and provides the ultimate outcome of a MeTTa interpreter session.
struct metta_t	metta_new (void)
	Creates a new top-level MeTTa Runner, with only the Rust stdlib loaded.
struct metta_t	metta_new_with_stdlib_loader (struct module_loader_t stdlib_loader_mov, struct space_t space_ref, struct env_builder_t env_builder_mov)
	Creates a new top-level MeTTa Runner, with the specified stdlib module loaded.
struct metta_t	metta_new_core (struct space_t *space, struct env_builder_t env_builder)
	Creates a new core MeTTa runner, with no loaded stdlib nor initialization.
struct metta_t	metta_clone_handle (const struct metta_t *metta)
	Clones a metta_t handle.
void	metta_free (struct metta_t metta)
	Frees a metta_t handle.
const char *	metta_err_str (const struct metta_t *metta)
	Returns the error string associated with the last metta_run, metta_evaluate_atom, or metta_load_module call.
bool	metta_eq (const struct metta_t a, const struct metta_t b)
	Compares two metta_t handles to test whether the referenced MeTTa runner is the same.
struct space_t	metta_space (struct metta_t *metta)
	Provides access to the Space of the runner's top-level module.
struct tokenizer_t	metta_tokenizer (struct metta_t *metta)
	Provides access to the Tokenizer of the runner's top-level module.
uintptr_t	metta_working_dir (const struct metta_t metta, char buf, uintptr_t buf_len)
	Renders the working directory of the runner's environment into a buffer.
void	metta_run (struct metta_t metta, struct sexpr_parser_t parser, c_atom_vec_callback_t callback, void context)
	Runs the MeTTa runner until the input text has been fully parsed and evaluated.
void	metta_evaluate_atom (struct metta_t metta, atom_t atom, c_atom_vec_callback_t callback, void context)
	Runs the MeTTa runner to evaluate an input Atom.
struct module_id_t	metta_load_module_direct (struct metta_t metta_ref, const char name_ref, struct module_loader_t *loader_mov)
	Loads a module directly into the runner, from a module_loader_t.
struct module_id_t	metta_load_module_at_path (struct metta_t metta, const char path, const char *name)
	Loads a module into the runner from a module resource at a file system path.
struct space_t	metta_get_module_space (const struct metta_t *metta, struct module_id_t mod_id)
	Returns the Space for a loaded module.
void	run_context_push_parser (struct run_context_t *run_context, struct sexpr_parser_t parser)
	Appends the parser to the Run Context's queue of input to run.
struct metta_t	run_context_get_metta (const struct run_context_t *run_context)
	Returns a pointer to the metta_t runner that a run context is executing within.
struct space_t	run_context_get_space (const struct run_context_t *run_context)
	Provides access to the Space of the currently running module.
struct tokenizer_t	run_context_get_tokenizer (const struct run_context_t *run_context)
	Provides access to the Tokenizer of the currently running module.
void	run_context_raise_error (struct run_context_t run_context, const char message)
	Sets a runtime error.
struct runner_state_t	runner_state_new_with_parser (const struct metta_t *metta, struct sexpr_parser_t parser)
	Creates a runner_state_t, to use for step-wise execution of MeTTa text.
struct runner_state_t	runner_state_new_with_atoms (const struct metta_t metta, const struct atom_vec_t atoms)
	Creates a runner_state_t, to use for step-wise execution of a list of atoms.
void	runner_state_free (struct runner_state_t state)
	Frees a runner_state_t.
const char *	runner_state_err_str (const struct runner_state_t *state)
	Returns the error string associated with the last runner_state_step
void	runner_state_step (struct runner_state_t *state)
	Runs one step of the runner.
bool	runner_state_is_complete (const struct runner_state_t *state)
	Returns whether or not the runner_state_t has completed all outstanding work.
uintptr_t	runner_state_to_str (const struct runner_state_t state, char buf, uintptr_t buf_len)
	Renders a text description of a runner_state_t into a buffer.
void	runner_state_current_results (const struct runner_state_t state, c_atom_vec_callback_t callback, void context)
	Accesses the current in-flight results in the runner_state_t.

Detailed Description

Top-level API to execute MeTTa code.

This Interface includes the types and functions to instantiate a MeTTa interpreter and step through MeTTa code.

Function Documentation

◆ interpret_init()

struct step_result_t interpret_init	(	struct space_t *	space,
		const atom_ref_t *	expr )

Initializes an interpreter operation and take the initial step.

Parameters

[in]	space	A pointer to the Space in which to perform the operation
[in]	expr	A pointer to an atom_t or atom_ref_t Expression atom to interpret

Returns: A step_result_t representing the outcome from the initial step

Note: The returned value may represent an error, an immediate result value, or it may be necessary to call interpret_step() in a loop to fully evaluate the execution plan. Ultimately step_get_result() must be called to release the returned step_result_t

◆ interpret_step()

struct step_result_t interpret_step ( struct step_result_t step )

Takes a subsequent step in an in-flight interpreter operation.

Parameters

[in] step The existing state for the in-flight interpreter operation

Returns: A new step_result_t representing the outcome from the step

◆ metta_clone_handle()

struct metta_t metta_clone_handle ( const struct metta_t * metta )

Clones a metta_t handle.

Parameters

[in] metta The handle to clone

Returns: The newly cloned metta_t handle, pointing to the same underlying runner

Note: The caller must take ownership responsibility for the returned metta_t, and free it with metta_free()

◆ metta_eq()

bool metta_eq	(	const struct metta_t *	a,
		const struct metta_t *	b )

Compares two metta_t handles to test whether the referenced MeTTa runner is the same.

Parameters

[in]	a	A pointer to the first runner handle
[in]	b	A pointer to the first runner handle

Returns: True if the two handles reference the same runner, otherwise False

◆ metta_err_str()

const char * metta_err_str ( const struct metta_t * metta )

Returns the error string associated with the last metta_run, metta_evaluate_atom, or metta_load_module call.

Parameters

[in] metta A pointer to the MeTTa handle

Returns: A pointer to the C-string containing the error that occurred, or NULL if no error occurred

Warning: The returned pointer should NOT be freed. It must never be accessed after the metta_t has been freed, or any subsequent call to metta_run, metta_evaluate_atom, or metta_load_module has been made.

◆ metta_evaluate_atom()

void metta_evaluate_atom	(	struct metta_t *	metta,
		atom_t	atom,
		c_atom_vec_callback_t	callback,
		void *	context )

Runs the MeTTa runner to evaluate an input Atom.

Parameters

[in]	metta	A pointer to the runner handle
[in]	atom	The atom_t representing the atom to evaluate
[in]	callback	A function that will be called to provide a vector of atoms produced by the evaluation
[in]	context	A pointer to a caller-defined structure to facilitate communication with the callback function

Note: If this function encounters an error, the callback will not be called and the error may be accessed with metta_err_str()

Warning: This function takes ownership of the provided atom_t, so it must not be subsequently accessed or freed

◆ metta_free()

void metta_free ( struct metta_t metta )

Frees a metta_t handle.

Parameters

[in] metta The handle to free

Note: The underlying runner may be deallocated if all handles that refer to it have been freed, otherwise the runner itself won't be freed

◆ metta_get_module_space()

struct space_t metta_get_module_space	(	const struct metta_t *	metta,
		struct module_id_t	mod_id )

Returns the Space for a loaded module.

Parameters

[in]	metta	A pointer to the handle specifying the runner into which to load the module
[in]	mod_id	The module_id_t of the loaded module to access

Returns: The space_t for the module's Space

Note: The returned space_t must be freed with space_free

◆ metta_load_module_at_path()

struct module_id_t metta_load_module_at_path	(	struct metta_t *	metta,
		const char *	path,
		const char *	name )

Loads a module into the runner from a module resource at a file system path.

Parameters

[in]	metta	A pointer to the handle specifying the runner into which to load the module
[in]	path	A C-string specifying the path from which to load the module
[in]	name	A C-string specifying a name for the module, or NULL if you want the module to be private and unable to be loaded by name

Returns: The module_id_t for the loaded module, or invalid if there was an error

Note: This function effectively bypasses the catalog, for situations where you wish to load a specific module from disk; If this function encounters an error, the error may be accessed with metta_err_str()

◆ metta_load_module_direct()

struct module_id_t metta_load_module_direct	(	struct metta_t *	metta_ref,
		const char *	name_ref,
		struct module_loader_t *	loader_mov )

Loads a module directly into the runner, from a module_loader_t.

Parameters

[in]	metta_ref	A pointer to the handle specifying the runner into which to load the module
[in]	name_ref	A C-string specifying a name for the module
[in]	loader_mov	The module_loader_t instance to load the module

Returns: The module_id_t for the loaded module, or invalid if there was an error

Note: This function might be useful to provide MeTTa modules that are built-in as part of your application; If this function encounters an error, the error may be accessed with metta_err_str()

◆ metta_new()

struct metta_t metta_new ( void )

Creates a new top-level MeTTa Runner, with only the Rust stdlib loaded.

Returns: A metta_t handle to the newly created runner

Note: The caller must take ownership responsibility for the returned metta_t, and free it with metta_free()

◆ metta_new_core()

struct metta_t metta_new_core	(	struct space_t *	space,
		struct env_builder_t	env_builder )

Creates a new core MeTTa runner, with no loaded stdlib nor initialization.

Parameters

[in]	space	A pointer to a handle for the Space for use as the space of the top-level module
[in]	environment	An env_builder_t handle to configure the environment to use

Returns: A metta_t handle to the newly created runner

Note: The caller must take ownership responsibility for the returned metta_t, and free it with metta_free(); This function does not load any stdlib, nor does it run the init.metta file from the environment

◆ metta_new_with_stdlib_loader()

struct metta_t metta_new_with_stdlib_loader	(	struct module_loader_t *	stdlib_loader_mov,
		struct space_t *	space_ref,
		struct env_builder_t	env_builder_mov )

Creates a new top-level MeTTa Runner, with the specified stdlib module loaded.

Parameters

[in]	space_ref	A pointer to a handle for the Space for use in the Runner's top-level module
[in]	env_builder_mov	An env_builder_t handle to configure the environment to use
[in]	stdlib_loader_mov	Stdlib loader implemented in C code. Pass NULL to use the default stdlib

Returns: A metta_t handle to the newly created Runner

Note: The caller must take ownership responsibility for the returned metta_t, and free it with metta_free(); Most callers can simply call metta_new. This function is provided to support languages with their own stdlib, that needs to be loaded before the init.metta file is run

◆ metta_run()

void metta_run	(	struct metta_t *	metta,
		struct sexpr_parser_t	parser,
		c_atom_vec_callback_t	callback,
		void *	context )

Runs the MeTTa runner until the input text has been fully parsed and evaluated.

Parameters

[in]	metta	A pointer to the runner handle
[in]	parser	An S-Expression Parser containing the MeTTa text
[in]	callback	A function that will be called to provide a vector of atoms produced by the evaluation
[in]	context	A pointer to a caller-defined structure to facilitate communication with the callback function

Note: If this function encounters an error, the callback will not be called and the error may be accessed with metta_err_str()

Warning: Ownership of the provided parser will be taken by this function, so it must not be subsequently accessed nor freed.

◆ metta_space()

struct space_t metta_space ( struct metta_t * metta )

Provides access to the Space of the runner's top-level module.

Parameters

[in] metta A pointer to the runner handle

Returns: A Space handle, to access the Space of the runner's top-level module

Note: The caller must take ownership responsibility for the returned space_t and free it with space_free()

◆ metta_tokenizer()

struct tokenizer_t metta_tokenizer ( struct metta_t * metta )

Provides access to the Tokenizer of the runner's top-level module.

Parameters

[in] metta A pointer to the runner handle

Returns: A Tokenizer handle, to access the Tokenizer of the runner's top-level module

Note: The caller must take ownership responsibility for the returned tokenizer_t and free it with tokenizer_free()

◆ metta_working_dir()

uintptr_t metta_working_dir	(	const struct metta_t *	metta,
		char *	buf,
		uintptr_t	buf_len )

Renders the working directory of the runner's environment into a buffer.

Parameters

[in]	metta	A pointer to the runner handle
[out]	buf	A buffer into which the path will be rendered
[in]	buf_len	The maximum allocated size of buf

Returns: The length of the path string, minus the string terminator character. Returns 0 if the runner's environment has no working directory.

Note: If return_value > buf_len + 1, then the text was not fully rendered and this function should be called again with a larger buffer.

◆ run_context_get_metta()

struct metta_t run_context_get_metta ( const struct run_context_t * run_context )

Returns a pointer to the metta_t runner that a run context is executing within.

Parameters

[in] run_context A pointer to the run_context_t to access the runner API

Returns: A metta_t handle to access the runner

Note: The returned metta_t handle is must be freed using metta_free

◆ run_context_get_space()

struct space_t run_context_get_space ( const struct run_context_t * run_context )

Provides access to the Space of the currently running module.

Parameters

[in] run_context A pointer to the run_context_t to access the runner API

Returns: A Space handle, to access the Space of the currently running module

Note: The caller must take ownership responsibility for the returned space_t and free it with space_free()

◆ run_context_get_tokenizer()

struct tokenizer_t run_context_get_tokenizer ( const struct run_context_t * run_context )

Provides access to the Tokenizer of the currently running module.

Parameters

[in] run_context A pointer to the run_context_t to access the runner API

Returns: A Tokenizer handle, to access the Tokenizer of the currently running module

Note: The caller must take ownership responsibility for the returned tokenizer_t and free it with tokenizer_free()

◆ run_context_push_parser()

void run_context_push_parser	(	struct run_context_t *	run_context,
		struct sexpr_parser_t	parser )

Appends the parser to the Run Context's queue of input to run.

Parameters

[in]	run_context	A pointer to the run_context_t to access the runner API
[in]	parser	An S-Expression Parser containing the MeTTa source code to execute

◆ run_context_raise_error()

void run_context_raise_error	(	struct run_context_t *	run_context,
		const char *	message )

Sets a runtime error.

Parameters

[in]	run_context	A pointer to the run_context_t to access the runner API
[in]	message	A C-string specifying an error message

Note: Raising an error through this function will cause the MeTTa interpreter to take an error pathway

◆ runner_state_current_results()

void runner_state_current_results	(	const struct runner_state_t *	state,
		c_atom_vec_callback_t	callback,
		void *	context )

Accesses the current in-flight results in the runner_state_t.

Parameters

[in]	state	The runner_state_t within which to preview results
[in]	callback	A function that will be called to provide a vector of atoms produced by the evaluation
[in]	context	A pointer to a caller-defined structure to facilitate communication with the callback function

Warning: The provided results will be overwritten by the next call to metta_run_step, so the caller must clone the result atoms if they are needed for an extended period of time

◆ runner_state_err_str()

const char * runner_state_err_str ( const struct runner_state_t * state )

Returns the error string associated with the last runner_state_step

Parameters

[in] state A pointer to the runner state

Returns: A pointer to the C-string containing the error that occurred, or NULL if no error occurred

Warning: The returned pointer should NOT be freed. It must never be accessed after the runner_state_t has been freed, or any subsequent call to runner_state_step has been made.

◆ runner_state_free()

void runner_state_free ( struct runner_state_t state )

Frees a runner_state_t.

Parameters

[in] node The runner_state_t to free

◆ runner_state_is_complete()

bool runner_state_is_complete ( const struct runner_state_t * state )

Returns whether or not the runner_state_t has completed all outstanding work.

Parameters

[in] state The runner_state_t to inspect

Returns: true if the runner has already concluded, or false if there is more work to do

◆ runner_state_new_with_atoms()

struct runner_state_t runner_state_new_with_atoms	(	const struct metta_t *	metta,
		const struct atom_vec_t *	atoms )

Creates a runner_state_t, to use for step-wise execution of a list of atoms.

Parameters

[in]	metta	A pointer to the runner handle in which to perform the run
[in]	atoms	A pointer to an atom_vec_t containing the atoms to run

Returns: The newly created runner_state_t, which can begin evaluating MeTTa code

Warning: The referenced atoms atom_vec_t must not be modified nor freed while the runner_state_t remains active

Note: The returned runner_state_t handle must be freed with runner_state_free()

◆ runner_state_new_with_parser()

struct runner_state_t runner_state_new_with_parser	(	const struct metta_t *	metta,
		struct sexpr_parser_t	parser )

Creates a runner_state_t, to use for step-wise execution of MeTTa text.

Parameters

[in]	metta	A pointer to the runner handle in which to perform the run
[in]	parser	An S-Expression Parser containing the MeTTa text

Returns: The newly created runner_state_t, which can begin evaluating MeTTa code

Warning: Ownership of the provided parser will be taken by this function, so it must not be subsequently accessed nor freed.

Note: The returned runner_state_t handle must be freed with runner_state_free()

◆ runner_state_step()

void runner_state_step ( struct runner_state_t * state )

Runs one step of the runner.

Parameters

[in] state A pointer to the in-flight runner state

Note: If this function encounters an error, the error may be accessed with runner_state_err_str()

◆ runner_state_to_str()

uintptr_t runner_state_to_str	(	const struct runner_state_t *	state,
		char *	buf,
		uintptr_t	buf_len )

Renders a text description of a runner_state_t into a buffer.

Parameters

[in]	state	A pointer to a runner_state_t to render
[out]	buf	A buffer into which the text will be rendered
[in]	buf_len	The maximum allocated size of buf

Returns: The length of the description string, minus the string terminator character. If return_value > buf_len + 1, then the text was not fully rendered and this function should be called again with a larger buffer.

◆ step_get_result()

void step_get_result	(	struct step_result_t	step,
		c_atom_vec_callback_t	callback,
		void *	context )

Consumes a step_result_t and provides the ultimate outcome of a MeTTa interpreter session.

Parameters

[in]	step	A pointer to a step_result_t to render
[in]	callback	A function that will be called to provide a vector of all atoms resulting from the interpreter session
[in]	context	A pointer to a caller-defined structure to facilitate communication with the callback function

◆ step_has_next()

bool step_has_next ( const struct step_result_t * step )

Examines a step_result_t to determine if more work is needed.

Parameters

[in] step A pointer to the step_result_t representing the in-flight interpreter operation

Returns: true if the operation plan indicates that more work is needed to finalize results, otherwise false

◆ step_to_str()

uintptr_t step_to_str	(	const struct step_result_t *	step,
		char *	buf,
		uintptr_t	buf_len )

Renders a text description of a step_result_t into a buffer.

Parameters

[in]	step	A pointer to a step_result_t to render
[out]	buf	A buffer into which the text will be rendered
[in]	buf_len	The maximum allocated size of buf

Returns: The length of the description string, minus the string terminator character. If return_value > buf_len + 1, then the text was not fully rendered and this function should be called again with a larger buffer.

Classes

Functions

Detailed Description

Function Documentation

◆ interpret_init()

◆ interpret_step()

◆ metta_clone_handle()

◆ metta_eq()

◆ metta_err_str()

◆ metta_evaluate_atom()

◆ metta_free()

◆ metta_get_module_space()

◆ metta_load_module_at_path()

◆ metta_load_module_direct()

◆ metta_new()

◆ metta_new_core()

◆ metta_new_with_stdlib_loader()

◆ metta_run()

◆ metta_space()

◆ metta_tokenizer()

◆ metta_working_dir()

◆ run_context_get_metta()

◆ run_context_get_space()

◆ run_context_get_tokenizer()

◆ run_context_push_parser()

◆ run_context_raise_error()

◆ runner_state_current_results()

◆ runner_state_err_str()

◆ runner_state_free()

◆ runner_state_is_complete()

◆ runner_state_new_with_atoms()

◆ runner_state_new_with_parser()

◆ runner_state_step()

◆ runner_state_to_str()

◆ step_get_result()

◆ step_has_next()

◆ step_to_str()