SWI-Prolog -- The class PlTerm (version 2)

Documentation
- Reference manual
- Packages
  - A C++ interface to SWI-Prolog
    - A C++ interface to SWI-Prolog (Version 2)

2.10 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.10.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.10.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.10.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 the PlTerm is a Prolog integer or float that can be converted without loss to a long. throws a type_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.10.4 Unification (version 2)

2.10.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 a long and perform standard C-comparison between the two long integers. If PlTerm cannot be converted a type_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 the PlTerm 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 an type_error exception if the conversion failed.

Below are some typical examples. See section 2.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.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 new PlTerm representing the arg-th argument of the term. If PlTerm is not compound, a type_error is raised. Id arg is out of range, a domain_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 class PlCompound. The following example tests x to represent a term with first-argument an atom or string equal to gnat.

   ...,
   if ( x[1] == "gnat" )
     ...

const char * PlTerm::name()

Return a const char * holding the name of the functor of the compound term. Raises a type_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.7 Miscellaneous (version 2)

bool is_null(): t.is_null() is the same as t.unwrap() == PlTerm::null
bool not_null(): t.not_null() is the same as t.unwrap() != PlTerm::null
bool reset(): t.reset() is the same as t.unwrap() = PlTerm::null
bool reset(term_t): t.reset(x) is the same as t.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 or PL_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.10.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.10.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.10.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.10.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 term hello(world).

PlCompound("hello", PlTermv("world"))

2.10.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. As PlTail 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 the PlTail object now points to the new variable B.

This function returns true if the unification succeeded and false 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 advance PlTail. Returns true on success and false if PlTail represents the empty list. If PlTail is neither a list nor the empty list, a type_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;
}