- Documentation
- Reference manual
- Packages
- A C++ interface to SWI-Prolog
- A C++ interface to SWI-Prolog (Version 1)
- A C++ interface to SWI-Prolog (Version 2)
- Summary of changes between Versions 1 and 2
- Sample code (version 2)
- Introduction (version 2)
- The life of a PREDICATE (version 2)
- Overview (version 2)
- Examples (version 2)
- Rationale for changes from version 1 (version 2)
- Porting from version 1 to version 2
- The class PlFail (version 2)
- Overview of accessing and changing values (version 2)
- The class PlRegister (version 2)
- The class PlQuery (version 2)
- The PREDICATE and PREDICATE_NONDET macros (version 2)
- Exceptions (version 2)
- Embedded applications (version 2)
- Considerations (version 2)
- Conclusions (version 2)
- A C++ interface to SWI-Prolog
2 A C++ interface to SWI-Prolog (Version 2)
2.1 Summary of changes between Versions 1 and 2
Version 1 is in SWI-cpp.h
; version 2 is in SWI-cpp2.h
,
SWI-cpp2.cpp
, SWI-cpp2-plx.h
, and SWI-cpp2-atommap.h
.
The overall structure of the API has been retained - that is, it is a
thin layer of lightweight classes on top of the interface provided by
SWI-Prolog.h
. Based on experience with the API, most of the
conversion operators and some of the comparison operators have been
removed or deprecated, and replaced by “getter” methods; the
overloaded constructors have been replaced by subclasses for the various
types. Some changes were also made to ensure that the
operator for []
PlTerm
and PlTermv
doesn't cause unexpected implicit conversions.2If
there is an implicit conversion operator from PlTerm
to term_t
and also to char*
, then the
operator is ambiguous if []
f
is overloaded to accept a term_t
or char*
in the code PlTerm t=...; f(t[0])
.
Prolog errors are now converted to C++ exceptions (which contain the
exception term rather being a subclass of PlTerm
as in
version 1), where they can be caught and thrown using the usual C++
mechanisms; and the subclasses that create exceptions have been changed
to functions. In addition, an exception type PlFail
has
been added, together with PlCheckFail
, to allow more
compact code by “short circuit” return to Prolog on failure.
A convenience class for creating blobs has been added, so that an existing structure can be converted to a blob with only a few lines of code.
More specifically:
SWI-cpp2.cpp
has been added, containing the implementation of some functions. This is included by default fromSWI-cpp2.h
or can be compiled separately.- The constructor PlTerm() is restricted to a few unambiguous cases - instead, you should use the appropriate subclass constructors that specify the type (PlTerm_var(), PlTerm_atom(), etc.).
- Wrapper functions have been provided for almost all the PL_*()
functions in
SWI-Prolog.h
, and have the same names with the “PL” replaced by “Plx” .3 “Pl” is used throughout theSWI-cpp2.h
interface, and the “x” is for “eXtended with eXception handling.’ Where appropriate, these check return codes and throw a C++ exception (created from the Prolog error). See section 2.5.4. Many of these wrapper functions are also methods in thePlAtom
andPlTerm
classes, with the arguments changed fromatom_t
andterm_t
toPlAtom
andPlTerm
and in some caseschar*
andwchar_t*
changed tostd::string
andstd::wstring
. These wrappers are available if you includeSWI-cpp2.h
(they are in a separateSWI-cpp2-plx.h
file for ease of maintenance). - Instead of returning
false
from a foreign predicate to indicate failure, you can throw PlFail(). The convenience function PlCheckFail(rc) can be used to throw PlFail() iffalse
is returned from a function inSWI-Prolog.h
. If the wrapper functions or class methods are used, Prolog errors result in a C++PlException
exception.4If a “Plx_” wrapper is used to call aSWI-Prolog.h
function, a Prolog error will have already resulted in throwingPlException
; PlCheckFail(rc) is used to additionally throwPlFail
, similar to returningfalse
from the top-level of a foreign predicate - Prolog will check for an error and call throw/1 if appropriate. - The
PlException
class is now a subclass ofstd::exception
and encapsulates a Prolog error. Prolog errors are converted intothrow PlException(...)
. If the user code does not catch thePlException
, the PREDICATE() macro converts the error to a Prolog error upon return to the Prolog caller. - The C++ constructors, functions, and methods use the wrapper functions to throw a C++ exception on error (this C++ exception is converted to a Prolog exception when control returns to Prolog).
- The “cast” operators (e.g.,
(char*)t
,(int64_t)t
,static_cast<char*>(t)
) have been deprecated, replaced by “getters” (e.g.,t.as_string()
,t.as_int64_t()
). - The overloaded assignment operator for unification is deprecated, replaced by PlTerm::unify_term(), PlTerm::unify_atom(), etc., and the helper PlCheckFail().
- Many of the equality and inequality operators are deprecated;
replaced by the PlTerm::as_string()
or PlTerm::get_nchars()
methods and the associated
std::string
, comparison operators. The PlTerm::as_string() method allows specifying the encoding to use whereas the
and similar operators do not allow for this.==
- Methods that return
char*
have been replaced by methods that returnstd::string
to ensure that lifetime issues don't cause subtle bugs.5If you want to return achar*
from a function, you should not doreturn t.as_string().c_str()
because that will return a pointer to local or stack memory. Instead, you should change your interface to return astd::string
and apply thec_str()
method to it. These lifetime errors can sometimes be caught by specifying the Gnu C++ or Clang options-Wreturn-stack-address
or-Wreturn-local-addr
- as of 2023-04, Clang seems to do a better analysis. - Most constructors, methods, and functions that accept
char*
orwchar_t*
arguments also acceptstd::string
orstd::wstring
arguments. Where possible, encoding information can also be specified. - Type-checking methods have been added: PlTerm::type(), PlTerm::is_variable(), PlTerm::is_atom(), etc.
PlString
has been renamed toPlTerm_string
to make it clear that it's a term that contains a Prolog string.- More
PL_...(term_t, ...)
methods have been added toPlTerm
, andPL_...(atom_t, ...)
methods have been added toPlAtom
. Where appropriate, the arguments usePlTerm
,PlAtom
, etc. instead ofterm_t
,atom_t
, etc. - Most functions/methods that return an
int
for true/false now return a C++bool
. - The wrapped C types fields (
term_t
,atom_t
, etc.) have been renamed fromhandle
,ref
, etc. toC_
.6This is done by subclassing fromWrapped<term_t>
,Wrapped<atom_t>
, etc., which define the fieldC_
, standard constructors, the methods is_null(), not_null(), reset(), reset(v), reset_wrapped(v), plus the constantnull
. This value can be accessed by the unwrap() and unwrap_as_ptr() methods. There is also a “friend” function PlUnwrapAsPtr(). - A convenience function
PlControl::context_unique_ptr<ContextType>()
has been added, to simplify dynamic memory allocation in non-deterministic predicates. - A convenience function PlRewindOnFail() has been added, to simplify non-deterministic code that does backtracking by checking unification results.
PlStringBuffers
provides a simpler interface for allocating strings on the stack than PL_STRINGS_MARK() and PL_STRINGS_RELEASE(). However, this is mostly not needed because most functions now usestd::string
: see section 2.5.8.1.PlStream
provides a simpler interface for streams than PL_get_stream(), PL_acquire_stream(), and PL_release_stream(). See section 2.5.8.2.- Wrapper classes for
record_t
have been added. ThePlRecordExternalCopy
class contains the opaque handle, as a convenience. - Wrapper class for
control_t
has been added and the PREDICATE_NONDET() has been modified to use it.
More details on the rationale and how to port from version 1 to version 1 are given in section 2.7 and section 2.8.
2.2 Sample code (version 2)
The file test_cpp.cpp contains examples of Prolog predicates written in C++. This file is used for testing (called from test_cpp.pl). Notable examples:
- add_num/3 -
same as
A3 is A1+A2
, converting the sum to an integer if possible. - name_arity/3 - C++ implementation of functor/3.
- average/3 - computes the average of all the solutions to Goal
- can_unify/2 - tests whether the two arguments can unify with each other, without instantiating anything (similar to unifiable/3).
- eq1/1, eq2/2, eq3/2 - three different ways of implementing =/2.
- write_list/1 - outputs the elements of a list, each on a new line.
- cappend/3 - appends two lists (requires that the two lists are instantiated).
- square_roots/2
- same as
bagof(Sqrt, X^(between(0,4,X), Sqrt is sqrt(X)), A2)
. - range_cpp/3 - on backtracking, generates all integers starting at A1 and less than A2 (that is, one less than between/3).
- int_info/2 - on backtracking generates all the integral types with their minimum and maximum values.
The file
likes.cpp
contains a simple program that calls the Prolog predicate likes/2
and
happy/1 (these
predicates are defined in
likes.pl.
The usage and how to compile the code are in comments in likes.cpp
2.3 Introduction (version 2)
C++ provides a number of features that make it possible to define a more natural and concise interface to dynamically typed languages than plain C does. Using type-conversion (casting) and overloading, native data-types can be easily translated into appropriate Prolog types, automatic destructors can be used to deal with most of the cleanup required and C++ exception handling can be used to map Prolog exceptions and interface conversion errors to C++ exceptions, which are automatically mapped to Prolog exceptions as control is turned back to Prolog.
However, there are subtle differences between Prolog and C++ that can lead to confusion; in particular, the lifetime of terms do not fit well with the C++ notion of constructor/destructor. It might be possible to handle this with “smart pointers” , but that would lead to other complications, so the decision was made to provide a thin layer between the underlying C functions and the C++ classes/methods/functions.
More information on the SWI-Prolog native types is given in Interface Data Types.
It would be tempting to use C++ implicit conversion operators and
method overloading to automatically convert between C++ types such as
std::string
and int64_t
and Prolog foreign
language interface types such as term_t
and atom_t
.
However, types such as term_t
are unsigned integers, so
many of the automatic type conversions can inadvertently do something
other than what the programmer intended, resulting in subtle bugs that
are difficult to find. Therefore Version 2 of this interface reduces the
amount of automatic conversion and introduces some redundancy, to avoid
these subtle bugs, by using “getter” methods rather than
conversion operators, and using naming conventions for explicitly
specifying constructors.
2.3.1 Acknowledgements (version 2)
I would like to thank Anjo Anjewierden for comments on the definition, implementation and documentation of this package. Peter Ludemann modified the interface to remove some pitfalls, and also added some convenience functions (see section 2.1).
2.4 The life of a PREDICATE (version 2)
A foreign predicate is defined using the PREDICATE()
macro, plus a few variations on this, such as
PREDICATE_NONDET(), NAMED_PREDICATE(),
and
NAMED_PREDICATE_NONDET().
These define an internal name for the function, register it with the
SWI-Prolog runtime (where it will be picked up by the use_foreign_library/1
directive), and define the names A1
, A2
, etc.
for the arguments.7You can define
your own names for the arguments, for example: auto dir=A1, db=A2;
or PlTerm options(A3);
. If a non-deterministic
predicate is being defined, an additional parameter handle
is defined (of type
PlControl
).
The foreign predicate returns a value:
true
- successfalse
- failure or an error (see section 2.14 and Prolog exceptions in foreign code).- “retry” - for non-deterministic predicates, gives a “context” for backtracking / redoing the call for the next solution.
The C++ API provides Plx_*() functions that are the same as the PL_*() functions except that where appropriate they check for exceptions and thrown a PlException().
Addditionally, the function PlCheckFail()
can be used to check for failure and throw a PlFail
exception that is handled before returning to Prolog with failure.
The following three snippets do essentially the same thing (for
implementing the equivalent of =/2); however the first version (with
PlTerm::unify_term())
and second version (with Plx_unify()) throw a C++ PlExceptionFail
exception if there's an error and otherwise return true
or false
;
the third version (with PlCheckFail())
throws a PlFail
exception for failure (and PlExceptionFail
for an error) and otherwise returns true
- the PREDICATE()
wrapper handles all of these appropriately and reports the same result
back to Prolog; but you might wish to distinguish the two situations in
more complex code.
PREDICATE(eq, 2) { return A1.unify_term(A2); }
PREDICATE(eq, 2) { return Plx_unify(A1.unwrap(), A2.unwrap())); }
PREDICATE(eq, 2) { PlCheckFail(A1.unify_term(A2)); return true; }
2.5 Overview (version 2)
One useful area for exploiting C++ features is type-conversion.
Prolog variables are dynamically typed and all information is passed
around using the C-interface type term_t
. In C++,
term_t
is embedded in the lightweight class
PlTerm
. Other lightweight classes, such as PlAtom
for
atom_t
are also provided. Constructors and operator
definitions provide flexible operations and integration with important
C-types (char*
, wchar_t*
, long
and
double
), plus the C++-types (std::string
,
std::wstring
). (char*
and wchar_t*
are deprecated in the C++ API; std::string
and
std::wstring
are safer and should be used instead.)
Another useful area is in handling errors and cleanup. Prolog errors can be modeled using C++ exceptions; and C++'s destructors can be used to clean up error situations, to prevent memory and other resource leaks.
2.5.1 Design philosophy of the classes
See also section 2.5.5 for more on naming conventions and standard methods.
The general philosophy for C++ classes is that a “half-created” object should not be possible - that is, the constructor should either succeed with a completely usable object or it should throw an exception. This API tries to follow that philosophy, but there are some important exceptions and caveats. (For more on how the C++ and Prolog exceptions interrelate, see section 2.14.)
Most of the PL_*() functions have corresponding wrapper methods. For example, PlTerm::get_atom() calls Plx_get_atom(), which calls PL_get_atom(). If the PL_get_atom() has an error, it creates a Prolog error; the Plx_get_atom() wrapper checks for this and converts the error to a C++ exception, which is thrown; upon return to Prolog, the exception is turned back into a Prolog error. Therfore, code typically does not need to check for errors.
Some functions return false
to indicate either failure
or an error, for example PlTerm::unify_term();
for such methods, a check is made for an error and an exception is
thrown, so the return value of
false
only means failure. (The whole thing can be wrapped
in
PlCheckFail(), in which case a PlFail
exception is thrown, which is converted to failure in Prolog.) For more
on this, see
section 2.5.4, and for handling
failure, see
section 2.12.1.
For PL_*() functions that take or return char*
or
wchar_t*
values, there are also wrapper functions and
methods that use std::string
or std::wstring
.
Because these copy the values, there is usually no need to enclose the
calls with
PlStringBuffers
(which wraps PL_STRING_MARK() and
PL_STRING_RELEASE()). See also the rationale for string:
section 2.7.2.
Many of the classes (PlAtom
, PlTerm
, etc.)
are thin wrappers around the C interface's types (atom_t
,
term_t
, etc.). As such, they inherit the concept of “null” from
these types (which is abstracted as PlAtom::null
,
PlTerm::null
, etc., which typically is equivalent to
0
). Normally, you shouldn't need to check whether the
object is “fully created” , for the rare situations where a
check is needed, the methods is_null()
and not_null() are provided.
Most of the classes have constructors that create a “complete” object. For example,
PlAtom foo("foo");
will ensure that the object foo
is useable and will
throw an exception if the atom can't be created. However, if you choose
to create a PlAtom
object from an atom_t
value, no checking is done (similarly, no checking is done if you create
a PlTerm
object from a term_t
value).
In many situations, you will be using a term; for these, there are special constructors. For example:
PlTerm_atom foo("foo"); // Same as PlTerm(PlAtom("foo")) PlTerm_string str("a string");
To help avoid programming errors, some of the classes do not have a
default “empty” constructor. For example, if you with to
create a
PlAtom
that is uninitialized, you must explicitly use
PlAtom(PlAtom::null)
.
This make some code a bit more cumbersome because you can't omit the
default constructors in struct initalizers.
Many of the classes have an as_string()
method8This might be changed in
future to to_string(), to be consistent with std::to_string()
,
which is useful for debugging.
The method names such as
as_int32_t() were chosen itnstead of to_int32_t() because
they imply that the representation is already an int32_t
,
and not that the value is converted to a int32_t
. That is,
if the value is a float, int32_t
will fail with an error
rather than (for example) truncating the floating point value to fit
into a 32-bit integer.
Many of the classes wrap long-lived items, such as atoms, functors,
predicates, or modules. For these, it's often a good idea to define them
as static
variables that get created at load time, so that
a lookup for each use isn't needed (atoms are unique, so
PlAtom("foo")
requires
a lookup for an atom foo
and creates one if it isn't
found).
C code sometimes creates objects “lazily” on first use:
void my_function(...) { static atom_t ATOM_foo = 0; ... if ( ! foo ) foo = PL_new_atom("foo"); ... }
For C++, this can be done in a simpler way, because C++ will call a
local “static
” constructor on first use.
void my_function(...) { static PlAtom ATOM_foo("foo"); }
The class PlTerm
(which wraps term_t
) is
the most used. Although a PlTerm
object can be created from
a term_t
value, it is intended to be used with a
constructor that gives it an initial value. The default constructor
calls PL_new_term_ref() and throws an exception if this fails.
The various constructors are described in
section 2.5.6. Note that the
default constructor is not public; to create a “variable” term,
you should use the subclass constructor PlTerm_var().
2.5.2 Summary of files
The following files are provided:
SWI-cpp2.h
- Include this file to get the C++ API. It automatically includesSWI-cpp2-plx.h
andSWI-cpp2.cpp
, unless the macro_SWI_CPP2_CPP_SEPARATE
is defined, in which case you must compileSWI-cpp2.cpp
separately.SWI-cpp2.cpp
- Contains the implementations of some methods and functions. If you wish to compile this separately, you must define the macro_SWI_CPP2_CPP_SEPARATE
before your include forSWI-cpp2.h
.SWI-cpp2-plx.h
- Contains the wrapper functions for the most of the functions inSWI-Prolog.h
. This file is not intended to be used by itself, but is#include
d bySWI-cpp2.h
.SWI-cpp2-atommap.h
- Contains a utility class for mapping atom-to-atom or atom-to-term, which is useful for naming long-lived blobs instead of having to pass them around as arguments.test_cpp.cpp
,test_cpp.pl
- Contains various tests, including some longer sequences of code that can help in understanding how the C++ API is intended to be used. In addition, there aretest_ffi.cpp
,test_ffi.pl
, which often have the same tests written in C, without the C++ API.
2.5.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 onterm_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.10.1.
For more details about
PlTerm
, see section 2.5.6 - 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 aPlTermv
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. - PlAtom
- Wraps
atom_t
in their internal Prolog representation for fast comparison. (For more details onatom_t
, see Interface Data Types). For more details ofPlAtom
, see section 2.10.12.4. - 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.
- 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, thePlException
object is turned back into a Prolog error when control returns to Prolog from the PREDICATE() macros. This is a subclass ofPlExceptionBase
, which is a subclass ofstd::exception
. - 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
- Encapsulates PL_register_foreign() to allow using C++ global constructors for registering foreign predicates.
- 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 throwingPlFail
; but it's better style to create the error throwing one of the subclasses ofPlException
e.g.,throw PlTypeError("int", t)
. Subclass ofPlExceptionFailBase
. - PlExceptionFail
- In some situations, a Prolog error cannot be turned into a
PlException
object, so aPlExceptionFail
object is thrown. This is turned into failure by the PREDICATE() macro, resulting in normal Prolog error handling. Subclass ofPlExceptionFailBase
. - PlExceptionBase
- A “do nothing” subclass of
std::exception
, to allow catchingPlException
,PlExceptionFail
orPlFail
in a single “catch” clause. - PlExceptionFailBase
- A “do nothing” subclass of
PlExceptionBase
, to allow catchingPlExceptionFail
orPlFail
in a single “catch” clause, excludingPlException
.
2.5.4 Wrapper functions
The various PL_*() functions in SWI-Prolog.h
have
corresponding Plx_*() functions, defined in SWI-cpp2-plx.h
,
which is always included by SWI-cpp2.h
. There are three
kinds of wrappers, with the appropriate one being chosen according to
the semantics of the wrapped function:
- “as-is” - the PL_*() function cannot cause an error. If
it has a return value, the caller will want to use it.
- “exception wrapper” - the PL_*() function can return
false
, indicating an error. The Plx_*() function checks for this and throws aPlException
object containing the error. The wrapper usestemplate<typename C_t> C_t PlEx(C_t rc)
, whereC_t
is the return type of the PL_*() function. - “success, failure, or error” - the PL_*() function can
return
true
if it succeeds andfalse
if it fails or has a runtime error. If it fails, the wrapper checks for a Prolog error and throws aPlException
object containing the error. The wrapper usestemplate<typename C_t> C_t PlWrap(C_t rc)
, whereC_t
is the return type of the PL_*() function.
A few PL_*() functions do not have a corresponding Plx*() function
because they do not fit into one of these categories. For example,
PL_next_solution() has multiple return values (PL_S_EXCEPTION
,
PL_S_LAST
, etc.) if the query was opened with the
PL_Q_EXT_STATUS
flag.
Most of the PL_*() functions whose first argument is of type
term_t
, atom_t
, etc. have corresponding
methods in classes PlTerm
, PlAtom
, etc.
Important: You should use the Plx_*() wrappers only in the context of a PREDICATE() call, which will handle any C++ exceptions. Some blob callbacks can also handle an exception (see section 2.5.7). Everywhere else, the result of calling a Plx_*() function is unpredicatable - probably a crash.
2.5.5 Naming conventions, utility functions and methods (version 2)
See also the discussion on design philosophy in section 2.5.1.
The classes all have names starting with “Pl” , using CamelCase; this contrasts with the C functions that start with “PL_” and use underscores.
The wrapper classes (PlFunctor
, PlAtom
,
PlTerm
), etc. all contain a field C_
that
contains the wrapped value (functor_t
, atom_t
, term_t
respectively). If this wrapped value is needed, it should be accessed
using the unwrap() or unwrap_ptr() methods.
In some cases, it's natural to use a pointer to a wrapper class. For
those, the function PlUnwrapAsPtr() returns nullptr
if the pointer is null; otherwise it returns the wrapped value (which
itself might be some kind of “null” ).
The wrapper classes, which subclass WrappedC<...>
,
all define the following methods and constants:
- Default constructor (sets the wrapped value to
null
). Some classes do not have a default constructor because it can lead to subtle bugs - instead, they either have a different way of creating the object or can use the‘null` value for the class. - Constructor that takes the wrapped value (e.g., for
PlAtom
, the constructor takes anatom_t
value). C_
- the wrapped value. This can be used directly when calling C functions, for example, ift
anda
are of typePlTerm
andPlAtom
:Plcheck_PL(PL_put_atom(t.unwrap(),a.unwrap()))
.null
- the null value (typically0
, but code should not rely on this).is_null()
,not_null()
- test for the wrapped value beingnull
.reset()
- set the wrapped value tonull
reset(new_value)
- set the wrapped value from the wrapped type (e.g., PlTerm::reset(term_t new_value))reset_wrapped(new_value)
- set the wrapped value from the same type (e.g., PlTerm::reset_wrapped(PlTerm new_value))- The
bool
operator is disabled - you should use not_null() instead.9The reason: abool
conversion causes ambiguity withPlAtom(PlTterm)
andPlAtom(atom_t)
.
The method unwrap() can be used to access the C_
field, and can be used wherever a atom_t
or term_t
is used. For example, the PL_scan_options() example code can be
written as follows. Note the use of &callback.unwrap()
to pass a pointer to the wrapped term_t
value.
PREDICATE(mypred, 2) { auto options = A2; int quoted = false; size_t length = 10; PlTerm_var callback; PlCheckFail(PL_scan_options(options, 0, "mypred_options", mypred_options, "ed, &length, &callback.unwrap())); callback.record(); // Needed if callback is put in a blob that Prolog doesn't know about. // If it were an atom (OPT_ATOM): register_ref(). <implement mypred> }
For functions in SWI-Prolog.h
that don't have a C++
equivalent in SWI-cpp2.h
, PlCheckFail()
is a convenience function that checks the return code and throws a PlFail
exception on failure or PlException
if there was an
exception. The enclosing PREDICATE()
code catches PlFail
exceptions and converts them to the foreign_t
return code for failure. If the failure from the C function was due to
an exception (e.g., unification failed because of an out-of-memory
condition), the foreign function caller will detect that situation and
convert the failure to an exception.
The “getter” methods for PlTerm
all throw an
exception if the term isn't of the expected Prolog type. The “getter” methods
typically start with “as” , e.g. PlTerm::as_string().
There are also other “getter” methods, such as PlTerm::get_float_ex()
that wrap PL_*() functions.
“getters” for integers have an additional problem, in
that C++ doesn't define the sizes of int
, long
,
or
size_t
. It seems to be impossible to make an overloaded
method that works for all the various combinations of integer types on
all compilers, so there are specific methods for int64_t
,
uint64_t
, size_t
.
In some cases,it is possible to overload methods; for example, this
allows the following code without knowing the exact definition of
size_t
:
PREDICATE(p, 1) { size_t sz; A1.integer(&sz); ... }
It is strongly recommended that you enable conversion checking.
For example, with GNU C++, use these options (possibly with -Werror
):
-Wconversion -Warith-conversion -Wsign-conversion
-Wfloat-conversion
.
There is an additional problem with characters - C promotes them to int
but C++ doesn't. In general, this shouldn't cause any problems, but care
must be used with the various getters for integers.
2.5.6 PlTerm class (version 2)
As we have seen from the examples, the PlTerm
class
plays a central role in conversion and operating on Prolog data. This
section provides complete documentation of this class.
There are a number of subclasses that exist only to provide a safe way of constructing at term.
Most of the PlTerm
constructors are defined as
subclasses of
PlTerm
, with a name that reflects the Prolog type of what
is being created (e.g., PlTerm_atom
creates a term from an
atom;
PlTerm_string
creates a term from a Prolog string). This is
done to ensure that the there is no ambiguity in the constructors - for
example, there is no way to distinguish between term_t
,
atom_t
, and ordinary integers, so there are constructors
PlTerm(), PlTerm_atom(), and PlTerm_integer. All of the
constructors are “explicit” because implicit creation of PlTerm
objects can lead to subtle and difficult to debug errors.
If a constructor fails (e.g., out of memory), a PlException
is thrown. The class and subclass constructors are as follows.
- PlTerm :: PlTerm(PlAtom a)
- Creates a term reference containing an atom, using PL_put_atom(). It is the same as PlTerm_atom().
- PlTerm :: PlTerm(term_t t)
- Creates a term reference from a C term (by wrapping it). As this is a lightweight class, this is a no-op in the generated code.
- PlTerm :: PlTerm(PlRecord r)
- Creates a term reference from a record, using PL_recorded().
- PlTerm_atom :: PlTerm_atom(atom_t a)
- Creates a term reference containing an atom.
- PlTerm_atom :: PlTerm_atom(PlAtom a)
- Creates a term reference containing an atom.
- PlTerm_atom :: PlTerm_atom(const char *text)
- Creates a term reference containing an atom, after creating the atom from the text.
- PlTerm_atom :: PlTerm_atom(const wchar_t *text)
- Creates a term reference containing an atom, after creating the atom from the text.
- PlTerm_atom :: PlTerm_atom(const std::string& text)
- Creates a term reference containing an atom, after creating the atom from the text.
- PlTerm_atom :: PlTerm_atom(const std::wstring& text)
- Creates a term reference containing an atom, after creating the atom from the text.
- PlTerm_var :: PlTerm_var()
- Creates a term reference for an uninstantiated variable. Typically this term is then unified with another object.
- PlTerm_term_t :: PlTerm_term_t()
- Creates a term reference from a C
term_t
. This is a lightweight class, so no code is generated. - PlTerm_integer :: PlTerm_integer()
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog integer from along
.10PL_put_integer() takes along
argument. - PlTerm_int64 :: PlTerm_int64()
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog integer from aint64_t
. - PlTerm_uint64 :: PlTerm_uint64()
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog integer from auint64_t
. - PlTerm_size_t :: PlTerm_size_t()
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog integer from asize_t
. - PlTerm_float :: PlTerm_float()
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog float. - PlTerm_pointer :: 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. A pointer is represented in Prolog as a mangled integer. The mangling is designed to make most pointers fit into a tagged-integer. Any valid pointer can be represented. This mechanism can be used to represent pointers to C++ objects in Prolog. Please note that‘MyClass’should define conversion to and fromvoid *
.PREDICATE(make_my_object, 1) { auto myobj = new MyClass(); return A1.unify_pointer(myobj); } PREDICATE(my_object_contents, 2) { auto myobj = static_cast<MyClass*>(A1.pointer()); return A2.unify_string(myobj->contents); } PREDICATE(free_my_object, 1) { auto myobj = static_cast<MyClass*>(A1.pointer()); delete myobj; return true; }
- PlTerm_string :: PlTerm_string()
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog string object. For constructing a term from the text form, seePlCompound
. - PlTerm_list_codes :: PlTerm_list_codes()
- Subclass of
PlTerm
with constructors for building Prolog lists of character integer values. - PlTerm_chars :: PlTerm_chars()
- Subclass of
PlTerm
with constructors for building Prolog lists of one-character atoms (as atom_chars/2). - PlTerm_tail :: PlTerm_tail()
- SubClass of
PlTerm
for building and analysing Prolog lists.
The methods are:
- bool PlTerm::get_atom(PlAtom* a)
- Wrapper of PL_get_atom(), throwing an exception on Prolog error.
- bool PlTerm::get_bool(int* value)
- Wrapper of PL_get_bool(), throwing an exception on Prolog error.
- chars PlTerm::get_chars(char**s, unsigned int flags)
- Wrapper of PL_get_chars(), throwing an exception on Prolog error.
- chars PlTerm::get_list_chars(char**s, unsigned int flags)
- Wrapper of PL_get_list_chars(), throwing an exception on Prolog error.
- bool PlTerm::get_list_chars(char **s, unsigned int flags)
- Wrappper of PL_get_list_chars(), throwing an exception on Prolog error.
- bool PlTerm::get_atom_nchars(size_t *len, char **a)
- Wrappper of PL_get_atom_nchars(), throwing an exception on Prolog error.
- bool PlTerm::get_list_nchars(size_t *len, char **s, unsigned int flags)
- Wrappper of PL_get_list_nchars(), throwing an exception on Prolog error.
- bool PlTerm::get_nchars(size_t *len, char **s, unsigned int flags)
- Wrappper of PL_get_nchars(), throwing an exception on Prolog
error. Deprecated: see PlTerm::get_nchars(flags)
that returns a
std::string
. If you use this, be sure to wrap it withPlStringBuffers
, and if you use theBUF_MALLOC
flag, you can usestd::unique_ptr<char, decltype(&PL_free)>
to manage the pointer. - bool PlTerm::get_wchars(size_t *length, pl_wchar_t **s, unsigned flags)
- Wrappper of PL_get_wchars(), throwing an exception on Prolog
error. Deprecated: see PlTerm::getwchars(flags) that returns a
std::wstring
. If you use this, be sure to wrap it withPlStringBuffers
, and if you use theBUF_MALLOC
flag, you can usestd::unique_ptr<char, decltype(&PL_close)>
to manage the pointer. - bool PlTerm::get_integer(int *i)
- Wrappper of PL_get_integer(), throwing an exception on Prolog error.
- bool PlTerm::get_long(long *i)
- Wrappper of PL_get_long(), throwing an exception on Prolog error.
- bool PlTerm::get_intptr(intptr_t *i)
- Wrappper of PL_get_intptr(), throwing an exception on Prolog error.
- bool PlTerm::get_pointer(void **ptr)
- Wrappper of PL_get_pointer(), throwing an exception on Prolog error.
- bool PlTerm::get_float(double *f)
- Wrapper Plx_get_float(), throwing an exception on Prolog error.
- bool PlTerm::get_functor(PlFunctor *f)
- Wrappper of PL_get_functor(), throwing an exception on Prolog error.
- bool PlTerm::get_name_arity(PlAtom *name, size_t *arity)
- Wrappper of PL_get_name_arity(), throwing an exception on Prolog error.
- bool PlTerm::get_compound_name_arity(PlAtom *name, size_t *arity)
- Wrappper of PL_get_compound_name_arity(), throwing an exception on Prolog error.
- bool PlTerm::get_module(PlModule *module)
- Wrappper of PL_get_module(), throwing an exception on Prolog error.
- bool PlTerm::get_arg(size_t index, PlTerm a)
- Wrappper of PL_get_arg(index,), throwing an exception on Prolog error.
- bool PlTerm::get_dict_key(PlAtom key, PlTerm dict, PlTerm value)
- Wrappper of PL_get_dict_key(key.), throwing an exception on Prolog error.
- bool PlTerm::get_list(PlTerm h, PlTerm t)
- Wrappper of PL_get_list(), throwing an exception on Prolog error.
- bool PlTerm::get_head(PlTerm h)
- Wrappper of PL_get_head(), throwing an exception on Prolog error.
- bool PlTerm::get_tail(PlTerm t)
- Wrappper of PL_get_tail(), throwing an exception on Prolog error.
- bool PlTerm::get_nil()
- Wrappper of PL_get_nil(), throwing an exception on Prolog error.
- bool PlTerm::get_blob(void **blob, size_t *len, PL_blob_t **type)
- Wrappper of PL_get_blob(), throwing an exception on Prolog error.
- bool PlTerm::get_file_name(char **name, int flags)
- Wrappper of PL_get_file_name(), throwing an exception on Prolog error.
- bool PlTerm::get_file_nameW(wchar_t **name, int flags)
- Wrappper of PL_get_file_nameW(), throwing an exception on Prolog error.
- bool PlTerm::get_attr(term_t a)
- Wrappper of PL_get_attr(), throwing an exception on Prolog error.
- void PlTerm::get_atom_ex(PlAtom *a)
- Wrapper of PL_get_atom_ex(), throwing an exception on Prolog error.
- void PlTerm::get_integer_ex(int *i)
- Wrapper of PL_get_integer_ex(), throwing an exception on Prolog error.
- void PlTerm::get_long_ex(long *i)
- Wrapper of PL_get_long_ex(), throwing an exception on Prolog error.
- void PlTerm::get_int64_ex(int64_t *i)
- Wrapper of PL_get_int64_ex(), throwing an exception on Prolog error.
- void PlTerm::get_uint64_ex(uint64_t *i)
- Wrapper of PL_get_uint64_ex(), throwing an exception on Prolog error.
- void PlTerm::get_intptr_ex(intptr_t *i)
- Wrapper of PL_get_intptr_ex(), throwing an exception on Prolog error.
- void PlTerm::get_size_ex(size_t *i)
- Wrapper of PL_get_size_ex(), throwing an exception on Prolog error.
- void PlTerm::get_bool_ex(int *i)
- Wrapper of PL_get_bool_ex(), throwing an exception on Prolog error.
- void PlTerm::get_float_ex(double *f)
- Wrapper of PL_get_float_ex(), throwing an exception on Prolog error.
- void PlTerm::get_char_ex(int *p, int eof)
- Wrapper of PL_get_char_ex(), throwing an exception on Prolog error.
- void PlTerm::unify_bool_ex(int val)
- Wrapper of PL_unify_bool_ex(), throwing an exception on Prolog error.
- void PlTerm::get_pointer_ex(void **addrp)
- Wrapper of PL_get_pointer_ex(), throwing an exception on Prolog error.
- bool PlTerm::unify_list_ex(PlTerm h, PlTerm t)
- Wrappper of PL_unify_list_ex(), throwing an exception on Prolog error.
- void PlTerm::unify_nil_ex()
- Wrapper of PL_unify_nil_ex(), throwing an exception on Prolog error.
- bool PlTerm::get_list_ex(PlTerm h, PlTerm t)
- Wrappper of PL_get_list_ex(), throwing an exception on Prolog error.
- void PlTerm::get_nil_ex()
- Wrapper of PL_get_nil_ex(), throwing an exception on Prolog error.
- int PlTerm::type()
- Wrapper of PL_term_type(unwrap()), returning
PL_VARIABLE
,PL_ATOM
, etc, throwing an exception on Prolog error. bo - ol PlTerm::is_attvar()
- Wrappper of PL_is_attvar(), throwing an exception on Prolog error.
- bool PlTerm::is_variable()
- Wrappper of PL_is_variable(), throwing an exception on Prolog error.
- bool PlTerm::is_ground()
- Wrappper of PL_is_ground(), throwing an exception on Prolog error.
- bool PlTerm::is_atom()
- Wrappper of PL_is_atom(), throwing an exception on Prolog error.
- bool PlTerm::is_integer()
- Wrappper of PL_is_integer(), throwing an exception on Prolog error.
- bool PlTerm::is_string()
- Wrappper of PL_is_string(), throwing an exception on Prolog error.
- bool PlTerm::is_atom_or_string()
is_atom()
oris_string()
.- bool PlTerm::is_float()
- Wrappper of PL_is_float(), throwing an exception on Prolog error.
- bool PlTerm::is_rational()
- Wrappper of PL_is_rational(), throwing an exception on Prolog error.
- bool PlTerm::is_compound()
- Wrappper of PL_is_compound(), throwing an exception on Prolog error.
- bool PlTerm::is_callable()
- Wrappper of PL_is_callable(), throwing an exception on Prolog error.
- bool PlTerm::is_list()
- Wrappper of PL_is_list(), throwing an exception on Prolog error.
- bool PlTerm::is_dict()
- Wrappper of PL_is_dict(), throwing an exception on Prolog error.
- bool PlTerm::is_pair()
- Wrappper of PL_is_pair(), throwing an exception on Prolog error.
- bool PlTerm::is_atomic()
- Wrappper of PL_is_atomic(), throwing an exception on Prolog error.
- bool PlTerm::is_number()
- Wrappper of PL_is_number(), throwing an exception on Prolog error.
- bool PlTerm::is_acyclic()
- Wrappper of PL_is_acyclic(), throwing an exception on Prolog error.
- bool PlTerm::is_functor(PlFunctor f)
- Wrappper of PL_is_functor(), throwing an exception on Prolog error.
- bool PlTerm::is_blob(PL_blob_t **type)
- Wrappper of PL_is_blob(), throwing an exception on Prolog error.
- void PlTerm::must_be_attvar()
- Throw
PlTypeError
if PlTerm::is_attvar() fails. - void PlTerm::must_be_variable()
- Throw
PlTypeError
if PlTerm::is_variable() fails. - void PlTerm::must_be_ground()
- Throw
PlTypeError
if PlTerm::is_ground() fails. - void PlTerm::must_be_atom()
- Throw
PlTypeError
if PlTerm::is_atom() fails. - void PlTerm::must_be_integer()
- Throw
PlTypeError
if PlTerm::is_integer() fails. - void PlTerm::must_be_string()
- Throw
PlTypeError
if PlTerm::is_string() fails. - void PlTerm::must_be_atom_or_string()
- Throw
PlTypeError
if PlTerm::is_atom_or_string() fails. - void PlTerm::must_be_float()
- Throw
PlTypeError
if PlTerm::is_float() fails. - void PlTerm::must_be_rational()
- Throw
PlTypeError
if PlTerm::is_rational() fails. - void PlTerm::must_be_compound()
- Throw
PlTypeError
if PlTerm::is_compound() fails. - void PlTerm::must_be_callable()
- Throw
PlTypeError
if PlTerm::is_callable() fails. - void PlTerm::must_be_list()
- Throw
PlTypeError
if PlTerm::is_list() fails. - void PlTerm::must_be_dict()
- Throw
PlTypeError
if PlTerm::is_dict() fails. - void PlTerm::must_be_pair()
- Throw
PlTypeError
if PlTerm::is_pair() fails. - void PlTerm::must_be_atomic()
- Throw
PlTypeError
if PlTerm::is_atomic() fails. - void PlTerm::must_be_number()
- Throw
PlTypeError
if PlTerm::is_number() fails. - void PlTerm::must_be_acyclic()
- Throw
PlTypeError
if PlTerm::is_acyclic() fails. - void PlTerm::put_variable()
- Wrapper of PL_put_variable(), throwing an exception on Prolog error.
- void PlTerm::put_atom(PlAtom a)
- Wrapper of PL_put_atom(), throwing an exception on Prolog error.
- void PlTerm::put_bool(int val)
- Wrapper of PL_put_bool(), throwing an exception on Prolog error.
- void PlTerm::put_atom_chars(const char *chars)
- Wrapper of PL_put_atom_chars(), throwing an exception on Prolog error.
- void PlTerm::put_string_chars(const char *chars)
- Wrapper of PL_put_string_chars(), throwing an exception on Prolog error.
- void PlTerm::put_chars(int flags, size_t len, const char *chars)
- Wrapper of PL_put_chars(), throwing an exception on Prolog error.
- void PlTerm::put_list_chars(const char *chars)
- Wrapper of PL_put_list_chars(), throwing an exception on Prolog error.
- void PlTerm::put_list_codes(const char *chars)
- Wrapper of PL_put_list_codes(), throwing an exception on Prolog error.
- void PlTerm::put_atom_nchars(size_t l, const char *chars)
- Wrapper of PL_put_atom_nchars(), throwing an exception on Prolog error.
- void PlTerm::put_string_nchars(size_t len, const char *chars)
- Wrapper of PL_put_string_nchars(), throwing an exception on Prolog error.
- void PlTerm::put_list_nchars(size_t l, const char *chars)
- Wrapper of PL_put_list_nchars(), throwing an exception on Prolog error.
- void PlTerm::put_list_ncodes(size_t l, const char *chars)
- Wrapper of PL_put_list_ncodes(), throwing an exception on Prolog error.
- void PlTerm::put_integer(long i)
- Wrapper of PL_put_integer(), throwing an exception on Prolog error.
- void PlTerm::put_pointer(void *ptr)
- Wrapper of PL_put_pointer(), throwing an exception on Prolog error.
- void PlTerm::put_float(double f)
- Wrapper of PL_put_float(), throwing an exception on Prolog error.
- void PlTerm::put_functor(PlFunctor functor)
- Wrapper of PL_put_functor(), throwing an exception on Prolog error.
- void PlTerm::put_list()
- Wrapper of PL_put_list(), throwing an exception on Prolog error.
- void PlTerm::put_nil()
- Wrapper of PL_put_nil(), throwing an exception on Prolog error.
- void PlTerm::put_term(PlTerm t2)
- Wrapper of PL_put_term(), throwing an exception on Prolog error.
- void PlTerm::put_blob(void *blob, size_t len, PL_blob_t *type)
- Wrapper of PL_put_blob(), throwing an exception on Prolog error.
- PlRecord PlTerm::record()
- Returns a
PlRecord
constructed from the term. Same as PlRecord(*this). - void PlTerm::integer(bool *v)
- Wrapper of PL_cvt_i_bool().
- void PlTerm::integer(char *v)
- Wrapper of PL_cvt_i_char().
- void PlTerm::integer(int *v)
- Wrapper of PL_cvt_i_int().
- void PlTerm::integer(long *v)
- Wrapper of PL_cvt_i_long().
- void PlTerm::integer(long long *v)
- Wrapper of PL_cvt_i_llong().
- void PlTerm::integer(short *v)
- Wrapper of PL_cvt_i_short().
- void PlTerm::integer(signed char *v)
- Wrapper of PL_cvt_i_schar().
- void PlTerm::integer(unsigned char *v)
- Wrapper of PL_cvt_i_uchar().
- void PlTerm::integer(unsigned int *v)
- Wrapper of PL_cvt_i_uint().
- void PlTerm::integer(unsigned long *v)
- Wrapper of PL_cvt_i_ulong().
- void PlTerm::integer(unsigned long long *v)
- Wrapper of PL_cvt_i_ullong().
- void PlTerm::integer(unsigned short *v)
- Wrapper of PL_cvt_i_ushort().
- const std::string PlTerm::as_string(PlEncoding enc=ENC_OUTPUT)
- Calls PlTerm::get_nchars(CVT_ALL|CVT_WRITEQ|CVT_EXCEPTION). This method is provided mainly for debugging. The definition is subject to change in future - if you want precise control, use PlTerm::get_nchars().
- const std::wstring PlTerm::as_wstring()
- Calls PlTerm::get_wchars(CVT_ALL|CVT_WRITEQ|CVT_EXCEPTION). This method is provided mainly for debugging. The definition is subject to change in future - if you want precise control, use PlTerm::get_nchars().
- long PlTerm::as_long()
- Wrapper of PL_cvt_i_*().
- int32_t PlTerm::as_int32_t()
- Wrapper of PL_cvt_i_*().
- uint32_t PlTerm::as_uint32_t()
- Wrapper of PL_cvt_i_*().
- uint64_t PlTerm::as_uint64_t()
- Wrapper of PL_cvt_i_*().
- int64_t PlTerm::as_int64_t()
- Wrapper of PL_cvt_i_*().
- size_t PlTerm::as_size_t()
- Wrapper of PL_cvt_i_*().
- int PlTerm::as_int()
- Wrapper of PL_cvt_i_*().
- unsigned PlTerm::as_uint()
- Wrapper of PL_cvt_i_*().
- unsigned long PlTerm::as_ulong()
- Wrapper of PL_cvt_i_*().
- bool PlTerm::as_bool()
- Wrapper of PL_cvt_i_*().
- void PlTerm::as_nil()
- Wrapper of PL_get_nil_ex(), throwing an exception if the term isn't “nil” .
- double PlTerm::as_float()
- Wrapper of PL_get_float_ex(), throwing an exception if the term isn't a float.
- double PlTerm::as_double()
- Wrapper of PL_get_float_ex(), throwing an exception if the term isn't a float.
- void * PlTerm::as_pointer()
- (Deprecated: should use blob API). Wrapper of PL_get_pointer_ex(), throwing an exception if the term isn't a blob.
- const std::string PlTerm::get_nchars(unsigned int flags)
- Calls PL_get_nchars(..., flags) and converts the result to a
std::string
. The flagsBUF_MALLOC
,BUF_STACK
, andBUF_ALLOW_STACK
are ignored and replaced byBUF_DISCARDABLE
. - const std::wstring PlTerm::get_wchars(unsigned int flags)
- Calls PL_get_wchars(..., flags) and converts the result to a
std::wstring
. The flagsBUF_MALLOC
,BUF_STACK
, andBUF_ALLOW_STACK
are ignored and replaced byBUF_DISCARDABLE
. - PlAtom PlTerm::as_atom()
- Wrapper of PL_get_atom_ex(), throwing an exception if the term is not an atom.
- bool PlTerm::eq_if_atom(PlAtom a)
- Returns true if the term is an atom and equal to a.
- PlTerm::operator[] size_t index(W)
- rapper for PL_get_arg(), throwing an exception if the term isn't a compound or the index is out of range.
- size_t PlTerm::arity()
- Gets the arity of the term; throws
PlTypeError
if not a "compound" or atom. - PlAtom PlTerm::name()
- Gets the name of the term;
PlTypeError
if not a "compound" or atom. - bool name_arity(PlAtom *name, size_t *arity)
- Wrapper of PL_get_name_arity(); name and/or arity
can be
nullptr
. Returnsfalse
if the term isn't a compound or atom. - PlTerm PlTerm::copy_term_ref()
- Wrapper of PL_copy_term_ref(). Throws an exception error (e.g.,
PlResourceError
). - bool nify_term(PlTerm t2)
- Wrapper of PL_unify(). Throws an exception on error and returns
false
if unification fails. If on failure, there isn't an immediate return to Prolog (e.g., by wrapping the call with PlCheckFail()), this method should be called within the context ofPlFrame
, and PlFrame::rewind() should be called. - bool PlTerm::unify_atom(PlAtom a)
- Wrapper of PL_unify_atom(), throwing an exception on error.
- bool PlTerm::unify_chars(int flags, size_t len, const char *s)
- Wrapper of PL_unify_chars(), throwing an exception on error.
- bool PlTerm::unify_chars(int flags, const std::string& s)
- Wrapper of PL_unify_chars(), throwing an exception on error.
- bool PlTerm::unify_atom(const char* v)
- Wrapper of PL_unify_atom_chars(), throwing an exception on error.
- bool PlTerm::unify_atom(const wchar_t* v)
- Wrapper of PL_unify_wchars(), throwing an exception on error.
- bool PlTerm::unify_atom(const std::string& v)
- Wrapper of PL_unify_atom_nchars(), throwing an exception on error.
- bool PlTerm::unify_atom(const std::wstring& v)
- Wrapper of PL_unify_wchars(), throwing an exception on error. cfunctionboolPlTerm::unify_integerbool v Wrapper of PL_unify_int64(), throwing an exception on error.
- bool PlTerm::unify_integer(char v)
- Wrapper of PL_unify_int64(), throwing an exception on error.
- bool PlTerm::unify_integer(int v)
- Wrapper of PL_unify_int64(), throwing an exception on error.
- bool PlTerm::unify_integer(long v)
- Wrapper of PL_unify_int64(), throwing an exception on error.
- bool PlTerm::unify_integer(long long v)
- Wrapper of PL_unify_int64(), throwing an exception on error.
- bool PlTerm::unify_integer(short v)
- Wrapper of PL_unify_int64(), throwing an exception on error.
- bool PlTerm::unify_integer(signed char v)
- Wrapper of PL_unify_int64(), throwing an exception on error.
- bool PlTerm::unify_integer(unsigned char v)
- Wrapper of PL_unify_uint64(), throwing an exception on error.
- bool PlTerm::unify_integer(unsigned int v)
- Wrapper of PL_unify_uint64(), throwing an exception on error.
- bool PlTerm::unify_integer(unsigned long v)
- Wrapper of PL_unify_uint64(), throwing an exception on error.
- bool PlTerm::unify_integer(unsigned long long v)
- Wrapper of PL_unify_uint64(), throwing an exception on error.
- bool PlTerm::unify_integer(unsigned short v)
- Wrapper of PL_unify_uint64(), throwing an exception on error.
- bool PlTerm::unify_float(double v)
- Wrapper of PL_unify_float(), throwing an exception on error.
- bool PlTerm::unify_string(const std::string& v)
- Wrapper of PL_unify_string_nchars(), throwing an exception on error.
- bool PlTerm::unify_string(const std::wstring& v)
- Wrapper of PL_unify_wchars(), throwing an exception on error.
- bool PlTerm::unify_functor(PlFunctor f)
- Wrapper of PL_unify_functor(), throwing an exception on error.
- bool PlTerm::unify_pointer(void *ptr)
- Wrapper of PL_unify_pointer(), throwing an exception on error.
- bool PlTerm::unify_nil()
- Wrapper of PL_unify_nil(), throwing an exception on error.
- bool PlTerm::unify_list(PlTerm h, PlTerm t)
- Wrapper of PL_unify_list(), throwing an exception on error.
- bool PlTerm::unify_bool(bool val)
- Wrapper of PL_unify_bool(), throwing an exception on error.
- bool PlTerm::unify_blob(const PlBlob* blob)
- Wrapper of PL_unify_blob(), throwing an exception on error.
- bool PlTerm::unify_blob(const void *blob, size_t len, const PL_blob_t *type)
- Wrapper of PL_unify_blob(), throwing an exception on error.
- int PlTerm::compare(PlTerm t2)
- Wrapper for PL_compare(), returning -1, 0, 1 for the result of standard order comparison of the term with a2.
- bool operator ==(PlTerm t2)
compare(t2) == 0
.- bool operator !=(PlTerm t2)
compare(t2) != 0
.- bool operator <(PlTerm t2)
compare(t2) < 0
.- bool operator >(PlTerm t2)
compare(t2) > 0
.- bool operator <=(PlTerm t2)
compare(t2) <= 0
.- bool operator >=(PlTerm t2)
compare(t2) >= 0
.- int write(IOSTREAM *s, int precedence, int flags)
- Wrapper for PL_write_term().
- void reset_term_refs()
- Wrapper for PL_reset_term_refs().
- int call(PlModule module)
- Wrapper for PL_call(unwrap(); module defaults to “null” .
2.5.7 Blobs
Nomenclature warning:
There are two different release()
functions:
- The release() callback for a blob (see the definition of
PL_blob_t
). - std::unique_ptr::release(), which passes ownership of a
unique_ptr
.
Disclaimer:
The blob API for C++ is not completely general, but is designed to make common use cases easy to write. For other use cases, the underlying C API can still be used. The use case is:
- The blob is defined as a subclass of
PlBlob
, which provides a number of fields and methods, of which a few can be overridden in the blob (notably: write_fields(), compare_fields(), save(), load(), and the destructor). - The blob will not be subclassed.
- The blob contains the foreign object or a pointer to it (e.g., a database connection or a pointer to a database connection), plus optionally some other data.
- The blob is created by a predicate that makes the foreign object and
stores it (or a pointer to it) within the blob - for example, making a
connection to a database or compiling a regular expression into an
internal form. This “create” predicate uses
std::unique_ptr
to manage the blob (that is, the blob is created using the new operator and is not created on the stack). - Optionally, there can be a predicate that deletes the foreign object, such as a file or database connection close.
- The blob can be garbage collected, althought this might require calling the predicate that deletes the foreign object first. There is no provision for handling “weak references” (e.g., a separate lookup table or cache for the foreign objects).
- The blob must have a default constructor that sets all the fields to appropriate initial values.11This is used by the load() callback; the default implementation for a C++ blob is to throw an error.
- The blob's constructor throws an exception and cleans up any resources if it cannot create the blob.12This is not a strong requirement, but the code is simpler if this style is used.
- The foreign object can be deleted when the blob is deleted. That is,
the foreign object is created using the
new
operator and passes ownership to the blob. More complex behavior is possible, using PlAtom::register_ref() and PlAtom::unregister_ref(). - The blob's lifetime is controlled by Prolog and its destructor is invoked when the blob is garbage collected. Optionally, the predicate that deletes the foreign object deletes the foreign object and the Prolog garbage collector only frees the blob.
A Prolog blob consists of five parts:
- A
PL_blob_t
structure that defines the callbacks. The PL_BLOB_DEFINITION() macro is typically used to create this, with the callbacks pointing to methods in the C++ blob. - A structure that contains the blob data. This must have a
constructor that references the
PL_blob_t
structure, and optionally a virtual destructor. ThePL_BLOB_SIZE
macro is used to define some required methods. - A “create” or “open” predicate that unifies
one of its arguments with a newly created blob that contains the foreign
object. The blob is created using the new operator (not
on the stack) and managed with
std::unique_ptr
. - (Optionally) a “close” predicate that does the opposite of the “create” or “open” predicate.
- Predicates that manipulate the foreign object (e.g., for a file-like object, these could be read, write, seek, etc.).
For the PL_blob_t
structure, the C++ API provides the
PL_BLOB_DEFINITION(blob_class,blob_name) macro, which references
a set of template functions that allow easily setting up the callbacks.
The C interface allows more flexibility by allowing some of the
callbacks to default; however, the C++ API for blobs provides suitable
callbacks for all of them, using the PL_BLOB_DEFINITION() macro.
For the data, which is subclassed from PlBlob
, the
programmer defines the various fields, a constructor that initializes
them, and a destructor. Optionally, override methods can be defined for
one of more of the methods PlBlob::compare_fields(), PlBlob::write_fields(),
PlBlob::save(), PlBlob::load(), PlBlob::pre_delete().
More details on these are given later.
There is a mismatch between how Prolog does memory management (and
garbage collection) and how C++ does it. In particular, Prolog assumes
that cleanup will be done in the release() callback function
associated with the blob whereas C++ typically does cleanup in a
destructor. The blob interface gets around this mismatch by providing a
default release() callback that assumes that the blob was created
using PL_BLOB_NOCOPY
and manages memory using a
std::unique_ptr
.13This release()
function has nothing to do with std::unique_ptr::release().
More details on this are in
section 2.5.7.1.
The C blob interface has a flag that determines how memory is
managed:
PL_BLOB_NOCOPY
. The PL_BLOB_DEFINITION() macro sets
this, so Prolog will call the C++ destructor when the blob is garbage
collected. (This call is done indirectly, using a callback that is
registeered with Prolog.)
The C++ API for blobs only supports blobs with
PL_BLOB_NOCOPY
.14The
API can probably also support blobs with PL_BLOB_UNIQUE
,
but there seems to be little point in setting this flag for non-text
blobs.
2.5.7.1 A review of C++ features used by the API
Some slightly obscure features of C++ are used with PlBlob
and
ContextType
, and can easily cause subtle bugs or memory
leaks if not used carefully.
When a C++ object is created, its memory is allocated (either on the stack or on the heap using new), and the constructors are called in this order:
- the base class's constructor (possibly specified in the intialization list)
- the constructors for all the fields (possibly specified by an initial value and/or being in the initialization list)
- the object's constructor.
There are special forms of the constructor for copying, moving, and
assigning. The “copy constructor” has a signature Type(const
Type&
and is used when an object is created by copying, for
example by assignment or passing the object on the stack in a function
call. The “move constructor” has the signature Type(Type&&
and is equivalent to the copy constructor for the new object followed by
the destructor for the old object. (Assignment is usually allowed to
default but can also be specified).
Currently, the copy and move constructors are not used, so it is best to explicitly mark them as not existing:
Type(const Type&) = delete; Type(Type&&) = delete; Type& operator =(const Type&) = delete; Type& operator =(Type&&) = delete;
A constructor may throw an exception - good programming style is to not leave a “half constructed” object but to throw an exception. Destructors are not allowed to throw exceptions,15because the destructor might be invoked by another exception, and C++ has no mechanism for dealing with a second exception. which complicates the API somewhat.
More details about constructors and destructors can be found in the FAQs for constructors and destructors.
Many classes or types have a constructor that simply assigns a
default value (e.g., 0 for int
) and the destructor does
nothing. In particular, the destructor for a pointer does nothing, which
can lead to memory leaks. To avoid memory leaks, the smart pointer
std::unique_ptr
16The
name “unique” is to distinguish this from a “shared” pointer.
A shared pointer can share ownership with multiple pointers and the
pointed-to object is deleted only when all pointers to the object have
been deleted. A unique pointer allows only a single pointer, so the
pointed-to object is deleted when the unique pointer is deleted.
can be used, whose destructor deletes its managed object. Note that std::unique_ptr
does not enforce single ownership; it merely makes single ownership easy
to manage and it detects most common mistakes, for example by not having
copy constructor or assignment operator.
For example, in the following, the implicit destructor for p
does nothing, so there will be a memory leak when a Ex1
object is deleted:
class Ex1 { public: Ex1() : p(new int) { } int *p; };
To avoid a memory leak, the code could be changed to this:
class Ex1 { public: Ex1() p(new int) { } ~Ex1() { delete p; } int *p; };
but it is easier to do the following, where the destructor for
std::unique_ptr
will free the memory:
class Ex1 { public: Ex1() p(new int) { } std::unique_ptr<int> p; };
The same concept applies to objects that are created in code - if a
C++ object is created using new, the programmer must
manage when its destructor is called. In the following, if the call to
data->validate()
fails, there will be a memory
leak:
MyData *foo(int some_value) { MyData *data = new MyData(...); data->some_field = some_value; if (! data->validate() ) throw std::runtime_error("Failed to validate data"); return data; }
Ths could fixed by adding delete data
before throwing
the runtime_error
; but this doesn't handle the situation of data->validate()
throwing an exception (which would require a catch/throw). Instead, it's
easiser to use std::unique_ptr
, which takes care of every
return or exception path:
MyData *foo(int some_value) { std::unique_ptr<MyData> data(new MyData(...)); data->some_field = some_value; if (! data->validate() ) throw std::runtime_error("Failed to validate data"); return data.release(); // don't delete the new MyData }
The destructor for std::unique_ptr
will delete the data
when it goes out of scope (in this case, by return or throw) unless the
std::unique_ptr::release() method is called.17The
call to unique_ptr<MYData>::release
doesn't call the destructor; it can be called using std::unique_ptr::get_deleter().
In the code above, the throw
will cause the
unique_ptr
’s destructor to be called, which will free
the data; but the data will not be freed in the return
statement because of the unique_ptr::release(). Using this style,
a pointer to data on the heap can be managed as easily as data on the
stack. The current C++ API for blobs takes advantage of this - in
particular, there are two methods for unifying a blob:
- PlTerm::unify_blob(const PlBlob* blob) - does no memory management
- PlTerm::unify_blob(std::unique_std<PlBlob>* blob) - if unification fails or raises an error, the memory is automatically freed; otherwise the memory's ownership is transferred to Prolog, which may garbage collect the blob by calling the blob's destructor. Note that this uses a pointer to the pointer, so that PlTerm::unify_blob() can modify it.
unique_ptr
allows specifying the delete function. For
example, the following can be used to manage memory created with PL_malloc():
std::unique_ptr<void, decltype(&PL_free)> ptr(PL_malloc(...), &PL_free);
or, when memory is allocated within a PL_*() function (in this case, using the Plx_*() wrapper for PL_get_nchars()):
size_t len; char *str = nullptr; Plx_get_nchars(t, &len, &str.get(), BUF_MALLOC|CVT_ALL|CVT_WRITEQ|CVT_VARIABLE|REP_UTF8|CVT_EXCEPTION); std::unique_ptr<char, decltype(&PL_free)> _str(str, &PL_free);
The current C++ API assumes that the C++ blob is allocated on the
heap. If the programmer wishes to use the stack, they can use std::unique_ptr
to automatically delete the object if an error is thrown -
PlTerm::unify_blob(std::unique_ptr<PlBlob>*)
prevents the automatic deletion if unification succeeds.
A unique_ptr
needs a bit of care when it is passed as an
argument. The unique_ptr::get() method can be used to get the “raw” pointer;
the delete must not be used with this pointer. Or, the unique_ptr::release()
method can be used to transfer ownership without calling the object's
destructor.
Using unique_ptr::release() is a bit incovenient, so instead
the
unique_ptr
can be passed as a pointer (or a reference).
This does not create a new scope, so the pointer must be assigned to a
local variable. For example, the code for unify_blob() is
something like:
bool PlTerm::unify_blob(std::unique_ptr<PlBlob>* b) const { std::unique_ptr<PlBlob> blob(std::move(*b)); if ( !unify_blob(blob.get()) ) return false; (void)blob.release(); return true; }
The line declaration for blob
uses the “move
constructor” to set the value of a newly scoped variable (std::move(*b)
is a cast, so unique_ptr
’s move constructor is used).
This has the same effect as calling b->reset()
,
so from this point on,
b
has the value nullptr
.
Alternatively, the local unique_ptr
could be set by
std::unique_ptr<PlBlob> blob(b->release());
or
std::unique_ptr<PlBlob> blob; blob.swap(*b);
If the call to PlTerm::unify_blob()
fails or throws an exception, the virtual destructor for blob
is called. Otherwise, the call to blob.release()
prevents the destructor from being called - Prolog now owns the blob
object and can call its destructor when the garbage collector reclaims
it.
2.5.7.2 How to define a blob using C++
TL;DR: Use PL_BLOB_DEFINITION() to define the blob with the
flag
PL_BLOB_NOCOPY
and the default PlBlob
wrappers; define your struct as a subclass of PlBlob
with
no copy constructor, move constructor, or assignment operator; create a
blob using
std::unique_ptr<PlBlob>(new ...)
, call PlTerm::unify_blob().
Optionally, define one or more of: compare_fields(), write_fields(),
save(), load() methods (these are described after the
sample code).
2.5.7.3 The life of a PlBlob
In this section, the blob is of type MyBlob
, a subclass
of PlBlob
. (Example code is given in section
2.5.7.5)
A blob is typically created by calling a predicate that does the following:
- Creates the blob using
auto ref = std::unique_ptr<PlBlob>(new MyBlob>(...))}
or
auto ref = std::make_unique<MyBlob>(...);
- After the fields of the blob are filled in:
return PlTerm::unify_blob(&ref);
If unification fails or throws an exception, the object is automatically freed and its destructor is called.
If make_unique() was used to create the pointer, you need to call PlTerm::unify_blob() as follows, because C++'s type inferencing can't figure out that this is a covariant type:
std::unique_ptr<PlBlob> refb(ref.release()); // refb now "owns" the ptr - from here on, ref == nullptr return A2.unify_blob(&refb);
If unification succeeds, Prolog calls:
- PlBlobV<MyBlob>acquire(), which calls
- MyBlob::acquire(), which sets the field MyBlob::symbol_,
which is usually accessed using the method MyBlob::symbol_term().
If this all succeeds, PlTerm::unify_blob(ref)
calls
ref->release()
to pass ownership of the blob to Prolog (when the blob is eventually garbage collected, the blob's destructor will be called).
At this point, the blob is owned by Prolog and may be freed by its
atom garbage collector, which will call the blob's destructor (if the
blob shouldn't be deleted, it can override the the PlBlob::pre_delete()
method to return false
).
Whenever a predicate is called with the blob as an argument (e.g., as A1),
the blob can be accessed by
PlBlobv<MyBlob>::cast_check(A1.as_atom())
.
Within a method, the Prolog blob can be accessed as a term (e.g., for
constructing an error term) using the method MyBlob::symbol_term().
This field is initialized by the call to PlTerm::unify_blob();
if
MyBlob::symbol_term() is called before a successful call to
PlTerm::unify_blob(), MyBlob::symbol_term()
returns a
PlTerm_var
.
When the atom garbage collector runs, it frees the blob by first calling the release() callback, which does delete, which calls the destructor MyBlob::~MyBlob(). Note that C++ destructors are not supposed to raise exception; they also should not cause a Prolog error, which could cause deadlock unless the real work is done in another thread.
Often it is desired to release the resources before the garbage collector runs. To do this, the programmer can provide a “close” predicate that is the inverse of the “open” predicate that created the blob. This typically has the same logic as the destructor, except that it can raise a Prolog error.
2.5.7.4 C++ exceptions and blobs
When a blob is used in the context of a PREDICATE()
macro, it can raise a C++ exception (PlFail
or PlException
)
and the
PREDICATE() code will convert
the exception to the appropriate Prolog failure or error; memory
allocation exceptions are also handled.
Blobs have callbacks, which can run outside the context of a PREDICATE(). Their exception handling is as follows:
- void PlBlob::acquire()
- , which is called from PlBlobV<MyBlob>::acquire(), can throw a C++ exception. The programmer cannot override this.
- int PlBlob::compare_fields(const PlBlob *_b)
- , which is called from PlBlobV<MyBlob>::compare(), should not throw an exception. A Prolog error won't work as it uses “raw pointers” and thus a GC or stack shift triggered by creating the exception will upset the system.
- bool PlBlob::write_fields(IOStream *s, int flags)
- , which is called from PlBlobV<MyBlob>::write(), can throw an exception, just like code inside a PREDICATE(). In particular, you can wrap calls to Sfprintf() in PlCheckFail(), although the calling context will check for errors on the stream, so checking the Sfprintf() result isn't necessary.
- void PlBlob::PlBlob::save(IOStream *fd)
- can throw a C++ exception, including PlFail().
- PlAtom PlBlob::PlBlob::load(IOSTREAM *fd)
- can throw a C++ exception, which is converted to a return value of
PlAtom::null
, which is interpreted by Prolog as failure. - bool PlBlob::PlBlob::pre_delete()
- , which is called from PlBLobV<MyBLOB>::release(),
can return
false
(or throw aPlException
orPlExceptinFailBase
, which will be interpreted as a return value offalse
), resulting in the blob not being garbage collected, and the destructor not being called. Note that this doesn't work well with final clean-up atom garbage collection, which disregards the return value and also doesn't respect the ordering of blob dependencies (e.g., if an iterator blob refers to a file-like blob, the file-like blob might be deleted before the iterator is deleted).This code runs in the
gc
thread. The only PL_*() function that can safely be called are PL_unregister_atom() (which is what PlAtom::unregister_ref() calls).
2.5.7.5 Sample PlBlob code
Here is minimal sample code for creating a blob that owns a
connection to a database. It has a single field (connection
)
and defines compare_fields() and write_fields().
struct MyConnection { std::string name; explicit MyConnection(); explicit MyConnection(const std::string& _name); ~MyConnection() { } bool open(); bool close() noexcept; void portray(PlStream& strm) const; }; struct MyBlob; static PL_blob_t my_blob = PL_BLOB_DEFINITION(MyBlob, "my_blob"); struct MyBlob : public PlBlob { std::unique_ptr<MyConnection> connection; explicit MyBlob() : PlBlob(&my_blob) { } explicit MyBlob(const std::string& connection_name) : PlBlob(&my_blob), connection(std::make_unique<MyConnection>(connection_name)) { if ( !connection->open() ) throw MyBlobError("my_blob_open_error"); } PL_BLOB_SIZE ~MyBlob() noexcept { if ( !close() ) Sdprintf("***ERROR: Close MyBlob failed: %s\n", name().c_str()); // Can't use PL_warning() } inline std::string name() const { return connection ? connection->name : ""; } bool close() noexcept { if ( !connection ) return true; bool rc = connection->close(); connection.reset(); // Can be omitted, leaving deletion to ~MyBlob() return rc; } PlException MyBlobError(const char* error) const { return PlGeneralError(PlCompound(error, PlTermv(symbol_term()))); } int compare_fields(const PlBlob* _b_data) const override { auto b_data = static_cast<const MyBlob*>(_b_data); // See note about cast return name().compare(b_data->name()); } bool write_fields(IOSTREAM *s, int flags) const override { PlStream strm(s); strm.printf(","); return write_fields_only(strm); } bool write_fields_only(PlStream& strm) const { if ( connection ) connection->portray(strm); else strm.printf("closed"); return true; } bool portray(PlStream& strm) const { strm.printf("MyBlob("); write_fields_only(strm); strm.printf(")"); return true; } }; // %! create_my_blob(+Name: atom, -MyBlob) is semidet. PREDICATE(create_my_blob, 2) { // Allocating the blob uses std::unique_ptr<MyBlob> so that it'll be // deleted if an error happens - the auto-deletion is disabled by // ref.release() inside unify_blob() before returning success. auto ref = std::unique_ptr<PlBlob>(new MyBlob(A1.as_atom().as_string())); return A2.unify_blob(&ref); } // %! close_my_blob(+MyBlob) is det. // % Close the connection, silently succeeding if is already // % closed; throw an exception if something goes wrong. PREDICATE(close_my_blob, 1) { auto ref = PlBlobV<MyBlob>::cast_ex(A1, my_blob); if ( !ref->close() ) throw ref->MyBlobError("my_blob_close_error"); return true; } // %! portray_my_blob(+Stream, +MyBlob) is det. // % Hook predicate for // % user:portray(MyBlob) :- // % blob(MyBlob, my_blob), !, // % portray_my_blob(current_output, MyBlob). PREDICATE(portray_my_blob, 2) { auto ref = PlBlobV<MyBlob>::cast_ex(A2, my_blob); PlStream strm(A1, 0); return ref->portray(strm); }
2.5.7.6 Discussion of the sample PlBlob code
- PL_BLOB_DEFINITION(MyBlob, "my_blob") creates a
PL_blob_t
structure with the wrapper functions and flags set toPL_BLOB_NOCOPY
. It should be declared outside thePlBlob
class and should not be markedconst
- otherwise, a runtime error can occur.18The cause of the runtime error is not clear, but possibly has to do with the order of initializing globals, which is unspecified for C++. - The
MyBlob
struct is a subclass ofPlBlob
. See below for a discussion of the default behaviors.MyBlob
contains a pointer to aMyConnection
object and keeps a copy of the connection's name. TheMyConnection
object is handled by astd::unique_ptr
smart pointer, so that it is automatically freed when theMyBlob
object is freed.- A default constructor is defined - this is needed for the
load() and save() methods; it invokes the
PlBlob
constructor. - The
MyBlob
class must not provide a copy or move constructor, nor an assignment operator (PlBlob has these as delete, so if you try to use one of these, you will get a compile-time error). PlBlob
’s constructor setsblob_t_
to a pointer to themy_blob
definition. This is used for run-time consistency checking by the various callback functions and for constructing error terms (see PlBlob::symbol_term()).PlBlob
’s acquire() is called by PlBlobV<MyBlob>::acquire() and fills in thesymbol_
field.MyBlob
must not override this - it is not a virtual method. Thesymbol_
field can be accessed by PlBlob::symbol_term().- PlBlob::symbol_term() Creates a term from the blob, for use
in error terms. It is always safe to use this; if the symbol hasn't been
set (because acquire() hasn't been called),
symbol_term() returns a “var” term - this can be
checked with PlTerm::is_variable().
- The MyBlob(connection_name) constructor creates a
MyConnection
object. If this fails, an exception is thrown. The constructor then calls MyConnection::open() and throws an exception if that fails. (The code would be similar if instead the constructor forMyConnection
also did an open and threw an exception on failure.) - The
PL_BLOB_SIZE
is boilerplate that defines a blob_size_() method that is used when the blob is created. - The destructor MyBlob() is called when the blob is
released by the garbage collector and in turn calls the MyBlob::close(),
throwing away the result. If there is an error, a message is printed
because there is no other way report the error. For this reason, it is
preferred that the program explicitly calls the
close_my_blob/1
predicate, which can raise an error. One way of doing this is by using
the at_halt/1
hook.
- The MyBlob::close() method is called by either the destructor
or by the close_my_blob/1
predicate. Because it can be called by the garbage collector, which does
not provide the usual environment and which may also be in a different
thread, the only Prolog function that can be called is
PlAtom::unregister_ref(); and the MyBlob::close() method
must not throw an exception.19It
isn't enough to just catch exceptions; for example, if the code throws
PlUnknownError("...")
, that will try to create a Prolog term, which will crash because the environment for creating terms is not available. Because there is no mechanism for reporting an error, the destructor prints a message on failure (calling PL_warning() would cause a crash).PlBlob::close() calls MyConnection::close() and then frees the object. Error handling is left to the caller because of the possibility that this is called in the context of garbage collection. It is not necessary to free the
MyConnection
object here - if it is not freed, thestd::unique_ptr<MyConnection>
’s destructor would free it. - PlBlob::MyBlobError() is a convenience method for creating
errror terms.
- PlBlob::compare_fields()
makes the blob comparison function more deterministic by comparing the
name fields; if the names are the same, the comparison will be done by
comparing the addresses of the blobs (which is the default behavior for
blobs defined using the C API).
PlBlob::compare_fields()
is called by PlBlobV<PlBlob>::compare(), which
provides the default comparison if PlBlob::compare_fields()
returns
0
(``equal” ).The _b_data argument is of type
const PlBlob*
- this is cast toconst MyBlob*
using astatic_cast
. This is safe because Prolog guarantees that PlBlobV<PlBlob>::compare() will only be called if both blobs are of the same type. - PlBlob::write_fields()
outputs the name and the status of the connection, in addition to the
default of outputting the blob type and its address. This is for
illustrative purposes only; an alternative is to have a my_blob_properties/2
predicate to provide the information.
The flags argument is the same as given to PlBlobV<PlBlob>::write(), which is a bitwise or of zero or more of the
PL_WRT_*
flags that were passed in to the caling PL_write_term() (defined inSWI-Prolog.h
). The flags do not have thePL_WRT_NEWLINE
bit set, so it is safe to call PlTerm::write() and there is no need for writing a trailing newline.If anything in PlBlob::write_fields() throws a C++ exception, it will be caught by the calling PlBlobV<PlBlob>::write() and handled appropriately.
- PlBlob::save() and PlBlob::load() are not defined, so
the defaults are used - they throw an error on an attempt to save the
blob (e.g., by using qsave_program/[1,2]).20The
C API defaults would save the internal form of the blob, which is
probably not what you want, so the C++ API throws an error as its
default.
- create_my_blob/2
predicate:
std::unique_ptr<PlBlob>()
creates a MyBlob that is deleted when it goes out of scope. If an exception occurs between the creation of the blob or if the call to unify_blob() fails, the pointer will be automatically freed (and theMyBlob
destructor will be called).PlTerm::unify_blob() is called with a pointer to a
std::unique_ptr
, which takes ownership of the object by calling std::unique_ptr<PlBlob>::release() and passes the pointer to Prolog, which then owns it. This also sets ref tonullptr
, so any attempt to use ref after a call to PlTerm::unify_blob() will be an error.If you wish to create a
MyBlob
object instead of aPlBlob
object, a slightly different form is used:auto ref = std::make_unique<MyBlob>(...); ... std::unique_ptr<PlBlob> refb(ref.release()); PlCheckFail(A2.unify_blob(&refb)); return true;
- close_my_blob/1
predicate:
- The argument is turned into a
MyBlob
pointer using the PlBlobV<MyBlob>::cast_ex() function, which will throw atype_error
if the argument isn't a blob of the expected type. - The MyBlob::close() method is called - if it fails, a Prolog
error is thrown.
- The argument is turned into a
2.5.7.7 Identifying blobs by atoms
Passing a Prolog blob around can be inconvenient; it is easier if a
blob can be identified an atom. An example of this is with streams,
which are identified by atoms such as user_input
.
A utility class AtomMap
is provided for this situation.
See section 2.16.4.
2.5.8 Limitations of the interface
The C++ API remains a work in progress.
2.5.8.1 Strings
SWI-Prolog string handling has evolved over time. The functions that
create atoms or strings using char*
or wchar_t*
are “old school” ; similarly with functions that get the
string as
char*
or wchar_t*
. The PL_get_unify_put_[nw]chars()
family is more friendly when it comes to different input, output,
encoding and exception handling.
Roughly, the modern API is PL_get_nchars(), PL_unify_chars() and PL_put_chars() on terms. There is only half of the API for atoms as PL_new_atom_mbchars() and PL-atom_mbchars(), which take an encoding, length and char*.
For return values, char*
is dangerous because it can
point to local or stack memory. For this reason, wherever possible, the
C++ API returns a std::string
, which contains a copy of the
string. This can be slightly less efficient that returning a
char*
, but it avoids some subtle and pervasive bugs that
even address sanitizers can't detect.21If
we wish to minimize the overhead of passing strings, this can be done by
passing in a pointer to a string rather than returning a string value;
but this is more cumbersome and modern compilers can often optimize the
code to avoid copying the return value.
Some functions require allocating string space using PL_STRINGS_MARK().
The PlStringBuffers
class provides a RAII wrapper
that ensures the matching PL_STRINGS_RELEASE() is done. The PlAtom
or PlTerm
member functions that need the string buffer use PlStringBuffers
,
and then copy the resulting string to a std::string
value.
The C++ API has functions such as PlTerm::get_nchars()
that use
PlStringBuffers
and then copy the result to a
std::string
result, so the programmer often doesn't need to
use PlStringBuffers
.
- PlStringBuffers
- A RAII wrapper for allocating a string that is created using
BUF_STACK
. This isn't needed if you use a method such as PlTerm::as_string(), but is needed for calling certain PL_*() or Plx_*() wrapped functions.The constructor calls PL_STRINGS_MARK() and the destructor calls PL_STRINGS_RELEASE(). Here is an example of its use, for writing an atom to a stream, using Plx_atom_wchars(), which must be called within a strings buffer:
PREDICATE(w_atom_cpp, 2) { auto stream(A1), term(A2); PlStream strm(stream, STIO_OUTPUT); PlStringBuffers _string_buffers; const pl_wchar_t *sa = Plx_atom_wchars(term.as_atom().unwrap(), nullptr); strm.printfX("/%Ws/", sa); return true; }
2.5.8.2 Stream I/O
PlStream
can be used to get a stream from a Prolog term,
or to lock the stream so that other threads cannot interleave their
output. With either usage, PlStream
is a RAII
class that ensure the matchin PL_release_stream() is done, and
also handles some subtle problems with C++ exceptions.
The methods are:
-
- PlStream :: PlStream(term_t t, int flags)
- - see PL_get_stream() for documentation of the flags. Throws a C++ exception on error.
- PlStream :: PlStream(IOSTREAM *s)
- - calls PL_acquire_stream() to lock the stream. Throws a C++ exception on error.
- ~ PlStream()
- - calls PlStream::release(). See below for caveats if there are exceptions.
- void PlStream::release()
- calls PL_release_stream(), throwing an exception if there has been an I/O error on the stream, and sets the
PlStream
object to an invalid stream (see PlStream::check_stream()).- IOSTREAM* ::operator PlStream(void)
- - when used in a context that requires an
IOSTREAM*
,PlStream
is implicitly converted toIOSTREAM*
.- cfunctionvoidcheck_stream checks that the
PlStream
object contains a valid stream and throws an exception if it doesn't. This is used to ensure that PlStream::release() hasn't been called.- Most of the stream I/O functions have corresponding methods in
PlStream
. For example, Sfprintf() corresponds to PlStream::printf().
The C interface to stream I/O doesn't raise a Prolog error when
there's a stream error (typically indicated by a -1 return code).
Instead, the error sets a flag on the stream and
PL_release_stream() creates the error term. The
PlStream
destructor calls PL_release_stream(); but
it's a fatal error in C++ to raise an exception in a destructor if the
destructor is invoked by stack-unwinding due to another exception,
including the pseudo-exceptions PlFail
and
PlExceptionFail
.
To get around this, the various stream I/O functions have wrapper
methods in the PlStream
class that check for an error and
call PlStream::release()
to create the Prolog error, which is thrown as a C++ error.
The destructor calls PlStream::release(), which throws a C++ exception if there is a stream error. This is outside the destructor, so it is safe - the destructor checks if the stream has been released and does nothing in that situation.
The following two code examples do essentially the same thing:
PREDICATE(name_arity, 1) { PlStream strm(Scurrent_output); strm.printf("name = %s, arity = %zd\n", A1.name().as_string().c_str(), A1.arity()); return true; }
PREDICATE(name_arity, 1) { PlStream strm(Scurrent_output); try { strm.printf("name = %s, arity = %zd\n", A1.name().as_string().c_str(), A1.arity()); } PREDICATE_CATCH({strm.release(); return false;}) return true; }
If you write the code as follows, using Sfprintf() directly, it is possible that a fatal exception will be raised on an I/O error:
PREDICATE(name_arity, 1) { PlStream strm(Scurrent_output); Sfprintf(strm, "name = %s, arity = %zd\n", A1.name().as_string().c_str(), A1.arity()); return true; // WARNING: the PlStream destructor might throw a C++ // exception on stack unwinding, giving a fatal // fatal runtime exception. }
If you don't use these, and want to throw an exception if there's an
error, the following code works because PlStream
(and the
underlying PL_acquire_stream()) can be called recursively:
{ PlStream strm(...); strm.release(); }
2.5.8.3 Object handles
Many of the “opaque object handles” , such as atom_t
,
term_t
, and functor_t
are integers.22Typically uintptr_t
values, which the C standard defines as “an unsigned integer type
with the property that any valid pointer to void can be converted to
this type, then converted back to pointer to void, and the result will
compare equal to the original pointer.’ As such,
there is no compile-time detection of passing the wrong handle to a
function.
This leads to a problem with classes such as PlTerm
-
C++ overloading cannot be used to distinguish, for example, creating a
term from an atom versus creating a term from an integer. There are a
number of possible solutions, including:
- A subclass for each kind of initializer;
- A tag for each kind of intializer;
- Change the C code to use a
struct
instead of an integer.
It is impractical to change the C code, both because of the amount of edits that would be required and also because of the possibility that the changes would inhibit some optimizations.
There isn't much difference between subclasses versus tags; but as a matter of design, it's better to specify things as constants than as (theoretically) variables, so the decision was to use subclasses.
2.5.9 Linking embedded applications using swipl-ld
The utility program swipl-ld (Win32: swipl-ld.exe) works with both C and C++ programs. See Linking embedded applications using swipl-ld for more details.
Your C++ compiler should support at least C++-17.
To avoid incompatibilities amongst the various C++ compilers’ABIs,
the object file from compiling SWI-cpp2.cpp
is not included
in the shared object libswipl
; instead, it must be compiled
along with any foreign predicate files. If the macro
_SWI_CPP2_CPP_SEPARATE
is defined before the include for
SWI-cpp2.h
, then SWI-cpp2.cpp
is not
automatically included and must be compiled separately - either by
creating a
.a
file or by adding a #include <SWI-cpp2.cpp>
to one of your source files.
2.6 Examples (version 2)
Before going into a detailed description of the C++ classes we present a few examples illustrating the‘feel’of the interface.
2.6.1 Hello(World) (version 2)
This simple example shows the basic definition of the predicate hello/1 and how a Prolog argument is converted to C-data:
PREDICATE(hello, 1) { cout << "Hello " << A1.as_string() << endl; return true; }
The arguments to PREDICATE()
are the name and arity of the predicate. The macros A<n>
provide access to the predicate arguments by position and are of the
type PlTerm
. The C or C++ string for a PlTerm
can be extracted using as_string(),
or as_wstring() methods;23The
C-string values can be extracted from std::string
by using c_str(),
but you must be careful to not return a pointer to a local/stack value,
so this isn't recommende. and similar access methods
provide an easy type-conversion for most Prolog data-types, using the
output of write/1
otherwise:
?- hello(world). Hello world Yes ?- hello(X) Hello _G170 X = _G170
2.6.2 Adding numbers (version 2)
This example shows arithmetic using the C++ interface, including unification, type-checking, and conversion. The predicate add/3 adds the two first arguments and unifies the last with the result.
PREDICATE(add, 3) { return A3.unify_integer(A1.as_long() + A2.as_long()); }
You can use your own variable names instead of A1
,
A2
, etc.:
PREDICATE(add, 3) // add(+X, +Y, +Result) { PlTerm x(A1); PlTerm y(A2); PlTerm result(A3); return result.unify_integer(x.as_long() + y.as_long()); }
or more compactly:
PREDICATE(add, 3) // add(+X, +Y, +Result) { auto x = A1, y = A2, result = A3; return result.unify_integer(x.as_long() + y.as_long()); }
The as_long() method for a PlTerm
performs a PL_get_long_ex()
and throws a C++ exception if the Prolog argument is not a Prolog
integer or float that can be converted without loss to a
long
. The unify_integer() method of PlTerm
is defined to perform unification and returns true
or false
depending on the result.
?- add(1, 2, X). X = 3. ?- add(a, 2, X). [ERROR: Type error: `integer' expected, found `a'] Exception: ( 7) add(a, 2, _G197) ?
2.6.3 Average of solutions - calling a Prolog goal (version 2)
This example is a bit harder. The predicate average/3 is defined to take the template average(+Var, :Goal, -Average) , where Goal binds Var and will unify Average with average of the (integer) results.
PlQuery
takes the name of a predicate and the
goal-argument vector as arguments. From this information it deduces the
arity and locates the predicate. The method PlQuery::next_solution()
yields
true
if there was a solution and false
otherwise. If the goal yields a Prolog exception, it is mapped into a
C++ exception. A return to Prolog does an implicit “cut” (PL_cut_query());
this can also be done explicitly by the PlQuery::cut()
method.
PREDICATE(average, 3) /* average(+Templ, :Goal, -Average) */ { long sum = 0; long n = 0; PlQuery q("call", PlTermv(A2)); while( q.next_solution() ) { sum += A1.as_long(); n++; } return A3.unify_float(double(sum) / double(n)); }
?- [user]. |: p(1). |: p(10). |: p(20). |: % user://1 compiled 0.00 sec, 3 clauses true. ?- average(X, p(X), Average). Average = 10.333333333333334.
2.7 Rationale for changes from version 1 (version 2)
2.7.1 Implicit constructors and conversion operators
The original version of the C++ interface heavily used implicit constructors and conversion operators. This allowed, for example:
PREDICATE(hello, 1) { cout << "Hello " << (char *)A1 << endl; // Deprecated return true; } PREDICATE(add, 3) { return A3 = (long)A1 + (long)A2; // Deprecated }
Version 2 is a bit more verbose:
PREDICATE(hello, 1) { cout << "Hello " << A1.as_string() << endl; return true; } PREDICATE(add, 3) { return A3.unify_int(A1.as_long() + A2.as_long()); }
There are a few reasons for this:
- The implicit constructors and conversion operators, combined with the C++ conversion rules for integers and floats, could sometimes lead to subtle bugs that were difficult to find -- in one case, a typo resulted in terms being unified with floating point values when the code intended them to be atoms. This was mainly because the underlying C types for terms, atoms, etc. are unsigned integers, leading to confusion between numeric values and Prolog terms and atoms.
- The overloaded assignment operator for unification changed the usual
C++ semantics for assignments from returning a reference to the
left-hand-side to returning a
bool
. In addition, the result of unification should always be checked (e.g., an “always succeed” unification could fail due to an out-of-memory error); the unify_XXX() methods return abool
and they can be wrapped inside a PlCheckFail() to raise an exception on unification failure. - The C-style of casts is deprecated in C++, so the expression
(char*)A1
becomes the more verbosestatic_cast<std::string>(A1)
, which is longer thanA1.as_string()
. Also, the string casts don't allow for specifying encoding. - The implicit constructors and conversion operators were attractive
because they allowed directly calling the foreign language interface
functions, for example:
PlTerm t; Pl_put_atom_chars(t, "someName");
whereas this is now required:
PlTerm t; Pl_put_atom_chars(t.as_term_t(), "someName");
However, this is mostly avoided by methods and constructors that wrap the foreign language functions:
PlTerm_atom t("someName");
or
auto t = PlTerm_atom("someName");
Additionally, there are now wrappers for most of the PL_*() functions that check the error return and throw a C++ exception as appropriate.
Over time, it is expected that some of these restrictions will be eased, to allow a more compact coding style that was the intent of the original API. However, too much use of overloaded methods/constructors, implicit conversions and constructors can result in code that's difficult to understand, so a balance needs to be struck between compactness of code and understandability.
For backwards compatibility, much of the version 1 interface is still available (except for the implicit constructors and operators), but marked as “deprecated” ; code that depends on the parts that have been removed can be easily changed to use the new interface.
2.7.2 Strings
The version API often used char*
for both setting and
setting string values. This is not a problem for setting (although
encodings can be an issue), but can introduce subtle bugs in the
lifetimes of pointers if the buffer stack isn't used properly. PlStringBuffers
makes the buffer stack easier to use, but it would be preferable to
avoid its use altogether. C++, unlike C, has a standard string that
allows easily keeping a copy rather than dealing with a pointer that
might become invalid. (Also, C++ strings can contain null characters.)
C++ has default conversion operators from char*
to
std::string
, so some of the API support only
std::string
, even though this can cause a small
inefficiency. If this proves to be a problem, additional overloaded
functions and methods can be provided in future (note that some
compilers have optimizations that reduce the overheads of using
std::string
); but for performance-critical code, the C
functions can still be used.
There still remains the problems of Unicode and encodings.
std::wstring
is one way of dealing with this. And for
interfaces that use std::string
, an encoding can be
specified.24As of 2023-04, this
had only been partially implemented. Some of the details
for this - such as the default encoding - may change slightly in the
future.
2.8 Porting from version 1 to version 2
The easiest way of porting from SWI-cpp.h
to SWI-cpp2.h
is to change the #include "SWI-cpp.h"
to #include
"SWI-cpp2.h"
and look at the warning and error messages. Where
possible, version 2 keeps old interfaces with a “deprecated” flag
if there is a better way of doing things with version 2.
For convenience when calling PL_*() functions, the Plx_*() wrapper
functions add error checking. Also, most of the PL_*() functions that
work with term_t
, atom_t
, etc. have
corresponding methods in PlTerm
, PlAtom
, etc.
Here is a list of typical changes:
- Replace PlTerm() constructor with
PlTerm_var() for uninstantiated variables,
PlTerm_atom(a) for atoms, PlTerm_term_t(t) for the raw
term_t
, PlTerm_integer(i), PlTerm_float(v), or PlTerm_pointer(p). - Examine uses of
char*
orwchar_t
and replace them bystd::string
orstd::wstring
if appropriate. For example,cout << "Hello " << (char*)A1 << endl
can be replaced bycout << "Hello " << A1.as_string() << endl
. In general,std::string
is safer thanchar*
because the latter can potentially point to freed memory. - Instead of returning
false
from a predicate for failure, you can dothrow PlFail()
. This mechanism is also used by PlCheckFail(rc). Note that throwing an exception is slower than returningfalse
, so performance-critical code should avoid PlCheckFail(rc) if failure is expected to happen often. - You can use the PlCheck_PL(rc) to check the return code from
a function in
SWI-Prolog
and throw aPlFail
exception to short-circuit execution and return failure (false
) to Prolog (or throw aPlException
if there was a Prolog error. PlAtom::handle
has been replaced byPlAtom::C_
, which should be accessed by PlAtom::unwrap().PlTerm::ref
has been replaced byPlTerm::C_
, which should be accessed by PlTerm::unwrap().PlFunctor::functor
has been replaced byPlFunctor::C_
, which should be accessed by PlFunctor::unwrap().- The operator
for unification has been deprecated, replaced by various unify_*() methods (PlTerm::unify_term(t2), PlTerm::unify_atom(a), etc.).=
- The various “cast” operators have been deprecated or
deleted; you should use the various “getter” methods. For
example,
static_cast<char*>(t)
is replaced byt.as_string().c_str()
(and you should prefert.as_striong()
;static_cast<int32_t>(t)
is replaced byt.as_int32_t()
, etc. - It is recommended that you do not use
int
orlong
because of problems porting between Unix and Windows platforms; instead, useint32_t
,int64_t
,uint32_t
,uint64_t
, etc.
2.9 The class PlFail (version 2)
The PlFail
class is used for short-circuiting a function
when failure or an exception occurs and any errors will be handled in
the code generated by the PREDICATE()
macro. See also
section 2.16.2).
For example, this code, using the C API:
PREDICATE(unify_zero, 1) { if ( !PL_unify_integer(A1.unwrap(), 0) ) return false; // could be an error or failure Sprintf("It's zero!\n"); return true; }
can instead be written this way, using the C++ API:
PREDICATE(unify_zero, 1) { PlCheckFail(A1.unify_integer(0)); Sprintf("It's zero!\n"); return true; }
Using throw PlFail()
in performance-critical code
can cause a signficant slowdown. A simple benchmark showed a 15x to 20x
slowdown using throw PlFail()
compared to return
false
(comparing the first code sample above with the second and
third samples; the speed difference seems to have been because in the
second sample, the compiler did a better job of inlining). However, for
most code, this difference will be barely noticeable. And if the code
usually succeeds, there is no significant difference.
There was no significant performance difference between the C++ version and this C version:
static foreign_t unify_zero(term_t a1) { return PL_unify_integer(a1, 0); }
2.9.1 PlCheckFail(), PlCheckEx(), and PlCheck_PL() convenience functions
If one of the C PL_*() functions in SWI-Prolog.h
returns
failure, this can be either a Prolog-style failure (e.g. from
PL_unify() or PL_next_solution()) or an error. If the
failure is due to an error, it's usually best to immediately return to
Prolog - and this can be done with the PlCheckEx() function,
which turns a Prolog error into a C++ PlException
. PlCheckFail()
calls PlCheckEx() and additionally throws PlFail() if the
failure is for Prolog failure.
PlCheckEx() calls PL_exception() to see if there is a
Prolog exception; if so, the Prolog exception is converted to a
PlException
object, which is then thrown. For more details
on the C++ exceptions, see section 2.14.
- void PlCheckFail(bool rc)
- If rc is
false
, throwPlFail
to return control to Prolog with failure. - C_t PlWrap(C_t rc, qid_t qid = 0)
- If rc indicates failure or an error, check for an error and
throw a
PlException
if there was one; otherwise, return the rc. - void PlEx(C_t rc, qid_t qid = 0)
- If rc is “false” (non-zero), throw
PlFail
to return control to Prolog with failure. This is the same as PlCheckFail() except it can also specify aqid_t
query ID.
2.10 Overview of accessing and changing values (version 2)
The SWI-Prolog.h
header provides various functions for
accessing, setting, and unifying terms, atoms and other types.
Typically, these functions return a 0
(false
)
or
1
(true
) value for whether they succeeded or
not. For failure, there might also be an exception created - this can be
tested by calling PL_excpetion(0).
There are three major groups of methods:
- Put (set) a value, corresponding to the PL_put_*() functions.
- Get a value, corresponding to the PL_get_*() and PL_get_*_ex() functions.
- Unify a value, corresponding to the PL_unify_*() and PL_unify_*_ex() functions.
The “put” operations are typically done on an uninstantiated term (see the PlTerm_var() constructor). These are expected to succeed, and typically raise an exception failure (e.g., resource exception) - for details, see the corresponding PL_put_*() functions in Constructing Terms.
For the “get” and “unify” operations, there are three possible failures:
false
return code- unification failure
- exception (value of unexpected type or out of resources)
Each of these is communicated to Prolog by returning false
from the top level; exceptions also set a “global” exception
term (using PL_raise_exception()). The C++ programmer usually
doesn't have to worry about this; instead they can throw PlFail()
for failure or throw PlException()
(or one of PlException
’s
subclasses) and the C++ API will take care of everything.
2.10.1 Converting PlTerm to native C and C++ types (version 2)
These are deprecated and replaced by the various as_*()
methods.
PlTerm
can be converted to the following types:
- PlTerm ::operator term_t(void)
- This cast is used for integration with the C-interface primitives.
- PlTerm ::operator long(void)
- Yields a
long
if thePlTerm
is a Prolog integer or float that can be converted without loss to a long. Throws atype_error
exception otherwise. - PlTerm ::operator int(void)
- Same as for
long
, but might represent fewer bits. - PlTerm ::operator double(void)
- Yields the value as a C double if
PlTerm
represents a Prolog integer or float. - PlTerm ::operator wchar_t *(void)
- PlTerm ::operator char *(void)
- Converts the Prolog argument using PL_get_chars() using the flags
CVT_ALL|CVT_WRITE|BUF_RING
, which implies Prolog atoms and strings are converted to the represented text. All other data is handed to write/1. If the text is static in Prolog, a direct pointer to the string is returned. Otherwise the text is saved in a ring of 16 buffers and must be copied to avoid overwriting. - PlTerm ::operator void *(void)
- Extracts pointer value from a term. The term should have been created by PlTerm::PlTerm(void*).
In addition, the Prolog type (`PL_VARIABLE`,‘PL_ATOM`, ...‘PL_DICT`) can be determined using the type() method. There are also boolean methods that check the type:
- int PlTerm::type()
- See PL_term_type()
- bool PlTerm::is_variable()
- See PL_is_variable()
- bool PlTerm::is_ground()
- See PL_is_ground()
- bool PlTerm::is_atom(S)
- ee PL_is_atom()
- bool PlTerm::is_integer(S)
- ee PL_is_integer()
- bool PlTerm::is_string(S)
- ee PL_is_string()
- bool PlTerm::is_atom_or_string(I)
- s true if either PlTerm::is_atom() or PlTerm::is_string() is true.
- bool PlTerm::is_float(S)
- ee PL_is_float()
- bool PlTerm::is_rational(S)
- ee PL_is_rational()
- bool PlTerm::is_compound(S)
- ee PL_is_compound()
- bool PlTerm::is_callable(S)
- ee PL_is_callable()
- bool PlTerm::is_list(S)
- ee PL_is_list()
- bool PlTerm::is_dict(S)
- ee PL_is_dict()
- bool PlTerm::is_pair(S)
- ee PL_is_pair()
- bool PlTerm::is_atomic(S)
- ee PL_is_atomic()
- bool PlTerm::is_number(S)
- ee PL_is_number()
- bool PlTerm::is_acyclic(S)
- ee PL_is_acyclic()
- bool PlTerm::is_functor(PlFunctor)
- See PL_is_functor()
2.10.2 Unification (version 2)
See also section 2.12.1.
- bool PlTerm::unify_term(PlTerm)
- bool PlTerm::unify_atom(PlAtom)
- bool PlTerm::unify_atom(string)
- bool PlTerm::unify_list_codes(string)
- bool PlTerm::unify_list_chars(string)
- bool PlTerm::unify_integer(int)
- bool PlTerm::unify_float(double)
- bool PlTerm::unify_string(string)
- bool PlTerm::unify_functor(PlFunctor)
- bool PlTerm::unify_pointer(void *)
- bool PlTerm::unify_nil()
- bool PlTerm::unify_blob(PlBlob* blob)
- bool PlTerm::unify_blob(std::unique_ptr<PlBlob>* blob)
- Does a call to PL_unify_blob() and, if successful, calls
std::unique_ptr<PlBlob>::release() to pass
ownership to the Prolog blob; on failure or error, deletes the pointer
(ad calls its destructor). After either success and failure,
*blob==nullptr
. - bool PlTerm::unify_blob(void *blob, size_t len, PL_blob_t *type)
- bool PlTerm::unify_chars(int flags, size_t len, const char *s)
-
A family of unification methods are defined for the various Prolog types and C++ types. Wherever
string
is shown, you can use:char*
whar_t*
std::string
std::wstring
Here is an example:
PREDICATE(hostname, 1) { char buf[256]; if ( gethostname(buf, sizeof buf) == 0 ) return A1.unify_atom(buf); return false; }
An alternative way of writing this would use the PlCheckFail() to raise an exception if the unification fails.
PREDICATE(hostname2, 1) { char buf[256]; PlCheckFail(gethostname(buf, sizeof buf) == 0); PlCheckFail(A1.unify_atom(buf)); return true; }
Of course, in a real program, the failure of
gethostname(buf)sizeof buf should create an error term than
contains information from errno
.
2.10.3 Comparison (version 2)
- int PlTerm::compare(const PlTerm &t2)
- bool PlTerm::operator ==(const PlTerm &)
- bool PlTerm::operator !=(const PlTerm &)
- bool PlTerm::operator <(const PlTerm &)
- bool PlTerm::operator >(const PlTerm &)
- bool PlTerm::operator <=(const PlTerm &)
- bool PlTerm::operator >=(const PlTerm &)
- Compare the instance with t and return the result according to the Prolog defined standard order of terms.
- bool PlTerm::operator ==(long num)
- bool PlTerm::operator !=(long num)
- bool PlTerm::operator <(long num)
- bool PlTerm::operator >(long num)
- bool PlTerm::operator <=(long num)
- bool PlTerm::operator >=(long num)
- Convert
PlTerm
to along
and perform standard C-comparison between the two long integers. IfPlTerm
cannot be converted atype_error
is raised. - bool PlTerm::operator ==(const wchar_t *)
- bool PlTerm::operator ==(const char *)
- bool PlTerm::operator ==(std::wstring)
- bool PlTerm::operator ==(std::string)
- Yields
true
if thePlTerm
is an atom or string representing the same text as the argument,false
if the conversion was successful, but the strings are not equal and antype_error
exception if the conversion failed.
Below are some typical examples. See section 2.10.12.2 for direct manipulation of atoms in their internal representation.
A1 < 0 | Test A1 to hold a Prolog integer or float that can be transformed lossless to an integer less than zero. |
A1 < PlTerm(0) | A1
is before the term‘0’in the‘standard order of terms’.
This means that if A1 represents an atom, this test yields true . |
A1 == PlCompound("a(1)") | Test A1
to represent the term
a(1) . |
A1 == "now" | Test A1 to be an atom or string holding the text “now” . |
2.10.4 Analysing compound terms (version 2)
Compound terms can be viewed as an array of terms with a name and
arity (length). This view is expressed by overloading the
operator.
[]
A type_error
is raised if the argument is not compound
and a
domain_error
if the index is out of range.
In addition, the following functions are defined:
- PlTerm PlTerm::operator[](int arg)
- If the
PlTerm
is a compound term and arg is between 1 and the arity of the term, return a newPlTerm
representing the arg-th argument of the term. IfPlTerm
is not compound, atype_error
is raised. Id arg is out of range, adomain_error
is raised. Please note the counting from 1 which is consistent to Prolog's arg/3 predicate, but inconsistent to C's normal view on an array. See also classPlCompound
. The following example tests x to represent a term with first-argument an atom or string equal tognat
...., if ( x[1] == "gnat" ) ...
- const char * PlTerm::name()
- Return a
const char *
holding the name of the functor of the compound term. Raises atype_error
if the argument is not compound. - size_t PlTerm::arity()
- Returns the arity of the compound term. Raises a
type_error
if the argument is not compound.
2.10.5 Miscellaneous (version 2)
- bool is_null()
t.is_null()
is the same ast.unwrap() == PlTerm::null
- bool not_null()
t.not_null()
is the same ast.unwrap() != PlTerm::null
- bool reset()
t.reset()
is the same ast.unwrap() = PlTerm::null
- bool reset(term_t)
t.reset(x)
is the same ast.unwrap() = x
- int PlTerm::type()
- Yields the actual type of the term as PL_term_type(). Return
values are
PL_VARIABLE
,PL_FLOAT
,PL_INTEGER
,PL_ATOM
,PL_STRING
orPL_TERM
- std::string as_string(PlEncoding enc=EncLocale)
- Returns the string representation of the atom. See PlAtom::as_string() for an explanation of the encodings and caveats about std::string::c_str().
- std::string atomic_as_string(PlEncoding enc=EncLocale)
- As PlTerm::as_string(), but throws an exception if the term isn't atomic (see atomic/1).
- std::string atom_or_string_as_string(PlEncoding enc=EncLocale)
- As PlTerm::as_string(),
but throws an exception if the term isn't an atom or a string.
To avoid very confusing combinations of constructors and therefore
possible undesirable effects a number of subclasses of PlTerm
have been defined that provide constructors for creating special Prolog
terms. These subclasses are defined below.
2.10.6 The class PlTerm_string (version 2)
A SWI-Prolog string represents a byte-string on the global stack. Its
lifetime is the same as for compound terms and other data living on the
global stack. Strings are not only a compound representation of text
that is garbage-collected, but as they can contain 0-bytes, they can be
used to contain arbitrary C-data structures. However, it is generally
preferred to use blobs for storing arbitrary C-data structures (see also PlTerm_pointer(void
*ptr)
).
- PlTerm_string :: PlTerm_string(const wchar_t *text)
- PlTerm_string :: PlTerm_string(const char *text)
- Create a SWI-Prolog string object from a 0-terminated C-string. The text is copied.
- PlTerm_string :: PlTerm_string(const wchar_t *text, size_t len)
- PlTerm_string :: PlTerm_string(const char *text, size_t len)
- Create a SWI-Prolog string object from a C-string with specified length. The text may contain 0-characters and is copied.
2.10.7 The class PlCodeList (version 2)
- PlCodeList :: PlCodeList(const wchar_t *text)
- PlCodeList :: PlCodeList(const char *text)
- Create a Prolog list of ASCII codes from a 0-terminated C-string.
2.10.8 The class PlCharList (version 2)
Character lists are compliant to Prolog's atom_chars/2 predicate.
- PlCharList :: PlCharList(const wchar_t *text)
- PlCharList :: PlCharList(const char *text)
- Create a Prolog list of one-character atoms from a 0-terminated C-string.
2.10.9 The class PlCompound (version 2)
The PlCompound
class is a convenience class for creating
a term from a string; it is similar to (=..)/2
- PlCompound :: PlCompound(const wchar_t *text)
- PlCompound :: PlCompound(const char *text)
- PlCompound :: PlCompound(const std::wstring& text)
- PlCompound :: PlCompound(const std::string& text)
- PlEncoding enc=ENC_INPUT Create a term by parsing (as read/1)
the text. If the text is not valid Prolog syntax,
a
syntax_error
exception is raised. Otherwise a new term-reference holding the parsed text is created. - PlCompound :: PlCompound(const wchar_t *functor, PlTermv args)
- PlCompound :: PlCompound(const char *functor, PlTermv args)
- Create a compound term with the given name from the given vector of
arguments. See
PlTermv
for details. The example below creates the Prolog termhello(world)
.PlCompound("hello", PlTermv("world"))
2.10.10 The class PlTail (version 2)
The class PlTail
is both for analysing and constructing
lists. It is called PlTail
as enumeration-steps make the
term-reference follow the‘tail’of the list.
- PlTail :: PlTail(PlTerm list)
- A
PlTail
is created by making a new term-reference pointing to the same object. AsPlTail
is used to enumerate or build a Prolog list, the initial list term-reference keeps pointing to the head of the list. - int PlTail::append(const PlTerm &element)
- Appends element to the list and make the
PlTail
reference point to the new variable tail. If A is a variable, and this function is called on it using the argument"gnat"
, a list of the form[gnat|B]
is created and thePlTail
object now points to the new variable B.This function returns
true
if the unification succeeded andfalse
otherwise. No exceptions are generated.The example below translates the main() argument vector to Prolog and calls the prolog predicate entry/1 with it.
int main(int argc, char **argv) { PlEngine e(argv[0]); PlTermv av(1); PlTail l(av[0]); for(int i=0; i<argc; i++) PlCheckFail(l.append(argv[i])); PlCheckFail(l.close()); PlQuery q("entry", av); return q.next_solution() ? 0 : 1; }
- int PlTail::close()
- Unifies the term with
and returns the result of the unification.[]
- int PlTail::next(PlTerm &)
- Bind t to the next element of the list
PlTail
and advancePlTail
. Returnstrue
on success andfalse
ifPlTail
represents the empty list. IfPlTail
is neither a list nor the empty list, atype_error
is thrown. The example below prints the elements of a list.PREDICATE(write_list, 1) { PlTail tail(A1); PlTerm e; while(tail.next(e)) cout << e.as_string() << endl; return true; }
2.10.11 The class PlTermv (version 2)
The class PlTermv
represents an array of
term-references. This type is used to pass the arguments to a foreignly
defined predicate, construct compound terms (see
PlTerm::PlTerm(const char *name)PlTermv arguments ) and to create
queries (see PlQuery
).
The only useful member function is the overloading of
,
providing (0-based) access to the elements. Range checking is performed
and raises a []
domain_error
exception.
The constructors for this class are below.
- PlTermv :: PlTermv(int size)
- Create a new array of term-references, all holding variables.
- PlTermv :: PlTermv(int size, term_t t0)
- Convert a C-interface defined term-array into an instance.
- PlTermv :: PlTermv(PlTerm ...)
- Create a vector from 1 to 5 initialising arguments. For example:
load_file(const char *file) { return PlCall("compile", PlTermv(file)); }
If the vector has to contain more than 5 elements, the following construction should be used:
{ PlTermv av(10); av[0] = "hello"; ... }
2.10.12 The class PlAtom - Supporting Prolog constants (version 2)
Both for quick comparison as for quick building of lists of atoms, it is desirable to provide access to Prolog's atom-table, mapping handles to unique string-constants. If the handles of two atoms are different it is guaranteed they represent different text strings.
Suppose we want to test whether a term represents a certain atom, this interface presents a large number of alternatives:
2.10.12.1 Direct comparision to char *
Example:
PREDICATE(test, 1) { if ( A1 == "read" ) ...; }
This writes easily and is the preferred method is performance is not critical and only a few comparisons have to be made. It validates A1 to be a term-reference representing text (atom, string, integer or float) extracts the represented text and uses strcmp() to match the strings.
2.10.12.2 Direct comparision to PlAtom
Example:
static PlAtom ATOM_read("read"); PREDICATE(test, 1) { if ( A1 == ATOM_read ) ...; }
This case raises a type_error
if A1 is not an
atom. Otherwise it extacts the atom-handle and compares it to the
atom-handle of the global PlAtom
object. This approach is
faster and provides more strict type-checking.
2.10.12.3 Extraction of the atom and comparison to PlAtom
Example:
static PlAtom ATOM_read("read"); PREDICATE(test, 1) { PlAtom a1(A1); if ( a1 == ATOM_read ) ...; }
This approach is basically the same as section 2.10.12.2, but in nested if-then-else the extraction of the atom from the term is done only once.
2.10.12.4 Extraction of the atom and comparison to char *
Example:
PREDICATE(test, 1) { PlAtom a1(A1); if ( a1 == "read" ) ...; }
This approach extracts the atom once and for each test extracts the represented string from the atom and compares it. It avoids the need for global atom constructors.
- PlAtom :: PlAtom(atom_t handle)
- Create from C-interface atom handle (
atom_t
). Used internally and for integration with the C-interface. - PlAtom :: PlAtom(const char_t *text)
- PlAtom :: PlAtom(const wchar *text)
- PlAtom :: PlAtom(const std::string& text)
- PlAtom :: PlAtom(const std::wstring& text)
- Create an atom from a string. The text is copied if a new atom is created. See PL_new_atom(), PL_new_atom_wchars(), PL_new_atom_nchars(), PL_new_atom_wchars().
- PlAtom :: PlAtom(const PlTerm &)
- If t represents an atom, the new instance represents this
atom. Otherwise a
type_error
is thrown. - int PlAtom::operator ==(const wchar_t *text)
- int PlAtom::operator ==(const char *text)
- int PlAtom::operator ==(const std::string& text)
- int PlAtom::operator ==(const std::wstring& text)
- Yields
true
if the atom represents text,false
otherwise. Performs a strcmp() or similar for this. - int PlAtom::operator ==(const PlAtom &)
- Compares the two atom-handles, returning
true
orfalse
. Because atoms are unique, there is no need to use strcmp() for this. - int PlAtom::operator !=(const wchar_t *text)
- int PlAtom::operator !=(const char *text)
- int PlAtom::operator !=(const std::string& text)
- int PlAtom::operator !=(const std::wstring& text)
- int PlAtom::operator !=(const PlAtom &)
- The inverse of the
operator.==
- bool is_valid()
- Verifies that the handle is valid. This can be used after calling a function that returns an atom handle, to check that a new atom was created.
- void reset()
- Sets the handle to an invalid valid - a subsequent call to is_null()
will return
true
. - const std::string as_string(PlEncoding enc=EncLocale)
- Returns the string representation of the atom.25If
you wish to return a
char*
from a function, you should not doreturn t.as_string().c_str()
because that will return a pointer into the stack (Gnu C++ or Clang options-Wreturn-stack-address
or-Wreturn-local-addr
) can sometimes catch this, as can the runtime address sanitizer when run withdetect_stack_use_after_return=1
. This does not quote or escape any characters that would need to be escaped if the atom were to be input to the Prolog parser. The possible values forenc
are:EncLatin1
- throws an exception if cannot be represented in ASCII.EncUTF8
EncLocale
- uses the locale to determine the representation.
- const std:wstring as_wstring()
- Returns the string representation of the atom. This does not quote or escape any characters that would need to be escaped if the atom were to be input to the Prolog parser.
- void register_atom()
- See PL_register_atom().
- void unregister_atom()
- See PL_unregister_atom().
- void* blob_data(size_t *len, struct PL_blob_t **type)
- See PL_blob_data().
2.10.13 Classes for the recorded database: PlRecord and PlRecordExternalCopy
The recorded database is has two wrappers, for supporting the internal records and external records.
Currently, the interface to internal records requires that
the programmer explicitly call the dupicate() and erase()
methods - in future, it is intended that this will be done automatically
by a new
PlRecord
class, so that the internal records behave like “smart
pointers” ; in the meantime, the PlRecord
provides a
trivial wrapper around the various recorded database functions.
The class PlRecord
supports the following methods:
- PlRecord(PlTerm)
- Constructor.
- PlRecord(PlRecord)
- Copy and move constructors. Currently these do not do any reference counting. The assignment operator is currently not supported.
- PlRecord()
- Destructor. Currently this does not call PL_erase().
- PlTerm term()
- creates a term from the record, using PL_recorded().
- void erase()
- decrements the reference count of the record and deletes it if the count
goes to zero, using PL_erase(). It is safe to do this multiple
times on the same
PlRecord
object. - PlRecord duplicate()
- increments the reference count of the record, using PL_duplicate_record().
The class PlRecord
provides direct access to the
reference counting aspects of the recorded term (through the duplicate()
and
erase() methods), but does not
connect these with C++'s copy constructor, assignment operator, or
destructor. If the recorded term is encapsulated within an object, then
the containing object can use the duplicate()
and erase() methods in its copy and
move constructors and assignment operators (and the erase()
method in the destructor).26The
copy constructor and assignment use the duplicate()
method; the move constructor and assignment use the duplicate()
method to assign to the destination and the erase()
method on the source; and the destructor uses erase().
Alternatively, the std::shared_ptr
or std::unique_ptr
can be used with the supplied PlrecordDeleter
, which calls
the
erase() method when the shared_ptr
reference count goes to zero or when the std::unique_ptr
goes out of scope.
For example:
std::shared_ptr<PlRecord> r(new PlRecord(t.record()), PlRecordDeleter()); assert(t.unify_term(r->term()));
The class PlRecordExternalCopy
keeps the external
record as an uninterpreted string. It supports the following
methods.
- PlRecordExternalCopy()
- Constructor. Creates a string using Pl_record_external(), copies it into the object, then deletes the reference using PL_erase_external().
- PlTerm term()
- creates a term from the record, using PL_recorded_external()).
2.11 The class PlRegister (version 2)
This class encapsulates PL_register_foreign(). It is defined as a class rather then a function to exploit the C++ global constructor feature. This class provides a constructor to deal with the PREDICATE() way of defining foreign predicates as well as constructors to deal with more conventional foreign predicate definitions.
- PlRegister :: PlRegister(const char *module, const char *name, int arity, foreign_t (f)(term_t t0, int a, control_t ctx))
- Register f as a the implementation of the foreign predicate
<name>/<arity>. This interface uses
the
PL_FA_VARARGS
calling convention, where the argument list of the predicate is passed using an array ofterm_t
objects as returned by PL_new_term_refs(). This interface poses no limits on the arity of the predicate and is faster, especially for a large number of arguments. - PlRegister :: PlRegister(const char *module, const char *name, foreign_t (*f)(PlTerm a0, ...)
- Registers functions for use with the traditional calling conventional,
where each positional argument to the predicate is passed as an argument
to the function f. This can be used to define functions as
predicates similar to what is used in the C-interface:
static foreign_t pl_hello(PlTerm a1) { ... } PlRegister x_hello_1(NULL, "hello", 1, pl_hello);
This construct is currently supported upto 3 arguments.
2.12 The class PlQuery (version 2)
This class encapsulates the call-backs onto Prolog.
- PlQuery :: PlQuery(const char *name, const PlTermv &av)
- Create a query where name defines the name of the predicate
and
av the argument vector. The arity is deduced from av.
The predicate is located in the Prolog module
user
. - PlQuery :: PlQuery(const char *module, const char *name, const PlTermv &av)
- Same, but performs the predicate lookup in the indicated module.
- int PlQuery::next_solution()
- Provide the next solution to the query. Yields
true
if successful andfalse
if there are no (more) solutions. Prolog exceptions are mapped to C++ exceptions. - void PlQuery::cut()
- Discards the query, but does not delete an of the data created by the
query. If there is any pending Prolog exception, it is mapped to a C++
exception and thrown. The call to PlQuery::cut()
is done implicitly by
PlQuery
’s destructor.Below is an example listing the currently defined Prolog modules to the terminal.
PREDICATE(list_modules, 0) { PlTermv av(1); PlQuery q("current_module", av); while( q.next_solution() ) cout << av[0].as_string() << endl; return true; }
In addition to the above, the following functions have been defined.
- int PlCall(const char *predicate, const PlTermv &av)
- Creates a
PlQuery
from the arguments generates the first next_solution() and destroys the query. Returns the result of next_solution() or an exception. - int PlCall(const char *module, const char *predicate, const PlTermv &av)
- Same, locating the predicate in the named module.
- int PlCall(const wchar_t *goal)
- int PlCall(const std::string& goal)
- Translates goal into a term and calls this term as the other PlCall() variations. Especially suitable for simple goals such as making Prolog load a file.
- int PlTerm::call()
- Wrapper for PL_call(), and throws an exception if there's an
error.
t.call()
is essentially the same asPlCall(t)
. - int PlTerm::call(PlModule m)
- Same as PlTerm::call() but specifying the module.
2.12.1 The class PlFrame - Unification and foreign frames (version 2)
As documented with PL_unify(), if a unification call fails and
control isn't made immediately to Prolog, any changes made by
unification must be undone. The functions PL_open_foreign_frame(),
PL_rewind_foreign_frame(), PL_discard_foreign_frame(), and
PL_close_foreign_frame() are encapsulated in the class
PlFrame
, whose destructor calls
PL_close_foreign_frame(). Using this, the example code with PL_unify()
can be written:
PREDICATE(can_unify_ffi, 2) { fid_t fid = PL_open_foreign_frame(); int rval = PL_unify(A1.unwrap(), A2.unwrap()); PL_discard_foreign_frame(fid); return rval; }
/* equivalent to the Prolog code T1 = T2 -> do_one_thing ; do_another_thing */ { PlFrame fr; bool t1_t2_unified = A1.unify_term(A2); if ( ! t1_t2_unified ) fr.rewind(); if ( t1_t2_unified ) do_one_thing(...); else do_another_thing(...); }
The following is C++ version of the code example for PL_open_foreign_frame(). The calls to PL_close_foreign_frame() and the check for PL_exception(0) in the C code aren't needed in the C++ code:
static std::vector<std::string> lookup_unifies = { "item(one, 1)", "item(two, 2)", "item(three, 3)" }; PREDICATE(lookup_unify, 1) { PlFrame fr; for (auto& s : lookup_unifies ) { PlCompound t(s); if ( A1.unify_term(t) ) return true; fr.rewind(); } return false; }
or using this convenience wrapper:
if ( RewindOnFail([t1=A1,t2=A2]()->bool { return t1.unify_term(t2); }) ) do_one_thing(...); else do_another_thing(...);
Note that PlTerm::unify_term()
checks for an error and throws an exception to Prolog; if you wish to
handle exceptions, you must call PL_unify_term(t1. unwrap(),t2.
unwrap())
.
The class PlFrame
provides an interface to discard
unused term-references as well as rewinding unifications (data-backtracking).
Reclaiming unused term-references is automatically performed after a
call to a C++-defined predicate has finished and returns control to
Prolog. In this scenario PlFrame
is rarely of any use. This
class comes into play if the toplevel program is defined in C++ and
calls Prolog multiple times. Setting up arguments to a query requires
term-references and using PlFrame
is the only way to
reclaim them.
Another use of of PlFrame
is when multiple separate
unifications are done - if any of them fails, then the earlier
unifications must be undone before returning to Prolog.
- PlFrame :: PlFrame()
- Creating an instance of this class marks all term-references created afterwards to be valid only in the scope of this instance.
- ~ PlFrame()
- Reclaims all term-references created after constructing the instance. If either close() or discard() have been called, the destructor does nothing.
- void PlFrame::rewind()
- Discards all term-references and global-stack data created as well as undoing all unifications after the instance was created.
- void PlFrame::close()
- Reclaims all term-references created after constructing the instance.
- void PlFrame::discard()
- Same as PlFrame::rewind() + PlFrame::close().
- bool PlRewindOnFail(std::function<bool()> f)
- is a convenience function that does a frame rewind if a function call
fails (typically, failure due to unification failure). It takes a
std::function<bool>()> as an argument, which is
called in the context of a new
PlFrame
.
A typical use for PlFrame
is
the definition of C++ functions that call Prolog and may be called
repeatedly from C++. Consider the definition of assertWord(),
adding a fact to word/1;
the PlFrame
removes the new term av[0]
from
the stack, which prevents the stack from growing each time assertWord()
is called:
void assertWord(const char *word) { PlFrame fr; PlTermv av(1); av[0] = PlCompound("word", PlTermv(word)); PlQuery q("assert", av); PlCheckFail(q.next_solution()); }
The following example uses PlFrame
in the context of a
foreign predicate. The can_unify/2’s
truth-value is the same as for Prolog unification (=/2), but has no side
effects. In Prolog one would use double negation to achieve this:
PREDICATE(can_unify, 2) { PlFrame fr; int rval = (A1=A2); fr.discard(); // or, less efficiently: fr.rewindd(); return rval; }
Here is an example of using PlRewindOnFail(),
where name_to_terms
contains a map from names to terms
(which are made global by using the PL_record() function). The
frame rewind is needed in the situation where the first unify_term()
succeeds and the second one fails.
static const std::map<const std::string, PlRecord> name_to_term = { {"a", PlTerm(...).record(), PlTerm(...).record()}, ... }; PREDICATE(name_to_terms, 3) { A1.must_be_atom_or_string(); const auto it = name_to_term.find(A1.as_string()); return it != name_to_term.cend() && PlRewindOnFail([t1=A2,t2=A3,&it]() { return t1.unify_term(it->second.first.term()) && t2.unify_term(it->second.second.term()); }); }
The equivalent code without using PlRewindOnFail() is:
PREDICATE(name_to_terms, 3) { PlTerm key(A1), term1(A2), term2(A3); const auto it = name_to_term.find(key.as_string()); if ( it == name_to_term.cend() ) return false; if ( !term1.unify_term(it->second.first.term()) ) return false; PlFrame fr; if ( !term2.unify_term(it->second.second.term()) ) { fr.discard(); return false; } return true; }
2.13 The PREDICATE and PREDICATE_NONDET macros (version 2)
The PREDICATE macro is there to make your code look nice, taking care of the interface to the C-defined SWI-Prolog kernel as well as mapping exceptions. Using the macro
PREDICATE(hello, 1)
is the same as writing:27There
are a few more details, such as catching std::bad_alloc
.:
static foreign_t pl_hello__1(PlTermv PL_av); static foreign_t _pl_hello__1(term_t t0, int arity, control_t ctx) { (void)arity; (void)ctx; try { return pl_hello__1(PlTermv(1, t0)); } catch( PlFail& ) { return false; } catch ( PlException& ex ) { return ex.plThrow(); } } static PlRegister _x_hello__1("hello", 1, _pl_hello__1); static foreign_t pl_hello__1(PlTermv PL_av)
The first function converts the parameters passed from the Prolog
kernel to a PlTermv
instance and maps exceptions raised in
the body to simple failure or Prolog exceptions. The PlRegister
global constructor registers the predicate. Finally, the function header
for the implementation is created.
2.13.1 Variations of the PREDICATE macro (version 2)
The PREDICATE() macros have a number of variations that deal with special cases.
- PREDICATE(name, arity)
- Create a predicate with an automatically generated internal name, and
register it with Prolog. The various term arguments are accessible as
A1
,A2
, etc. - PREDICATE0(name)
- This is the same as PREDICATE(name, 0). It avoids a compiler warning
that
PL_av
is not used. - NAMED_PREDICATE(plname, cname, arity)
- This version can be used to create predicates whose name is not a valid
C++ identifier. Here is a ---hypothetical--- example, which unifies the
second argument with a stringified version of the first. The‘cname’is
used to create a name for the functions. The concrete name does not
matter, but must be unique. Typically it is a descriptive name using the
limitations imposed by C++ indentifiers.
NAMED_PREDICATE("#", hash, 2) { return A2.unify_string(A1.as_string()); }
- PREDICATE_NONDET(name, arity)
- Define a non-deterministic Prolog predicate in C++. See also section 2.13.2.
- NAMED_PREDICATE_NONDET(plname, cname, arity)
- Define a non-deterministic Prolog predicate in C++, whose name is not a
valid C++ identifier. See also section
2.13.2.
2.13.2 Non-deterministic predicates (version 2)
Non-deterministic predicates are defined using PREDICATE_NONDET(plname, cname, arity) or NAMED_PREDICATE_NONDET(plname, cname, arity).
A non-deterministic predicate returns a “context” , which
is passed to a subsequent retry. Typically, this context is allocated on
the first call to the predicate and freed when the predicate either
fails or does its last successful return (the context is nullptr
on the first call). To simplify this, a template helper function
PlControl::context_unique_ptr<ContextType>() provides a “smart
pointer” that frees the context on normal return or an exception;
when used with PL_retry_address(), the context's std:unique_ptr<ContextType>::release()
is used to pass the context to Prolog for the next retry, and to prevent
the context from being freed. If the predicate is called with PL_PRUNE
,
the normal return true
will implicitly free the context.
The skeleton for a typical non-deterministic predicate is as follows.
The test for PL_PRUNED
is done first to avoid an unneeded
PlFrame
and also to ensure that A1, A2,
etc. aren't used when they have the value
PlTerm::null
.28This
code could be structured as a switch
statement, but
typically the PL_FIRST_CALL
case falls through to the PL_REDO
case. There are a number of examples of non-deterministic
predicates in the test code test_cpp.cpp
.
struct PredContext { ... }; // The "context" for retries PREDICATE_NONDET(pred, <arity>) { // "ctxt" must be acquired so that the destructor deletes it auto ctxt = handle.context_unique_ptr<PredContext>(); const auto control = handle.foreign_control(); if ( control == PL_PRUNED ) return true; // Can use A1, A2, etc. after we know control != PL_PRUNED if ( ... ) // deterministic result { assert(control == PL_FIRST_CALL); if ( ... ) return true; // Success (and no more solutions) else return fase; } if ( control = PL_FIRST_CALL ) { ctxt.reset(new PredContext(...)); ... } else { assert(control == PL_REDO); } PlFrame fr; for ( ; ctxt->valid(...) ; ctxt->next() ) { if ( ... unify a result ... ) { ctxt->next(); if ( ctxt->valid(...) ) PL_retry_addresss(ctxt.release()); // Succeed with a choice point else return true; // deterministic success } fr.rewind(); } return false; }
2.13.3 Controlling the Prolog destination module (version 2)
With no special precautions, the predicates are defined into the
module from which load_foreign_library/1
was called, or in the module
user
if there is no Prolog context from which to deduce the
module such as while linking the extension statically with the Prolog
kernel.
Alternatively, before loading the SWI-Prolog include file, the macro PROLOG_MODULE may be defined to a string containing the name of the destination module. A module name may only contain alpha-numerical characters (letters, digits, _). See the example below:
#define PROLOG_MODULE "math" #include <SWI-Prolog.h> #include <math.h> PREDICATE(pi, 1) { A1 = M_PI; }
?- math:pi(X). X = 3.14159
2.14 Exceptions (version 2)
See also Prolog exceptions in foreign code.
Prolog exceptions are mapped to C++ exceptions using the class
PlException
(a subclass of PlExceptionBase
to
represent the Prolog exception term. All type-conversion functions of
the interface raise Prolog-compliant exceptions, providing decent
error-handling support at no extra work for the programmer.
For some commonly used exceptions, convenience functions have been
created to exploit both their constructors for easy creation of these
exceptions. If you wish to trap these, you should use
PlException
or PlExceptionBase
and then look
for the appropriate error name. For example, the following code catches
"type_error"
and passes all other exceptions:
try { do_something(...); } catch (const PlException& e) { PlTerm e_t = e.term(); PlAtom ATOM_type_error("type_error"); // e_t.name() == PlAtom("error") && e_t.arity() == 2 if ( e_t[1].name() == ATOM_type_error) ) { ... // expected type and culprit are \exam{e_t[1][1]} and \exam{e_t[1][2]} } else throw; }
The convenience functions are PlTypeEror() and PlDomainError(),
PlDomainError(), PlInstantiationError(), PlExistenceError(),
PlUninstantiationError(), PlRepresentationError(),
PlPermissionError(), PlResourceError(), PlUnknownError().
There is also a PlGeneralError(inside) that creates error(inside,_)
terms and is used by the other error convience functions.
To throw an exception, create an instance of PlException
and use throw
. This is intercepted by the PREDICATE macro
and turned into a Prolog exception. See section
2.16.2.
char *data = "users"; throw PlException(PlCompound("no_database", PlTerm(data)));
2.14.1 The class PlException (version 2)
This subclass of PlExceptionBase
is used to represent
exceptions. Currently defined methods are:
- PlException :: PlException(const PlTerm &)
- Create an exception from a general Prolog term. This provides the interface for throwing any Prolog terms as an exception.
- std::string as_string()
- The exception is translated into a message as produced by
print_message/2.
The character data is stored in a ring. Example:
...; try { PlCall("consult(load)"); } catch ( PlException& ex ) { cerr << ex.as_string() << endl; }
- int plThrow()
- Used in the PREDICATE() wrapper
to pass the exception to Prolog. See
PL_raise_exeption().
2.14.1.1 The function PlTypeError (version 2)
A type error expresses that a term does not satisfy the expected basic Prolog type.
- PlTypeError :: PlTypeError(const std::string& expected, const PlTerm &actual)
- Creates an ISO standard Prolog error term expressing the expected type and actual term that does not satisfy this type.
2.14.1.2 The function PlDomainError (version 2)
A domain error expresses that a term satisfies the basic
Prolog type expected, but is unacceptable to the restricted domain
expected by some operation. For example, the standard Prolog open/3
call expect an io_mode
(read, write, append, ...). If an
integer is provided, this is a type error, if an atom other
than one of the defined io-modes is provided it is a domain error.
- PlDomainError :: PlDomainError(const std::string& expected, const PlTerm &actual)
- Creates an ISO standard Prolog error term expressing a the expected domain and the actual term found.
2.15 Embedded applications (version 2)
Most of the above assumes Prolog is‘in charge’of the
application and C++ is used to add functionality to Prolog, either for
accessing external resources or for performance reasons. In some
applications, there is a main-program and we want to use Prolog
as a
logic server. For these applications, the class
PlEngine
has been defined.
Only a single instance of this class can exist in a process. When used in a multi-threading application, only one thread at a time may have a running query on this engine. Applications should ensure this using proper locking techniques.29For Unix, there is a multi-threaded version of SWI-Prolog. In this version each thread can create and destroy a thread-engine. There is currently no C++ interface defined to access this functionality, though ---of course--- you can use the C-functions.
- PlEngine :: PlEngine(int argc, char **argv)
- Initialises the Prolog engine. The application should make sure to pass
argv[0]
from its main function, which is needed in the Unix version to find the running executable. See PL_initialise() for details. - PlEngine :: PlEngine(char *argv0)
- Simple constructure using the main constructor with the specified
argument for
argv[0]
. - ~ PlEngine()
- Calls PL_cleanup() to destroy all data created by the Prolog engine.
Section 1.4.11 has a simple example using this class.
2.16 Considerations (version 2)
2.16.1 The C++ versus the C interface (version 2)
Not all functionality of the C-interface is provided, but as
PlTerm
and term_t
are essentially the same
thing with type-conversion between the two (using the unwrap()
method), this interface can be freely mixed with the functions defined
for plain C. For checking return codes from C functions, it is
recommended to use PlCheckFail()
or PlCheck_PL().
Using this interface rather than the plain C-interface requires a
little more resources. More term-references are wasted (but reclaimed on
return to Prolog or using PlFrame
). Use of some
intermediate types (functor_t
etc.) is not supported in the
current interface, causing more hash-table lookups. This could be fixed,
at the price of slighly complicating the interface.
Global terms and atoms need to be handled slightly differently in C++ than in C - see section 2.16.3
2.16.2 Notes on exceptions
Exceptions are normal Prolog terms that are handled specially by the
PREDICATE macro when they are used by a C++ throw
, and
converted into Prolog exceptions. The exception term may not be unbound;
that is, throw(_) must raise an error. The C++ code and underlying C
code do not explicitly check for the term being a variable, and
behaviour of raising an exception that is an unbound term is undefined,
including the possibility of causing a crash or corrupting data.
The Prolog exception term error(Formal, _) is special. If the 2nd
argument of error/2
is undefined, and the term is thrown, the system finds the catcher (if
any), and calls the hooks in library(prolog_stack) to add the context
and stack trace information when appropriate. That is, throw PlDomainError(Domain,Culprit)
ends up doing the same thing as calling
PL_domain_error(Domain,Culprit)
which internally
calls
PL_raise_exception() and returns control back to Prolog.
The VM handling of calling to C finds the FALSE
return
code, checks for the pending exception and propagates the exception into
the Prolog environment. As the term references (term_t
)
used to create the exception are lost while returning from the foreign
function we need some way to protect them. That is done using a global term_t
handle that is allocated at the epoch of Prolog.
PL_raise_exception() sets this to the term using PL_put_term().
PL_exception(0) returns the global exception term_t
if it is bound and 0 otherwise.
Special care needs to be taken with data backtracking using
PL_discard_foreign_frame() or PL_close_query() because
that will invalidate the exception term. So, between raising the
exception and returning control back to Prolog we must make sure not to
do anything that invalidates the exception term. If you suspect
something like that to happen, use the debugger with a breakpoint on
__do_undo__LD() defined in pl-wam.c
.
In order to always preserve Prolog exceptions and return as quickly as possible to Prolog on an exception, some of the C++ classes can throw an exception in their destructor. This is theoretically a dangerous thing to do, and can lead to a crash or program termination if the destructor is invoked as part of handling another exception.
2.16.3 Global terms, atoms, and functors
Sometimes it is convenient to put constant terms and atoms as global
variables in a file (with a static
qualifier), so that they
are only created (and looked up) cone. This is fine for atoms and
functors, which can be created by something like this:
static PlAtom ATOM_foo("foo"); static PlFunctor FUNCTOR_ff_2("ff", 2);
C++ makes no guarantees about the order of creating global variables
across “translation units” (that is, individual C++ files),
but the Prolog runtime ensures that the necessary initialization has
been done to allow PlAtom
and PlFunctor
objects to be created. However, to be safe, it is best to put such
global variables
inside functions - C++ will initialize them on their firstuse.
Global Terms need a bit of care. For one thing, terms are ephemeral,
so it is wrong to have a PlTerm
static variable - instead,
a
PlRecord
must be used, which will provide a fresh copy of
the term using PlRecord::term(). There is no guarantee that the
Prolog runtime has initialized everything needed for creating entries in
the recorded database (see
Recorded
database). Therefore, global recorded terms must be wrapped inside a
function. C++ will call the constructor upon first use. For example:
static PlTerm term_foo_bar() { static PlRecord r(PlCompound("foo", PlTermv(PlTerm_atom("bar"))).record()); return r.term(); }
2.16.4 Atom map utilities
The include file SWI-cpp2-atommap.h
contains a templated
class
AtomMap
for mapping atoms to atoms or terms. The typical
use case is for when it is desired to open a database or stream and,
instead of passing around the blob, an atom can be used to identify the
blob.
The keys in the map must be standard Prolog atoms and not blobs - the code depends on the fact that an atom has a unique ID.
The AtomMap
is thread-safe (it contains a mutex). It
also takes care of reference counts for both the key and the value. Here
is a typical use case:
static AtomMap<PlAtom, PlAtom> map_atom_my_blob("alias", "my_blob"); // look up an entry: auto value = map_atom_my_blob(A1.as_atom()); PlCheckFail(value.not_null()); // insert an entry: map_atom_my_blob.insert(A1.as_atom(), A2.as_atom()); // remove an entry: map_atom_my_blob.erase(A1.as_atom());
The constructor and methods are as follows:
- template<ValueType, StoredValueType> AtomMap::AtomMap(const std::string& insert_op)
- const std::string& insert_type Construct an
AtomMap
. The ValueType and StoredValueType specify what type you wish for the value. Currently, two value types are supported:PlAtom
- the StoredValueType should bePlAtom
.PlTerm
- the StoredValueType shoud bePlRecord
(because the term needs to be put on the global stack).
- insert PlAtom key, ValueType value(I)
- nserts a new value; raises a
permission_error
if the value is already in the map, unless the value is identical to the value in the map. The insert() method converts the value to theStoredValueType
. The insertion code takes care of atom reference counts. - ValueType find(PlAtom key)
- Look up an entry. Success/failure can be determined by using ValueType::is_null()
or ValueType::not_null(). The stored value is converted from
StoredValueType
toValueType
. - erase PlAtom(r)
- emoves the entry from the map. If there was no entry in the map with
that key, this is a no-op. The erasure code takes care of atom reference
counts.
2.16.5 Static linking and embedding (version 2)
The mechanisms outlined in this document can be used for static linking with the SWI-Prolog kernel using swipl-ld(1). In general the C++ linker should be used to deal with the C++ runtime libraries and global constructors.
2.16.6 Status and compiler versions (version 2)
The current interface can be entirely defined in the .h
file using inlined code. This approach has a few advantages: as no C++
code is in the Prolog kernel, different C++ compilers with different
name-mangling schemas can cooperate smoothly. However, inlining
everything can lead to code bloat, so the larger functions and methods
have been put into a .cpp
file that can be either compiled
separately (by the same compiler as used by the foreign predicate) or
inlined as if it were part of the .h
file.
Also, changes to the header file have no consequences to binary compatibility with the SWI-Prolog kernel. This makes it possible to have different versions of the header file with few compatibility consequences.
As of 2023-04, some details remain to be decided, mostly to do with
encodings. A few methods have a PlEncoding
optional
parameter (e.g., PlTerm::as_string()),
but this hasn't yet been extended to all methods that take or return a
string. Also, the details of how the default encoding is set have not
yet been decided.
As of 2023-04, the various error convenience classes do not fully
match what the equivalent C functions do. That is, throw PlInstantiationError(A1)
does not result in the same context and traceback information that would
happen from
Plx_instantiation_error(A1. unwrap()); throw PlFail()
.
See
section 2.16.2.
The Plx_*() wrappers may require small adjustments in whether their
return values require [[nodiscard]]
or whether their return
values should be treated as an error.
The implementation of PlException
is likely to change
somewhat in the future. Currently, to ensure that the exception term has
a sufficient lifetime, it is serialized using PL_record_external().
In future, if this proves unnecessary, the term will be stored as-is.
The API will not change if this implementation detail changes.
2.17 Conclusions (version 2)
In this document, we presented a high-level interface to Prolog exploiting automatic type-conversion and exception-handling defined in C++.
Programming using this interface is much more natural and requires only little extra resources in terms of time and memory.
Especially the smooth integration between C++ and Prolog exceptions reduce the coding effort for type checking and reporting in foreign predicates.
Index
- ?
- add/3
- 1.3.2 2.6.2
- add_num/3
- 2.2
- arg/3
- 1.4.5 2.10.4
- as_string()
- as_wstring()
- assert
- 1.8.1 2.12.1
- at_halt/1
- 2.5.7.6
- atom_chars/2
- 1.2 1.4.9 2.5.6 2.10.8
- atom_or_string_as_string()
- atomic/1
- 2.10.5
- atomic_as_string()
- average/3
- 1.3.3 2.2 2.6.3
- between/3
- 2.2
- blob_data()
- call()
- can_unify/2
- 2.2 2.12.1
- cappend/3
- 2.2
- close_my_blob/1
- 2.5.7.6 2.5.7.6 2.5.7.6
- create_my_blob/2
- 2.5.7.6
- duplicate()
- entry/1
- 1.4.11 2.10.10
- eq1/1
- 2.2
- eq2/2
- 2.2
- eq3/2
- 2.2
- erase()
- error/2
- 2.16.2
- fail/0
- 2.4
- find()
- functor/3
- 2.2
- happy/1
- 2.2
- hello/1
- 1.3.1 2.6.1
- int_info/2
- 2.2
- is_null()
- is_valid()
- likes/2
- 2.2
- load_foreign_library/1
- 1.9.2 2.13.3
- my_blob_properties/2
- 2.5.7.6
- name_arity()
- name_arity/3
- 2.2
- nify_term()
- not_null()
- open/3
- 1.10.3 2.14.1.2
- operator!=()
- operator<()
- operator<=()
- operator==()
- operator>()
- operator>=()
- print_message/2
- 1.10.1 2.14.1
- qsave_program/[1,2]
- 2.5.7.6
- range_cpp/3
- 2.2
- read/1
- 1.4.10 2.10.9
- register_atom()
- reset()
- reset_term_refs()
- size_tindex()
- square_roots/2
- 2.2
- term()
- throw/1
- 2.1 2.4
- unifiable/3
- 2.2
- unregister_atom()
- use_foreign_library/1
- 2.4
- word/1
- 1.8.1 2.12.1
- write()
- write/1
- 1.3.1 1.4.2 2.6.1 2.10.1
- write_list/1
- 2.2
- NAMED_PREDICATE()
- NAMED_PREDICATE_NONDET()
- P
- PlAtom
- 1.4.3 1.6
- PlAtom!=()
- PlAtom()
- PlAtom==()
- PlAtomkey,ValueTypevalue()
- PlBlob::acquire()
- PlBlob::compare_fields()
- PlBlob::write_fields()
- PlBlob::PlBlob::load()
- PlBlob::PlBlob::pre_delete()
- PlBlob::PlBlob::save()
- PlCall()
- PlCompound
- 1.4.5
- PlCheckFail()
- PlDomainError
- 1.10
- PlEngine
- 1.11
- PlEx()
- PlException
- 1.2 1.2 1.2 1.2 1.10 1.10 1.10 1.10.1 1.10.1 1.10.1
- PlFrame
- 1.8.1 1.8.1 1.8.1 1.8.1 1.8.1 1.12.1
- PlFrame::close()
- PlFrame::discard()
- PlFrame::rewind()
- PlQuery
- 1.3.3 1.5 1.8
- PlQuery::cut()
- PlQuery::next_solution()
- PlRecord()
- PlRegister
- 1.9
- PlRecord()
- PlRecordExternalCopy()
- PREDICATE()
- PREDICATE0()
- PREDICATE_NONDET()
- PlRewindOnFail()
- PlStream::release()
- PlTail
- 1.4.11 1.4.11 1.4.11 1.4.11 1.4.11 1.4.11 1.4.11 1.4.11 1.4.11 1.4.11
- PlTail::append()
- PlTail::close()
- PlTail::next()
- PlTerm
- 1.2 1.2 1.2 1.2 1.2 1.2 1.2 1.3.1 1.3.1 1.3.2 1.3.2 1.4 1.4.1 1.4.2 1.4.2 1.4.3 1.4.4 1.4.4 1.4.4 1.4.5 1.4.5 1.4.5 1.4.6 1.10 1.10.1 1.12.1
- PlTerm!=()
- PlTerm::arity()
- PlTerm::as_atom()
- PlTerm::as_bool()
- PlTerm::as_double()
- PlTerm::as_float()
- PlTerm::as_int()
- PlTerm::as_int32_t()
- PlTerm::as_int64_t()
- PlTerm::as_long()
- PlTerm::as_nil()
- PlTerm::as_pointer()
- PlTerm::as_size_t()
- PlTerm::as_string()
- PlTerm::as_uint()
- PlTerm::as_uint32_t()
- PlTerm::as_uint64_t()
- PlTerm::as_ulong()
- PlTerm::as_wstring()
- PlTerm::call()
- PlTerm::compare()
- PlTerm::copy_term_ref()
- PlTerm::eq_if_atom()
- PlTerm::get_arg()
- PlTerm::get_atom()
- PlTerm::get_atom_ex()
- PlTerm::get_atom_nchars()
- PlTerm::get_attr()
- PlTerm::get_blob()
- PlTerm::get_bool()
- PlTerm::get_bool_ex()
- PlTerm::get_char_ex()
- PlTerm::get_chars()
- PlTerm::get_compound_name_arity()
- PlTerm::get_dict_key()
- PlTerm::get_file_name()
- PlTerm::get_float()
- PlTerm::get_float_ex()
- PlTerm::get_functor()
- PlTerm::get_head()
- PlTerm::get_int64_ex()
- PlTerm::get_integer()
- PlTerm::get_integer_ex()
- PlTerm::get_intptr()
- PlTerm::get_intptr_ex()
- PlTerm::get_list()
- PlTerm::get_list_chars()
- PlTerm::get_list_ex()
- PlTerm::get_list_nchars()
- PlTerm::get_long()
- PlTerm::get_long_ex()
- PlTerm::get_module()
- PlTerm::get_name_arity()
- PlTerm::get_nchars()
- PlTerm::get_nil()
- PlTerm::get_nil_ex()
- PlTerm::get_pointer()
- PlTerm::get_pointer_ex()
- PlTerm::get_size_ex()
- PlTerm::get_tail()
- PlTerm::get_uint64_ex()
- PlTerm::get_wchars()
- PlTerm::integer()
- PlTerm::is_acyclic()
- PlTerm::is_atom()
- PlTerm::is_atom_or_string()
- PlTerm::is_atomic()
- PlTerm::is_attvar()
- PlTerm::is_blob()
- PlTerm::is_callable()
- PlTerm::is_compound()
- PlTerm::is_dict()
- PlTerm::is_float()
- PlTerm::is_functor()
- PlTerm::is_ground()
- PlTerm::is_integer()
- PlTerm::is_list()
- PlTerm::is_number()
- PlTerm::is_pair()
- PlTerm::is_rational()
- PlTerm::is_string()
- PlTerm::is_variable()
- PlTerm::must_be_acyclic()
- PlTerm::must_be_atom()
- PlTerm::must_be_atom_or_string()
- PlTerm::must_be_atomic()
- PlTerm::must_be_attvar()
- PlTerm::must_be_callable()
- PlTerm::must_be_compound()
- PlTerm::must_be_dict()
- PlTerm::must_be_float()
- PlTerm::must_be_ground()
- PlTerm::must_be_integer()
- PlTerm::must_be_list()
- PlTerm::must_be_number()
- PlTerm::must_be_pair()
- PlTerm::must_be_rational()
- PlTerm::must_be_string()
- PlTerm::must_be_variable()
- PlTerm::name()
- PlTerm::put_atom()
- PlTerm::put_atom_chars()
- PlTerm::put_atom_nchars()
- PlTerm::put_blob()
- PlTerm::put_bool()
- PlTerm::put_chars()
- PlTerm::put_float()
- PlTerm::put_functor()
- PlTerm::put_integer()
- PlTerm::put_list()
- PlTerm::put_list_chars()
- PlTerm::put_list_codes()
- PlTerm::put_list_nchars()
- PlTerm::put_list_ncodes()
- PlTerm::put_nil()
- PlTerm::put_pointer()
- PlTerm::put_string_chars()
- PlTerm::put_string_nchars()
- PlTerm::put_term()
- PlTerm::put_variable()
- PlTerm::record()
- PlTerm::type()
- PlTerm::unify_atom()
- PlTerm::unify_blob()
- PlTerm::unify_bool()
- PlTerm::unify_bool_ex()
- PlTerm::unify_chars()
- PlTerm::unify_float()
- PlTerm::unify_functor()
- PlTerm::unify_integer()
- PlTerm::unify_list()
- PlTerm::unify_list_chars()
- PlTerm::unify_list_codes()
- PlTerm::unify_list_ex()
- PlTerm::unify_nil()
- PlTerm::unify_nil_ex()
- PlTerm::unify_pointer()
- PlTerm::unify_string()
- PlTerm::unify_term()
- PlTerm<()
- PlTerm<=()
- PlTerm=()
- PlTerm==()
- PlTerm>()
- PlTerm>=()
- PlTerm[]()
- PlTermv
- 1.2 1.4.10 1.5 1.9
- PlTypeEror
- 1.10 1.10.1
- PlTerm::get_file_nameW()
- PlWrap()
- T
- cppThrow()
- plThrow()
- V
- template<ValueType,StoredValueType>AtomMap::AtomMap()