atoms ¶

def __del__(self):
    """Frees an Atom and all associated resources."""
    hp.atom_free(self.catom)

def __eq__(self, other):
    """Checks if two atom objects represent the same conceptual Atom."""
    return (isinstance(other, Atom) and
            hp.atom_eq(self.catom, other.catom))

def __repr__(self):
    """Renders a human-readable text description of the Atom."""
    return hp.atom_to_str(self.catom)

def get_metatype(self):
    """Gets the metatype (kind) of the current Atom instance"""
    return hp.atom_get_metatype(self.catom)

def iterate(self):
    """Performs a depth-first exhaustive iteration of an Atom and all its children recursively."""
    res = hp.atom_iterate(self.catom)
    result = []
    for r in res:
        result.append(Atom._from_catom(r))
    return result

def match_atom(self, b):
    """Matches one Atom with another, establishing bindings between them."""
    return BindingsSet(hp.atom_match_atom(self.catom, b.catom))

def __deepcopy__(self, memodict={}):
    """Makes a "deep copy" of the bindings."""
    return self.clone()

def __del__(self):
    """Frees the binding resources."""
    if self.cbindings is not None:
        hp.bindings_free(self.cbindings)

def __enter__(self):
    """For context management."""
    return self

def __eq__(self, other):
    """Checks if two bindings objects contain identical associations."""
    return (isinstance(other, Bindings) and
            hp.bindings_eq(self.cbindings, other.cbindings))

def __exit__(self, exc_type, exc_val, exc_tb):
    """Frees resources on exit."""
    if self.cbindings is not None:
        hp.bindings_free(self.cbindings)
        self.cbindings = None

def __repr__(self):
    """Renders a text description of the bindings"""
    return hp.bindings_to_str(self.cbindings)

def add_var_binding(self, var: VariableAtom, atom: Atom) -> bool:
    """Adds a binding between a variable and an Atom."""
    return hp.bindings_add_var_binding(self.cbindings, var.catom, atom.catom)

def clone(self):
    """Makes a "deep copy" of the bindings"""
    return Bindings(hp.bindings_clone(self.cbindings))

def is_empty(self) -> bool:
    """Checks if a bindings contains no associations."""
    return hp.bindings_is_empty(self.cbindings)

def iterator(self):
    """Returns an iterator over the variable-atom pairs in the bindings"""
    res = hp.bindings_list(self.cbindings)
    result = [(Atom._from_catom(r[0]), Atom._from_catom(r[1])) for r in res]
    return iter(result)

def merge(self, other: 'Bindings') -> 'BindingsSet':
    """Merges with another Bindings instance, into a Bindings Set."""
    return BindingsSet(hp.bindings_merge(self.cbindings, other.cbindings))

def narrow_vars(self, vars ):
    """Keeps only specific variable associations."""
    cvars = hp.CVecAtom = hp.atom_vec_new()
    for var in vars:
        hp.atom_vec_push(cvars, var.catom)
    hp.bindings_narrow_vars(self.cbindings, cvars)
    hp.atom_vec_free(cvars)

def resolve(self, var: VariableAtom) -> Union[Atom, None]:
    """Finds the atom for a given variable"""
    raw_atom = hp.bindings_resolve(self.cbindings, var.catom)
    return None if raw_atom is None else Atom._from_catom(raw_atom)

def __deepcopy__(self, memodict={}):
    """Makes a "deep copy" of a BindingsSet"""
    return self.clone()

def __del__(self):
    """Frees the BindingsSet"""
    if self.c_set is not None:
        hp.bindings_set_free(self.c_set)
        self.c_set = None

def __enter__(self):
    """For context management."""
    return self

def __eq__(self, other):
    """Checks if other BindingsSet contains identical associations."""
    return (isinstance(other, BindingsSet) and
            hp.bindings_set_eq(self.c_set, other.c_set))

def __exit__(self, exc_type, exc_val, exc_tb):
    """Frees resources on exit."""
    if self.c_set is not None:
        hp.bindings_set_free(self.c_set)
        self.c_set = None

def __getitem__(self, key):
    """Gets a Bindings frame by index"""
    if self.shadow_list is None:
        result = hp.bindings_set_unpack(self.c_set)
        self.shadow_list = [{k: Atom._from_catom(v) for k, v in bindings.items()} for bindings in result]
    return self.shadow_list[key]

def __repr__(self):
    """Renders a text description of a BindingsSet"""
    return hp.bindings_set_to_str(self.c_set)

def add_var_binding(self, var: VariableAtom, value: Atom) -> bool:
    """Adds a new variable to atom association to every Bindings frame in a
    BindingsSet.
    """
    self.shadow_list = None
    return hp.bindings_set_add_var_binding(self.c_set, var.catom, value.catom)

def add_var_equality(self, a: Atom, b: Atom) -> bool:
    """Asserts equality between two Variable atoms in a BindingsSet."""
    self.shadow_list = None
    return hp.bindings_set_add_var_equality(self.c_set, a.catom, b.catom)

def clone(self):
    """Makes a "deep copy" of a BindingsSet"""
    return BindingsSet(hp.bindings_set_clone(self.c_set))

def empty():
    """Creates a new BindingsSet without any Bindings frames.
    Conceptually, this means no valid matches exist.
    """
    return BindingsSet(hp.bindings_set_empty())

def is_empty(self) -> bool:
    """Checks if a BindingsSet contains no Bindings frames, and thus indicates
    no match."""
    return hp.bindings_set_is_empty(self.c_set)

def is_single(self) -> bool:
    """Checks if a Bindings set contains a frame with no associations, and
    thus allows variables to take any value.
    """
    return hp.bindings_set_is_single(self.c_set)

def iterator(self):
    """Returns an iterator over all Bindings frames"""
    res = hp.bindings_set_list(self.c_set)
    result = [Bindings(r) for r in res]
    return iter(result)

def merge_into(self, input: Union['BindingsSet', Bindings]):
    """Merges the contents of another BindingsSet or Bindings frame."""
    self.shadow_list = None
    if isinstance(input, BindingsSet):
        hp.bindings_set_merge_into(self.c_set, input.c_set)
    else:
        new_set = BindingsSet(input)
        hp.bindings_set_merge_into(self.c_set, new_set.c_set)

def push(self, bindings: Bindings):
    """Adds a Bindings frame to an existing BindingsSet

    Parameters
    ----------
    bindings:
        The Bindings set to incorporate into set. Ownership of this argument is
        taken by this function.
    """
    self.shadow_list = None
    hp.bindings_set_push(self.c_set, bindings.cbindings)

def __del__(self):
    """Frees an Atom and all associated resources."""
    hp.atom_free(self.catom)

def __eq__(self, other):
    """Checks if two atom objects represent the same conceptual Atom."""
    return (isinstance(other, Atom) and
            hp.atom_eq(self.catom, other.catom))

def __repr__(self):
    """Renders a human-readable text description of the Atom."""
    return hp.atom_to_str(self.catom)

def get_children(self):
    """Returns all children Atoms of an expression"""
    return [Atom._from_catom(catom) for catom in hp.atom_get_children(self.catom)]

def get_metatype(self):
    """Gets the metatype (kind) of the current Atom instance"""
    return hp.atom_get_metatype(self.catom)

def iterate(self):
    """Performs a depth-first exhaustive iteration of an Atom and all its children recursively."""
    res = hp.atom_iterate(self.catom)
    result = []
    for r in res:
        result.append(Atom._from_catom(r))
    return result

def match_atom(self, b):
    """Matches one Atom with another, establishing bindings between them."""
    return BindingsSet(hp.atom_match_atom(self.catom, b.catom))

def __del__(self):
    """Frees an Atom and all associated resources."""
    hp.atom_free(self.catom)

def __eq__(self, other):
    """Checks if two atom objects represent the same conceptual Atom."""
    return (isinstance(other, Atom) and
            hp.atom_eq(self.catom, other.catom))

def __repr__(self):
    """Renders a human-readable text description of the Atom."""
    return hp.atom_to_str(self.catom)

def get_grounded_type(self):
    """Retrieve the grounded type of the GroundedAtom."""
    return Atom._from_catom(hp.atom_get_grounded_type(self.catom))

def get_metatype(self):
    """Gets the metatype (kind) of the current Atom instance"""
    return hp.atom_get_metatype(self.catom)

def get_object(self):
    """Returns the GroundedAtom object, or the Space wrapped inside a GroundedAtom,
       or convert supported Rust grounded objects into corresponding ValueObjects.
       Function raises TypeError when grounded atom cannot be converted to Python object. Uncatched
       Python exception can lead to Rust panic in some contexts, for example when exception is thrown
       from atomspace query unification procedure. It is highly recommended to call get_object method
       inside try-except block to catch TypeError.
    """
    # TODO: Here code assumes CGrounded object is always Python object.
    # This is not true in general case. To make code universal we need to
    # keep kind of the original runtime in CGrounded structure.
    if hp.atom_is_cgrounded(self.catom):
        return hp.atom_get_object(self.catom)
    else:
        return _priv_gnd_get_object(self)

def iterate(self):
    """Performs a depth-first exhaustive iteration of an Atom and all its children recursively."""
    res = hp.atom_iterate(self.catom)
    result = []
    for r in res:
        result.append(Atom._from_catom(r))
    return result

def match_atom(self, b):
    """Matches one Atom with another, establishing bindings between them."""
    return BindingsSet(hp.atom_match_atom(self.catom, b.catom))

def __repr__(self):
    """Returns the object's ID if present, or a string representation of
    its content if not."""
    # Overwrite Python default representation of a string to use
    # double quotes instead of single quotes.
    if isinstance(self.content, str):
        newstr = repr(self.content)[1:-1].translate(str.maketrans({'"' : r'\"'}))
        return f'"{newstr}"'

    # Use default representation for everything else
    return repr(self.content) if self.id is None else self.id

def copy(self):
    """
    Returns a copy of this GroundedObject instance.

    Note: Currently, this method returns the original instance.
    """
    return self

def __eq__(self, other):
    """Compares the equality of this ValueObject with another based on their content."""
    # TODO: We need to hook this up the the Value-Bridging mechanism when it's designed and built
    # https://github.com/trueagi-io/hyperon-experimental/issues/351

    # TODO: ?typecheck for the contents
    return isinstance(other, ValueObject) and self.content == other.content

def __repr__(self):
    """Returns the object's ID if present, or a string representation of
    its content if not."""
    # Overwrite Python default representation of a string to use
    # double quotes instead of single quotes.
    if isinstance(self.content, str):
        newstr = repr(self.content)[1:-1].translate(str.maketrans({'"' : r'\"'}))
        return f'"{newstr}"'

    # Use default representation for everything else
    return repr(self.content) if self.id is None else self.id

def copy(self):
    """
    Returns a copy of this GroundedObject instance.

    Note: Currently, this method returns the original instance.
    """
    return self

def match_(self, atom):
    """
    A stub method for matching the object with an Atom.

    This method is intended to be overridden by subclasses to provide specific
    matching behavior with an Atom.

    Parameters:
        atom (Atom): An Atom object to match against.

    Raises:
        RuntimeError: Raised when this method is called without being overridden in a subclass.
    """
    raise RuntimeError("MatchableObject::match_() is not implemented")

def serialize(self, serializer):
    """
    Serialize standard Python values. This implementation is used to
    pass Python values into the foreign runtime.
    """
    if isinstance(self.content, bool):
        return serializer.serialize_bool(self.content)
    elif isinstance(self.content, int):
        return serializer.serialize_int(self.content)
    elif isinstance(self.content, float):
        return serializer.serialize_float(self.content)
    elif isinstance(self.content, str):
        return serializer.serialize_str(self.content)
    else:
        return SerialResult.NOT_SUPPORTED

def __eq__(self, other):
    """
    Compares the equality of this OperationObject with another based on their names.

    Parameters:
        other (OperationObject): Another OperationObject instance to compare.

    Returns:
        True if both OperationObjects have the same name; False otherwise.
    """
    return isinstance(other, OperationObject) and self.name == other.name

def __repr__(self):
    """Returns the object's ID if present, or a string representation of
    its content if not."""
    # Overwrite Python default representation of a string to use
    # double quotes instead of single quotes.
    if isinstance(self.content, str):
        newstr = repr(self.content)[1:-1].translate(str.maketrans({'"' : r'\"'}))
        return f'"{newstr}"'

    # Use default representation for everything else
    return repr(self.content) if self.id is None else self.id

def copy(self):
    """
    Returns a copy of this GroundedObject instance.

    Note: Currently, this method returns the original instance.
    """
    return self

def execute(self, *atoms, res_typ=AtomType.UNDEFINED):
    """
    Executes the operation with the provided arguments.

    Parameters:
        *args: Arguments to pass to the operation function.
        res_typ (AtomType, optional): The expected result type. Defaults to AtomType.UNDEFINED.

    Returns:
        The result of the operation.

    Raises:
        NoReduceError: Raised when `unwrap=True` and a non-GroundedAtom argument is provided.
        RuntimeError: Raised when the result of the operation is not a list.

    Note:
        Depending on the `unwrap` attribute, this method will either unwrap GroundedAtoms
        before passing them to the operation or pass them as is.
    """
    # type-check?
    if self.unwrap:
        args, kwargs = unwrap_args(atoms)
        try:
            result = self.op(*args, **kwargs)
        except MettaError as e:
            return [E(S('Error'), *e.args)]
        if result is None:
            return [Atoms.UNIT]
        if callable(result):
            return [OperationAtom(repr(result), result, unwrap=True)]
        return [ValueAtom(result, res_typ)]
    else:
        result = self.op(*atoms)
        try:
            iter(result)
        except TypeError:
            raise RuntimeError("Grounded operation `" + self.name + "` should return list")
        return result

def __del__(self):
    """Frees an Atom and all associated resources."""
    hp.atom_free(self.catom)

def __eq__(self, other):
    """Checks if two atom objects represent the same conceptual Atom."""
    return (isinstance(other, Atom) and
            hp.atom_eq(self.catom, other.catom))

def __repr__(self):
    """Renders a human-readable text description of the Atom."""
    return hp.atom_to_str(self.catom)

def get_metatype(self):
    """Gets the metatype (kind) of the current Atom instance"""
    return hp.atom_get_metatype(self.catom)

def get_name(self):
    """Returns the name of the Atom."""
    return hp.atom_get_name(self.catom)

def iterate(self):
    """Performs a depth-first exhaustive iteration of an Atom and all its children recursively."""
    res = hp.atom_iterate(self.catom)
    result = []
    for r in res:
        result.append(Atom._from_catom(r))
    return result

def match_atom(self, b):
    """Matches one Atom with another, establishing bindings between them."""
    return BindingsSet(hp.atom_match_atom(self.catom, b.catom))

def __eq__(self, other):
    """Compares the equality of this ValueObject with another based on their content."""
    # TODO: We need to hook this up the the Value-Bridging mechanism when it's designed and built
    # https://github.com/trueagi-io/hyperon-experimental/issues/351

    # TODO: ?typecheck for the contents
    return isinstance(other, ValueObject) and self.content == other.content

def __repr__(self):
    """Returns the object's ID if present, or a string representation of
    its content if not."""
    # Overwrite Python default representation of a string to use
    # double quotes instead of single quotes.
    if isinstance(self.content, str):
        newstr = repr(self.content)[1:-1].translate(str.maketrans({'"' : r'\"'}))
        return f'"{newstr}"'

    # Use default representation for everything else
    return repr(self.content) if self.id is None else self.id

def copy(self):
    """
    Returns a copy of this GroundedObject instance.

    Note: Currently, this method returns the original instance.
    """
    return self

def serialize(self, serializer):
    """
    Serialize standard Python values. This implementation is used to
    pass Python values into the foreign runtime.
    """
    if isinstance(self.content, bool):
        return serializer.serialize_bool(self.content)
    elif isinstance(self.content, int):
        return serializer.serialize_int(self.content)
    elif isinstance(self.content, float):
        return serializer.serialize_float(self.content)
    elif isinstance(self.content, str):
        return serializer.serialize_str(self.content)
    else:
        return SerialResult.NOT_SUPPORTED

def __del__(self):
    """Frees an Atom and all associated resources."""
    hp.atom_free(self.catom)

def __eq__(self, other):
    """Checks if two atom objects represent the same conceptual Atom."""
    return (isinstance(other, Atom) and
            hp.atom_eq(self.catom, other.catom))

def __repr__(self):
    """Renders a human-readable text description of the Atom."""
    return hp.atom_to_str(self.catom)

def get_metatype(self):
    """Gets the metatype (kind) of the current Atom instance"""
    return hp.atom_get_metatype(self.catom)

def get_name(self):
    """Returns the name of the Atom."""
    return hp.atom_get_name(self.catom)