2.4.3 Summary of classes

The list below summarises the classes defined in the C++ interface.

PlTerm

Generic Prolog term that wraps term_t (for more details on term_t, see Interface Data Types). This is a "base class" whose constructor is protected; subclasses specify the actual contents. Additional methods allow checking the Prolog type, unification, comparison, conversion to native C++-data types, etc. See section 2.9.3.

The subclass constructors are as follows. If a constructor fails (e.g., out of memory), a PlException is thrown.

PlTerm_atom

Subclass of PlTerm with constructors for building a term that contains an atom.

PlTerm_var

Subclass of PlTerm with constructors for building a term that contains an uninstantiated variable. Typically this term is then unified with another object.

PlTerm_term_t

Subclass of PlTerm with constructors for building a term from a C term_t.

PlTerm_integer

Subclass of PlTerm with constructors for building a term that contains a Prolog integer from a long.^{10PL_put_integer() takes a long argument.}

PlTerm_int64

Subclass of PlTerm with constructors for building a term that contains a Prolog integer from a int64_t.

PlTerm_uint64

Subclass of PlTerm with constructors for building a term that contains a Prolog integer from a uint64_t.

PlTerm_size_t

Subclass of PlTerm with constructors for building a term that contains a Prolog integer from a size_t.

PlTerm_float

Subclass of PlTerm with constructors for building a term that contains a Prolog float.

PlTerm_pointer

Subclass of PlTerm with constructors for building a term that contains a raw pointer. This is mainly for backwards compatibility; new code should use blobs.

PlTerm_string

Subclass of PlTerm with constructors for building a term that contains a Prolog string object.

PlTerm_list_codes

Subclass of PlTerm with constructors for building Prolog lists of character integer values.

PlTerm_chars

Subclass of PlTerm with constructors for building Prolog lists of one-character atoms (as atom_chars/2).

PlTerm_tail

SubClass of PlTerm for building and analysing Prolog lists.

Additional subclasses of PlTerm are:

PlCompound

Subclass of PlTerm with constructors for building compound terms. If there is a single string argument, then PL_chars_to_term() or PL_wchars_to_term() is used to parse the string and create the term. If the constructor has two arguments, the first is name of a functor and the second is a PlTermv with the arguments.

PlTermv

Vector of Prolog terms. See PL_new_term_refs(). The [] operator is overloaded to access elements in this vector. PlTermv is used to build complex terms and provide argument-lists to Prolog goals.

PlException

Subclass of std::exception, representing a Prolog exception. Provides methods for the Prolog communication and mapping to human-readable text representation.

PlTerm PlTypeError()

Creates a PlException object for representing a Prolog type_error exception.

PlTerm PlDomainError()

Creates a PlException object for representing a Prolog domain_error exception.

PlTerm PlExistenceError()

Creates a PlException object for representing a Prolog existence_error exception.

PlTerm PlPermissionError()

Creates a PlExceptionobject for representing a Prolog permission_error exception.

PlAtom

Allow for manipulating atoms (atom_t) in their internal Prolog representation for fast comparison. (For more details on atom_t, see Interface Data Types).

PlFunctor

A wrapper for functor_t, which maps to the internal representation of a name/arity pair.

PlPredicate

A wrapper for predicate_t, which maps to the internal representation of a Prolog predicate.

PlModule

A wrapper for module_t, which maps to the internal representation of a Prolog module.

PlQuery

Represents opening and enumerating the solutions to a Prolog query.

PlFail

Can be thrown to short-circuit processing and return failure to Prolog. Performance-critical code should use return false instead if failure is expected. An error can be signaled by calling Plx_raise_exception() or one of the PL_*_error() functions and then throwing PlFail; but it's better style to create the error throwing one of the subclasses of PlException e.g., throw PlTypeError("int", t).

PlException

If a call to Prolog results in an error, the C++ interface converts the error into a PlException object and throws it. If the enclosing code doesn't intercept the exception, the PlException object is turned back into a Prolog error.

PlExceptionFail

In some situations, a Prolog error cannot be turned into a PlException object, so a PlExceptionFail object is thrown. This is turned into failure by the PREDICATE() macro, resulting in normal Prolog error handling.

PlFrame

This utility-class can be used to discard unused term-references as well as to do‘data-backtracking’.

PlEngine

This class is used in embedded applications (applications where the main control is held in C++). It provides creation and destruction of the Prolog environment.

PlRegister

The encapsulation of PL_register_foreign() is defined to be able to use C++ global constructors for registering foreign predicates.

The required C++ function header and registration of a predicate is arranged through a macro called PREDICATE().