Interface for working with atom matching and variable-to-atom binding. More...

Classes
struct	bindings_set_t
	Represents a set of Bindings frames. Potentially expressing all possible matches produced by a match operarion. More...
struct	bindings_t
	Represents a single Bindings frame, which is a group of mutually-compatible variable <-> atom associations, providing a scope in which variable have definde values. More...

Typedefs
typedef void(*	c_var_binding_callback_t) (atom_ref_t var, atom_ref_t value, void *context)
	Function signature for a callback providing access to a variable <-> atom pair, associated with a binding.
typedef void(*	bindings_mut_callback_t) (struct bindings_t bindings, void context)
	Function signature for a callback providing mutable access to individual Bindings frames within a Bindings Set.

Functions
struct bindings_set_t	atom_match_atom (const atom_ref_t a, const atom_ref_t b)
	Matches one atom with another, establishing bindings between them.
struct bindings_t	bindings_new (void)
	Creates a new bindings_t containing no variable <-> atom associations, leaving all variables free to match any atom.
void	bindings_free (struct bindings_t bindings)
	Frees a bindings_t
struct bindings_t	bindings_clone (const struct bindings_t *bindings)
	Makes a "deep copy" of a bindings_t
uintptr_t	bindings_to_str (const struct bindings_t bindings, char buf, uintptr_t buf_len)
	Renders a text description of a bindings_t
bool	bindings_eq (const struct bindings_t a, const struct bindings_t b)
	Checks if two bindings_t objects contain identical associations.
void	bindings_traverse (const struct bindings_t bindings, c_var_binding_callback_t callback, void context)
	Iterates each variable <-> Atom association within a bindings_t
bool	bindings_add_var_binding (struct bindings_t *bindings, atom_t var, atom_t atom)
	Adds a new variable <-> atom association within a bindings_t
bool	bindings_is_empty (const struct bindings_t *bindings)
	Checks if a bindings_t contains no associations.
atom_t	bindings_resolve (const struct bindings_t *bindings, atom_t var)
	Returns the atom bound to the supplied variable name in the bindings_t
struct bindings_set_t	bindings_merge (struct bindings_t _self, const struct bindings_t *other)
	Merges two bindings_t Bindings frames together into a Bindings Set.
void	bindings_narrow_vars (struct bindings_t bindings, const struct atom_vec_t vars)
	Removes all variable associations from a bindings_t except those in the supplied list.
struct bindings_set_t	bindings_set_empty (void)
	Creates a new bindings_set_t without any Bindings frames. Conceptually this means no valid matches exist.
struct bindings_set_t	bindings_set_single (void)
	Creates a new bindings_set_t with one new Bindings frame. Conceptually this means all variables are able to take on any value.
struct bindings_set_t	bindings_set_from_bindings (struct bindings_t bindings)
	Creates a new bindings_set_t with the specified Bindings frame.
void	bindings_set_push (struct bindings_set_t *set, struct bindings_t bindings)
	Adds a Bindings frame to an existing bindings_set_t
void	bindings_set_free (struct bindings_set_t set)
	Frees a bindings_set_t
struct bindings_set_t	bindings_set_clone (const struct bindings_set_t *set)
	Makes a "deep copy" of a bindings_set_t
bool	bindings_set_eq (const struct bindings_set_t a, const struct bindings_set_t b)
	Checks if two bindings_set_t objects contain identical associations.
uintptr_t	bindings_set_to_str (const struct bindings_set_t set, char buf, uintptr_t buf_len)
	Renders a text description of a bindings_set_t
bool	bindings_set_is_empty (const struct bindings_set_t *set)
	Checks if a bindings_set_t contains no Bindings frames, and thus indicates no match.
bool	bindings_set_is_single (const struct bindings_set_t *set)
	Checks if a bindings_set_t contains a frame with no associations, and is thus allows variables to take on any value.
void	bindings_set_iterate (struct bindings_set_t set, bindings_mut_callback_t callback, void context)
	Provides sequential access to each Bindings frame within a Bindings set.
void	bindings_set_add_var_equality (struct bindings_set_t set, const atom_ref_t a, const atom_ref_t *b)
	Asserts equality between two Variable atoms in a Bindings set.
void	bindings_set_add_var_binding (struct bindings_set_t set, const atom_ref_t var, const atom_ref_t *value)
	Adds a new variable <-> atom association to every Bindings frame in a Bindings set.
void	bindings_set_merge_into (struct bindings_set_t _self, const struct bindings_set_t other)
	Merges the contents of one Bindings set into another Bindings set.

Detailed Description

Interface for working with atom matching and variable-to-atom binding.

Typedef Documentation

◆ bindings_mut_callback_t

typedef void(* bindings_mut_callback_t) (struct bindings_t *bindings, void *context)

Function signature for a callback providing mutable access to individual Bindings frames within a Bindings Set.

Parameters

[in]	bindings	A pointer to the bindings_t. It is ok to call functions that modify the bindings_t within the callback
[in]	context	The context state pointer initially passed to the upstream function initiating the callback

◆ c_var_binding_callback_t

typedef void(* c_var_binding_callback_t) (atom_ref_t var, atom_ref_t value, void *context)

Function signature for a callback providing access to a variable <-> atom pair, associated with a binding.

Parameters

[in]	var	A reference to the Variable atom. This atom should not be modified or freed by the callback
[in]	value	A reference to the other atom associated with the variable. This atom should not be modified or freed by the callback
[in]	context	The context state pointer initially passed to the upstream function initiating the callback

Function Documentation

◆ atom_match_atom()

struct bindings_set_t atom_match_atom	(	const atom_ref_t *	a,
		const atom_ref_t *	b )

Matches one atom with another, establishing bindings between them.

Parameters

[in]	a	A pointer to an atom_t or an atom_ref_t to match
[in]	b	A pointer to another atom_t or an atom_ref_t to match against

Returns: A bindings_set_t representing all variable <-> atom bindings established by the match

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

◆ bindings_add_var_binding()

bool bindings_add_var_binding	(	struct bindings_t *	bindings,
		atom_t	var,
		atom_t	atom )

Adds a new variable <-> atom association within a bindings_t

Parameters

[in]	bindings	A pointer to the bindings_t to add the association to
[in]	var	The Variable atom (L-value) for the variable <-> atom association
[in]	atom	The other atom (R-value) for the variable <-> atom association

Returns: true if the bindings_t has been sucessfully updated, and false if the new association would conflict with existing associations in the Bindings frame

Warning: This function takes ownership of both the var and atom atoms, so they must not be subsequently accessed or freed

◆ bindings_clone()

struct bindings_t bindings_clone ( const struct bindings_t * bindings )

Makes a "deep copy" of a bindings_t

Parameters

[in] bindings A pointer to the bindings_t to clone

Returns: A newly created bindings_t

Note: The caller must take ownership responsibility for the returned bindings_t

◆ bindings_eq()

bool bindings_eq	(	const struct bindings_t *	a,
		const struct bindings_t *	b )

Checks if two bindings_t objects contain identical associations.

Parameters

[in]	a	A pointer to a bindings_t representing the first Bindings frame
[in]	b	A pointer to a bindings_t representing the second Bindings frame

Returns: true is the Bindings frames are identical, and false otherwise

◆ bindings_free()

void bindings_free ( struct bindings_t bindings )

Frees a bindings_t

Parameters

[in] bindings The bindings_t to free

◆ bindings_is_empty()

bool bindings_is_empty ( const struct bindings_t * bindings )

Checks if a bindings_t contains no associations.

Parameters

[in] bindings A pointer to the bindings_t to inspect

Returns: true is the Bindings frame contains no associations, and false otherwise

◆ bindings_merge()

struct bindings_set_t bindings_merge	(	struct bindings_t	_self,
		const struct bindings_t *	other )

Merges two bindings_t Bindings frames together into a Bindings Set.

Parameters

[in]	_self	The first bindings_t to merge. Ownership of this argument is taken by this function
[in]	other	A pointer to the second bindings_t to merge. This argument is not modified

Returns: The bindings_set_t that results from the merge

Warning: This function takes ownership of the _self argument. After calling this function, the bindings_t passed as _self must not be accessed or freed

Note: The bindings_set_t returned from this function must be freed with bindings_set_free()

◆ bindings_narrow_vars()

void bindings_narrow_vars	(	struct bindings_t *	bindings,
		const struct atom_vec_t *	vars )

Removes all variable associations from a bindings_t except those in the supplied list.

Parameters

[in]	bindings	A pointer to the bindings_t to modify
[in]	vars	A pointer to a vec of Variable atoms, to specify which variables should remain in the Bindings

◆ bindings_new()

struct bindings_t bindings_new ( void )

Creates a new bindings_t containing no variable <-> atom associations, leaving all variables free to match any atom.

Returns: The new bindings_t

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

◆ bindings_resolve()

atom_t bindings_resolve	(	const struct bindings_t *	bindings,
		atom_t	var )

Returns the atom bound to the supplied variable name in the bindings_t

Parameters

[in]	bindings	A pointer to the bindings_t to inspect
[in]	var	The Variable atom (L-value) for the variable <-> atom association

Returns: The atom_t representing the atom that corresponds to the specified variable, or a NULL atom_ref_t if the variable is not present.

Note: The caller must take ownership responsibility for the returned atom_t, if it is not NULL

◆ bindings_set_add_var_binding()

void bindings_set_add_var_binding	(	struct bindings_set_t *	set,
		const atom_ref_t *	var,
		const atom_ref_t *	value )

Adds a new variable <-> atom association to every Bindings frame in a Bindings set.

Parameters

[in]	set	A pointer to the bindings_set_t to modify
[in]	var	A pointer to the Variable atom
[in]	value	A pointer to the other atom to associate the variable with

Note: This function is equivalent to calling bindings_add_var_binding for each Bindings frame in the Bindings set, but new Bindings frames may be generated if the new association conflicts with existing associations in existing frames

◆ bindings_set_add_var_equality()

void bindings_set_add_var_equality	(	struct bindings_set_t *	set,
		const atom_ref_t *	a,
		const atom_ref_t *	b )

Asserts equality between two Variable atoms in a Bindings set.

Parameters

[in]	set	A pointer to the bindings_set_t to modify
[in]	a	A pointer to the first Variable atom for the variable <-> variable association
[in]	b	A pointer to the second Variable atom for the variable <-> variable association

Note: Both a and b must be Variable atoms

◆ bindings_set_clone()

struct bindings_set_t bindings_set_clone ( const struct bindings_set_t * set )

Makes a "deep copy" of a bindings_set_t

Parameters

[in] set A pointer to the bindings_set_t to use as the source for the clone

Returns: The new cloned bindings_set_t

Note: The bindings_set_t returned from this function must be freed with bindings_set_free()

◆ bindings_set_empty()

struct bindings_set_t bindings_set_empty ( void )

Creates a new bindings_set_t without any Bindings frames. Conceptually this means no valid matches exist.

Returns: The empty bindings_set_t

Note: The bindings_set_t returned from this function must be freed with bindings_set_free()

◆ bindings_set_eq()

bool bindings_set_eq	(	const struct bindings_set_t *	a,
		const struct bindings_set_t *	b )

Checks if two bindings_set_t objects contain identical associations.

Parameters

[in]	a	A pointer to a bindings_set_t representing the first Bindings Set
[in]	b	A pointer to a bindings_set_t representing the second Bindings Set

Returns: true is the Bindings Sets are identical, and false otherwise

◆ bindings_set_free()

void bindings_set_free ( struct bindings_set_t set )

Frees a bindings_set_t

Parameters

[in] set The bindings_set_t to free

◆ bindings_set_from_bindings()

struct bindings_set_t bindings_set_from_bindings ( struct bindings_t bindings )

Creates a new bindings_set_t with the specified Bindings frame.

Parameters

[in] bindings The bindings_t to incorporate into the new Bindings Set. Ownership of this argument is taken by this function

Returns: The new bindings_set_t

Warning: This function takes ownership of the bindings argument, and it must not be subsequently accessed or freed after calling this function

Note: The bindings_set_t returned from this function must be freed with bindings_set_free()

◆ bindings_set_is_empty()

bool bindings_set_is_empty ( const struct bindings_set_t * set )

Checks if a bindings_set_t contains no Bindings frames, and thus indicates no match.

Parameters

[in] set A pointer to the bindings_set_t to inspect

Returns: true is the Bindings set is empty, and false otherwise

◆ bindings_set_is_single()

bool bindings_set_is_single ( const struct bindings_set_t * set )

Checks if a bindings_set_t contains a frame with no associations, and is thus allows variables to take on any value.

Parameters

[in] set A pointer to the bindings_set_t to inspect

Returns: true is the Bindings set is "single", and false otherwise

Note: Perhaps the word "single" is not a good description of its meaning. See https://github.com/trueagi-io/hyperon-experimental/issues/281

◆ bindings_set_iterate()

void bindings_set_iterate	(	struct bindings_set_t *	set,
		bindings_mut_callback_t	callback,
		void *	context )

Provides sequential access to each Bindings frame within a Bindings set.

Parameters

[in]	set	A pointer to the bindings_set_t to iterate
[in]	callback	A function that will be called to provide access to each Bindings frame
[in]	context	A pointer to a caller-defined structure to facilitate communication with the callback function

Note: The current implementation of this function allows Bindings frames to be modified by the callback function, however this may not be possible in future versions of Hyperon

◆ bindings_set_merge_into()

void bindings_set_merge_into	(	struct bindings_set_t *	_self,
		const struct bindings_set_t *	other )

Merges the contents of one Bindings set into another Bindings set.

Parameters

[in]	_self	A pointer to the bindings_set_t to modify
[in]	other	A pointer to another bindings_set_t

Note: This function merges each Bindings frame in the _self set with each frame in the other set, using the same logic as bindings_merge. New frames will potentially be created when associations are found to conflict

◆ bindings_set_push()

void bindings_set_push	(	struct bindings_set_t *	set,
		struct bindings_t	bindings )

Adds a Bindings frame to an existing bindings_set_t

Parameters

[in]	set	The bindings_set_t to add bindings into
[in]	bindings	The bindings_t to incorporate into set. Ownership of this argument is taken by this function

Warning: This function takes ownership of the bindings argument, and it must not be subsequently accessed or freed after calling this function

◆ bindings_set_single()

struct bindings_set_t bindings_set_single ( void )

Creates a new bindings_set_t with one new Bindings frame. Conceptually this means all variables are able to take on any value.

Returns: The new bindings_set_t

Note: The bindings_set_t returned from this function must be freed with bindings_set_free()

◆ bindings_set_to_str()

uintptr_t bindings_set_to_str	(	const struct bindings_set_t *	set,
		char *	buf,
		uintptr_t	buf_len )

Renders a text description of a bindings_set_t

Parameters

[in]	set	A pointer to the bindings_set_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.

◆ bindings_to_str()

uintptr_t bindings_to_str	(	const struct bindings_t *	bindings,
		char *	buf,
		uintptr_t	buf_len )

Renders a text description of a bindings_t

Parameters

[in]	bindings	A pointer to the bindings_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.

◆ bindings_traverse()

void bindings_traverse	(	const struct bindings_t *	bindings,
		c_var_binding_callback_t	callback,
		void *	context )

Iterates each variable <-> Atom association within a bindings_t

Parameters

[in]	bindings	A pointer to the bindings_t to iterate
[in]	callback	A function that will be called for each variable <-> atom pair within the Bindings frame
[in]	context	A pointer to a caller-defined structure to facilitate communication with the callback function

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ bindings_mut_callback_t

◆ c_var_binding_callback_t

Function Documentation

◆ atom_match_atom()

◆ bindings_add_var_binding()

◆ bindings_clone()

◆ bindings_eq()

◆ bindings_free()

◆ bindings_is_empty()

◆ bindings_merge()

◆ bindings_narrow_vars()

◆ bindings_new()

◆ bindings_resolve()

◆ bindings_set_add_var_binding()

◆ bindings_set_add_var_equality()

◆ bindings_set_clone()

◆ bindings_set_empty()

◆ bindings_set_eq()

◆ bindings_set_free()

◆ bindings_set_from_bindings()

◆ bindings_set_is_empty()

◆ bindings_set_is_single()

◆ bindings_set_iterate()

◆ bindings_set_merge_into()

◆ bindings_set_push()

◆ bindings_set_single()

◆ bindings_set_to_str()

◆ bindings_to_str()

◆ bindings_traverse()