- 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
- Introduction (version 2)
- The life of a PREDICATE (version 2)
- Overview (version 2)
- Examples (version 2)
- Rational for changes from version 1 (version 2)
- Porting from version 1 to version 2
- The class PlFail (version 2)
- The class PlTerm (version 2)
- The class PlTermv (version 2)
- The class PlAtom - Supporting Prolog constants (version 2)
- Unification and foreign frames (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
.
The overall structure of the API has been retained - that is, it is a
thin layer on top of the interface provided by
SWI-Prolog.h
. Based on experience with the API, most of the
conversion 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 in []
PlTerm t=...; f(t[0])
if f
is overloaded to accept a term_t
or char*
.
More specifically:
- The constructor PlTerm() is not available - instead, you should use the appropriate subclass' constructor (PlTerm_var(), PlTerm_atom(a), PlTerm_term_t(t), PlTerm_integer(i), PlTerm_int64(i), PlTerm_uint64(i), PlTerm_size_t(i), PlTerm_float(v), or PlTerm_pointer(p)).
- Instead of returning
false
from a predicate to indicate failure, you can usethrow PlFail()
. The convenience function PlCheck(rc) can be used to throwPlFail()
, if afalse
is returned from a function inSWI-Prolog.h
- The "cast" operators (e.g.,
(char*)t
,(int64_t)t
) have been deprecated, replaced by "getters" (e.g.,t.as_string()
,t.as_int64_t()
).3The form(char*)t
is a C-style cast; C++'s preferred form is more verbose:static_cast<char*>(t)
. - The overloaded assignment operator for unification is deprecated; replaced by unify_term(), unify_atom(), etc., and the helper PlCheck().
- Methods that return
char*
have been replaced by methods that returnstd::string
to ensure that lifetime issues don't cause subtle bugs.4If 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 will need to change your interface to return astd::string
and apply thec_str()
method to it. These errors can sometimes be caught by specifying the Gnu C++ or Clang options-Wreturn-stack-address
or-Wreturn-local-addr
- Clang seems to do a better analysis. - Type-checking methods have been added: type(), is_variable(), 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
. std::string
andstd::wstring
are now supported in most places wherechar*
orwchar_t*
are allowed.- 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_
.5This is done by subclassing fromWrapped<term_t>
,Wrapped<atom_t>
, etc., which define the fieldC_
, standard constructors, the methods is_null(), not_null(), reset(), and reset(v), plus the constantnull
. - A convenience class
PlForeignContextPtr<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().
More details are given in section 2.6 and section 2.7.
2.2 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 programmable type-conversion (casting) and overloading, native data-types can be translated automatically 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.
More information on the SWI-Prolog native types is given in Interface Data Types.
It would be tempting to use C++ 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 easily 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.2.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.3 The life of a PREDICATE (version 2)
A foreign predicate is defined using the PREDICATE() macro.6Plus
a few variations on this, such as PREDICATE_NONDET(), NAMED_PREDICATE(),
and NAMED_PREDICATE_NONDET().
This defines an internal name for the function, registers it with the
SWI-Prolog runtime (where it will be picked up by the use_foreign_library/1
directive), and defines the names A1
, A2
, etc.
for the arguments.7You can define
your own names for the arguments, for example: auto x=A1, y=A2,
result=A3;
. If a non-deterministic predicate is
being defined, an additional parameter handle
is defined
(of type
control_t
).
The foreign predicate returns a value of true
or false
to indicate whether it succeeded or failed.8Non-deterministic
predicates can also return a "retry" value. If a predicate
fails, it could be simple failure (the equivalent of calling the builtin fail/0)
or an error (the equivalent of calling throw/1).
When an exception is raised, it is important that a return be made to
the calling environment as soon as possible. In C code, this requires
checking every call to check for failure, which can become cumbersome.
C++ has exceptions, so instead the code can wrap calls to PL_*()
functions with
PlCheck(), which will do throw PlFail()
to exit from
the top level of the foreign predicate, and handle the failure or
exception appropriately.
The following three snippets do the same thing (for implementing the equivalent of =/2):
PREDICATE(eq, 2) { PlCheck(A1.unify_term(A2)); return true; }
PREDICATE(eq, 2) { return A1.unify_term(A2); }
PREDICATE(eq, 2) { PlCheck(PL_unify(A1.C_, A2.C_)); return true; }
2.4 Overview (version 2)
The most 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
.
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
).
2.4.1 Design philosophy of the classes
See also section 2.4.3.
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.16.)
The various 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
). You can check whether the object is "fully created" by
using the verify() method - it will throw an exception if the
object is null
.
However, 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.
To help avoid programming errors, most 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 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). Sometimes, it's desirable to create
them "lazily", such as:
static PlAtom foo(PlAtom::null}; ... if ( foo.is_null() ) foo = PlAtom("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.9.1. Note that the
default constructor is not public; to create a "variable" term, you
should use the subclass constructor PlTerm_var().
2.4.2 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.9.3.The subclass constructors are as follows. If a constructor fails (e.g., out of memory), a
PlException
is thrown.- PlTerm_atom
- Subclass of
PlTerm
with constructors for building a term that contains an atom. - PlTerm_var
- Subclass of
PlTerm
with constructors for building a term that contains an uninstantiated variable. Typically this term is then unified with another object. - PlTerm_term_t
- Subclass of
PlTerm
with constructors for building a term from a Cterm_t
. - PlTerm_integer
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog integer from along
.9PL_put_integer() takes along
argument. - PlTerm_int64
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog integer from aint64_t
. - PlTerm_uint64
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog integer from auint64_t
. - PlTerm_size_t
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog integer from asize_t
. - PlTerm_float
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog float. - PlTerm_pointer
- Subclass of
PlTerm
with constructors for building a term that contains a raw pointer. This is mainly for backwards compatibility; new code should use blobs. - PlTerm_string
- Subclass of
PlTerm
with constructors for building a term that contains a Prolog string object. - PlTerm_list_codes
- Subclass of
PlTerm
with constructors for building Prolog lists of character integer values. - PlTerm_chars
- Subclass of
PlTerm
with constructors for building Prolog lists of one-character atoms (as atom_chars/2). - PlTerm_tail
- SubClass of
PlTerm
for building and analysing Prolog lists.
Additional subclasses of
PlTerm
are:- PlCompound
- Subclass of
PlTerm
with constructors for building compound terms. If there is a single string argument, then PL_chars_to_term() or PL_wchars_to_term() is used to parse the string and create the term. If the constructor has two arguments, the first is name of a functor and the second is 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. - PlException
- Subclass of
PlTerm
representing a Prolog exception. Provides methods for the Prolog communication and mapping to human-readable text representation. - PlTypeError
- Subclass of
PlException
for representing a Prologtype_error
exception. - PlDomainError
- Subclass of
PlException
for representing a Prologdomain_error
exception. - PlExistenceError
- Subclass of
PlException
for representing a Prologexistence_error
exception. - PlPermissionError
- Subclass of
PlException
for representing a Prologpermission_error
exception.
- PlAtom
- Allow for manipulating atoms (
atom_t
) in their internal Prolog representation for fast comparison. (For more details onatom_t
, see Interface Data Types). - PlFunctor
- A wrapper for
functor_t
, which maps to the internal representation of a name/arity pair. - PlPredicate
- A wrapper for
predicate_t
, which maps to the internal representation of a Prolog predicate. - PlModule
- A wrapper for
module_t
, which maps to the internal representation of a Prolog module. - PlQuery
- Represents opening and enumerating the solutions to a Prolog query.
- PlFail
- Can be thrown to short-circuit processing and return failure to Prolog.
Performance-critical code should use
return false
instead if failure is expected. - PlFrame
- This utility-class can be used to discard unused term-references as well as to do‘data-backtracking’.
- PlEngine
- This class is used in embedded applications (applications where the main control is held in C++). It provides creation and destruction of the Prolog environment.
- PlRegister
- The encapsulation of PL_register_foreign() is defined to be able to use C++ global constructors for registering foreign predicates.
The required C++ function header and registration of a predicate is arranged through a macro called PREDICATE().
2.4.3 Naming conventions, utility functions and methods (version 2)
See also section 2.4.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
)
all contain a field C_
that contains the wrapped value (functor_t
, atom_t
, term_t
respectively).
The wrapper classes (which subclass WrappedC< ...
)
all define the following methods and constants:
- default constructor (sets the wrapped value to
null
) - 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_put_atom(t.C_,a.C_))
.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 valueverify()
- if the wrapped value (C_
) isnull
, throw a PlFail() exception. Typically, this check is done after an allocation function such as Plnew_term_ref() returns a null value, so the PlFail() is turned into a a resource error. However, if there is no pending exception, this results in simple failure (see section 2.18.2).- The
bool
operator is turned off - you should use not_null() instead.10The reason: abool
conversion causes ambiguity withPlAtom(PlTterm)
andPlAtom(atom_t)
.
The C_
field 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.C_
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; PlCheck(PL_scan_options(options, 0, "mypred_options", mypred_options, "ed, &length, &callback.C_)); 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
, PlCheck() is a convenience
function that checks the return code and throws a PlFail
exception on failure. The
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. Where possible, the
"getters" have the same name as the underlying type; but this isn't
possible for types such as int
or float
, so
for these the name is prepended with "as_".
"Getters" for integers have an additionnal problem, in that C++
doesn't define the sizes of int
and long
, nor
for
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++, 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 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.5.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;11The
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.
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.5.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()); }
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.5.3 Average of solutions (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 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.6 Rational for changes from version 1 (version 2)
2.6.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 " << A1.as_string() << endl; return true; } PREDICATE(add, 3) { return A3 = (long)A1 + (long)A2; }
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 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 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");
- 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 ctypebool. 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 a
bool
and they can be wrapped inside a PlCheck() to raise an exception on unification failure.
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, some 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.6.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. The
buffer stack is abstracted into PlStringBuffers
, 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.12As of 2022-11, this
had only been partially implemented. Some of the details
for this - such as the default encoding - may change slightly in the
future.
2.7 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.
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 " << A1.as_string().c_str()() << 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 PlCheck(rc). Note that throwing an exception is significantly slower than returningfalse
, so performance-critical code should avoid PlCheck(rc). - You can use the PlCheck(rc) to check the return code from a
function in
SWI-Prolog
and throw a PlFail() exception to short-circuit execution and return failure (false
) to Prolog. PlAtom::handle
has been replaced byPlAtom::C_
.PlTerm::ref
has been replaced byPlAtom::C_
.PlFunctor::functor
has been replaced byPlAtom::C_
.- The operator
for unification has been deprecated, replaced by various=
unify_XXX
‘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()
;static_cast<int32_t>(t)
is replaced byt.as_int32_t()
. - 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.8 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.18.2).
For example, this code:
PREDICATE(unify_zero, 1) { if ( !PL_unify_integer(A1.C_, 0) ) return false; return true; }
can instead be written this way:
void PREDICATE(unify_zero, 1) { if ( !PL_unify_integer(A1.C_, 0) ) throw PlFail(); return true; }
or:
PREDICATE(unify_zero, 1) { PlCheck(PL_unify_integer(t.C_, 0)); return true; }
or:
PREDICATE(unify_zero, 1) { PlCheck(A1.unify_integer(0)); return true; }
or:
PREDICATE(unify_zero, 1) { return A1.unify_integer(0); }
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.
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.8.1 PlCheck() convenience function
In general, wherever there is a method that wraps a C "PL_" function, PlCheck() can be used to return failure to Prolog from the "PL_" function.
The code for PlCheck() is very simple - it checks the return
code and throws PlFail
if the return code isn't "true". If
the return code is from a Prolog function (that is, a function starting
with "PL_"), the return code can be "false" either because of failure or
because an exception happened. If the cause is an exception, then the
only sensible thing is to return to Prolog immediately; throwing PlFail
will do this. See also section 2.18.2.
2.9 The class PlTerm (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.
2.9.1 Constructors (version 2)
The 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 an atom; PlTerm_string
creates a Prolog string). All of the constructors are "explicit" because
implicit creation of PlTerm
objects can lead to subtle and
difficult to debug errors.
- PlTerm :: PlTerm()
- Creates a new initialised "null" term (holding a Prolog variable).
- PlTerm_term_t :: PlTerm_term_t(term_t t)
- Converts between the C-interface and the C++ interface by turning the
term-reference into an instance of
PlTerm
. Note that, being a lightweight class, this is a no-op at the machine-level! - PlTerm_atom :: PlTerm_atom(const char *text)
- Creates a term-references holding a Prolog atom representing text.
- PlTerm_atom :: PlTerm_atom(const wchar_t *text)
- Creates a term-references holding a Prolog atom representing text.
- PlTerm_atom :: PlTerm_atom(const PlAtom &atom)
- Creates a term-references holding a Prolog atom from an atom-handle.
- PlTerm_int :: PlTerm_int(long n)
- Creates a term-references holding a Prolog integer representing n.
- PlTerm_int :: PlTerm_int(int64_t n)
- Creates a term-references holding a Prolog integer representing n (up to 64 bits signed).
- PlTerm_int :: PlTerm_int(uint64_t n)
- Creates a term-references holding a Prolog integer representing n (up to 64 bits unsigned).
- PlTerm_float :: PlTerm_float(double f)
- Creates a term-references holding a Prolog float representing f.
- PlTerm_pointer :: PlTerm_pointer(void *ptr)
- Creates a term-references holding a Prolog pointer. 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 from
void *
. Also note that in general blobs are a better way of doing this (see the section on blobs in the Foreign Language Interface part of the SWI-Prolog manual).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; }
2.9.2 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.9.3 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 type()
- See PL_term_type()
- bool is_variable()
- See PL_is_variable()
- bool is_ground()
- See PL_is_ground()
- bool is_atom(S)
- ee PL_is_atom()
- bool is_integer(S)
- ee PL_is_integer()
- bool is_string(S)
- ee PL_is_string()
- bool is_float(S)
- ee PL_is_float()
- bool is_rational(S)
- ee PL_is_rational()
- bool is_compound(S)
- ee PL_is_compound()
- bool is_callable(S)
- ee PL_is_callable()
- bool is_list(S)
- ee PL_is_list()
- bool is_dict(S)
- ee PL_is_dict()
- bool is_pair(S)
- ee PL_is_pair()
- bool is_atomic(S)
- ee PL_is_atomic()
- bool is_number(S)
- ee PL_is_number()
- bool is_acyclic(S)
- ee PL_is_acyclic()
- bool is_functor(PlFunctor)
- See PL_is_functor()
2.9.4 Unification (version 2)
See also section 2.12.
- 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(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 PlCheck() to raise an exception if the unification fails.
PREDICATE(hostname2, 1) { char buf[256]; PlCheck(gethostname(buf, sizeof buf) == 0); PlCheck(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.9.5 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.11.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.9.6 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.9.7 Miscellaneous (version 2)
- bool is_null()
t.is_null()
is the same ast.C_ == PlTerm::null
- bool not_null()
t.not_null()
is the same ast.C_ != PlTerm::null
- bool reset()
t.reset()
is the same ast.C_ = PlTerm::null
- bool reset(term_t)
t.reset(x)
is the same ast.C_ = 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
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.9.8 The class PlTermString (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)
).
- PlString :: PlString(const wchar_t *text)
- PlString :: PlString(const char *text)
- Create a SWI-Prolog string object from a 0-terminated C-string. The text is copied.
- PlString :: PlString(const wchar_t *text, size_t len)
- PlString :: PlString(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.9.9 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.9.10 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.9.11 The class PlCompound (version 2)
- PlCompound :: PlCompound(const wchar_t *text)
- PlCompound :: PlCompound(const char *text)
- 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.9.12 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++) PlCheck(l.append(argv[i])); PlCheck(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 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.11 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.11.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.11.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.11.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.11.2, but in nested if-then-else the extraction of the atom from the term is done only once.
2.11.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.13If
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.12 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(),
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:
{ PlFrame frame; ... if ( !t1.unify_term(t2) ) frame.rewind(); ... }
Note that PlTerm::unify_term()
checks for an exception and throws an exception to Prolog; if you with
to handle exceptions, you must call PL_unify_term(t1.C_,t2.C_)
.
2.13 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.14 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 char *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.
2.14.1 The class PlFrame (version 2)
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.
- 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.
- void PlFrame::rewind()
- Discards all term-references and global-stack data created as well as undoing all unifications after the instance was created.
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:
void assertWord(const char *word) { PlFrame fr; PlTermv av(1); av[0] = PlCompound("word", PlTermv(word)); PlQuery q("assert", av); PlCheck(q.next_solution()); }
This example shows the most sensible use of PlFrame
if
it is used in the context of a foreign predicate. The predicate's
thruth-value is the same as for the 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.rewind(); return rval; }
PlRewindOnFail(f) is a convenience function that does a frame
rewind if unification fails. Here is an example, where name_to_term
contains a map from names to terms (which are made global by using the
PL_record() function):
static const std::map<const std::string, record_t> name_to_term = { {"a", PlTerm(...).record()}, ...}; bool lookup_term(const std::string name, PlTerm result) { const auto it = name_to_term.find(name); if ( it == name_to_term.cend() ) return false; PlTerm t = PlTerm_recorded(it->second); return PlRewindOnFail([result,t]() -> bool { return result.unify_term(t); }); }
2.15 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:14There
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.15.1 Variations of the PREDICATE macro (version 2)
The PREDICATE() macros have a number of variations that deal with special cases.
- PREDICATE0(name)
- This is the same as PREDICATE(name, 0). It avoids a compiler warning
about 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) { A2 = (wchar_t*)A1; }
- PREDICATE_NONDET(name, arity)
- Define a non-deterministic Prolog predicate in C++. See also section 2.15.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.15.2.
2.15.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 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. To simplify this, a template helper class
PlForeignContextPtr<ContextType>
provides a
"smart pointer" that frees the context on normal return or an exception;
if PlForeignContextPtr<ContextType>::keep() is called, the
pointer isn't freed on return or exception.
The skeleton for a typical non-deterministic predicate is:
struct PredContext { ... }; // The "context" for retries PREDICATE_NONDET(pred, <arity>) { PlForeignContextPtr<PredContext> ctxt(handle); switch( PL_foreign_control(handle) ) { case PL_FIRST_CALL: ctxt.set(new PredContext(...)); ... break; case PL_REDO: break; case PL_PRUNED: return true; } if ( ... ) return false; // Failure (and no more solutions) // or throw PlFail(); if ( ... ) return true; // Success (and no more solutions) ... ctxt.keep(); PL_retry_address(ctxt.get()); // Succeed with a choice point }
2.15.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.16 Exceptions (version 2)
Prolog exceptions are mapped to C++ exceptions using the subclass
PlException
of PlTerm
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, subclasses of PlException
have been created to exploit both their constructors for easy creation
of these exceptions as well as selective trapping in C++. Currently,
these are PlTypeEror
and PlDomainError
,
PlTermvDomainError
, PlInstantiationError
,
PlExistenceError
, PermissionError
, PlResourceError
,
and PlException_qid
.
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.18.2.
char *data = "users"; throw PlException(PlCompound("no_database", PlTerm(data)));
2.16.1 The class PlException (version 2)
This subclass of PlTerm
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.16.2 The class PlTypeError (version 2)
A type error expresses that a term does not satisfy the expected basic Prolog type.
- PlTypeError :: PlTypeError(const char *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.16.3 The class 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 char *expected, const PlTerm &actual)
- Creates an ISO standard Prolog error term expressing a the expected domain and the actual term found.
2.17 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.15For 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.18 Considerations (version 2)
2.18.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 C_
field), 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 PlCheck().
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.
2.18.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 envoked as part of handling another exception.
2.18.3 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.18.4 Status and compiler versions (version 2)
The current interface is 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.
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 2022-11, 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 2022-11, 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 calling that would happen from PL_instantiation_error(A1.C_);
throw PlFail()
. See section
2.18.2.
2.19 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.5.2
- arg/3
- 1.4.5 2.9.6
- as_string()
- as_wstring()
- assert
- 1.8.1 2.14.1
- atom_chars/2
- 1.2 1.4.9 2.4.2 2.9.10
- average/3
- 1.3.3 2.5.3
- blob_data()
- entry/1
- 1.4.11 2.9.12
- error/2
- 2.18.2
- fail/0
- 2.3
- hello/1
- 1.3.1 2.5.1
- is_acyclic()
- is_atom()
- is_atomic()
- is_callable()
- is_compound()
- is_dict()
- is_float()
- is_functor()
- is_ground()
- is_integer()
- is_list()
- is_null()
- is_number()
- is_pair()
- is_rational()
- is_string()
- is_valid()
- is_variable()
- load_foreign_library/1
- 1.9.2 2.15.3
- not_null()
- open/3
- 1.10.3 2.16.3
- print_message/2
- 1.10.1 2.16.1
- read/1
- 1.4.10 2.9.11
- register_atom()
- reset()
- throw/1
- 2.3
- type()
- unregister_atom()
- use_foreign_library/1
- 2.3
- word/1
- 1.8.1 2.14.1
- write/1
- 1.3.1 1.4.2 2.5.1 2.9.3
- NAMED_PREDICATE()
- NAMED_PREDICATE_NONDET()
- P
- PlAtom
- 1.4.3 1.6
- PlAtom!=()
- PlAtom==()
- PlCall()
- PlCompound
- 1.4.5
- PlDomainError
- 1.10
- PlEngine
- 1.11
- 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::rewind()
- PlQuery
- 1.3.3 1.5 1.8
- PlQuery::cut()()
- PlQuery::next_solution()
- PlRegister
- 1.9
- PREDICATE0()
- PREDICATE_NONDET()
- 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::compare()
- PlTerm::name()
- PlTerm::type()
- PlTerm::unify_atom()
- PlTerm::unify_blob()
- PlTerm::unify_chars()
- PlTerm::unify_float()
- PlTerm::unify_functor()
- PlTerm::unify_integer()
- PlTerm::unify_list_chars()
- PlTerm::unify_list_codes()
- PlTerm::unify_nil()
- 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
- T
- cppThrow()
- plThrow()