1.10 Exceptions

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.

To throw an exception, create an instance of PlException and use throw().

  char *data = "users";

  throw PlException(PlCompound("no_database", PlTerm(data)));

1.10.1 The class PlException

The C++ model of exceptions and the Prolog model of exceptions are different. Wherever the underlying function returns a "fail" return code, the C++ API does a further check for whether there's an exception and, if so, does a C++ throw of a PlException object. You can use C++ try-catch to intercept this and examine the

This subclass of PlTerm is used to represent exceptions. Currently defined methods are:

PlException :: PlException()

Create an exception term using PL_exception(0). The method is_null() succeeds if there was simple failure (e.g., from unification failing) and not_null() succeeds if there was an exception.

PlException :: PlException(const PlTerm &)

Create an exception from a general Prolog term. This provides the interface for throwing any Prolog terms as an exception.

PlException ::operator wchar_t *(void)

PlException ::operator char *(void)

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 << (char *) ex << endl;
  }

int plThrow()

Used in the PREDICATE() wrapper to pass the exception to Prolog. See PL_raise_exeption().

int cppThrow()

Used by PlQuery::next_solution() to refine a generic PlException representing a specific class of Prolog exceptions to the corresponding C++ exception class and finally then executes throw(). Thus, if a PlException represents the term

error(type_error(Expected, Actual), Context)

PlException::cppThrow() throws a PlTypeEror exception. This ensures consistency in the exception-class whether the exception is generated by the C++-interface or returned by Prolog.

The following example illustrates this behaviour:

PREDICATE(call_atom, 1)
{ try
  { return PlCall((char *)A1);
  } catch ( PlTypeError &ex )
  { cerr << "Type Error caugth in C++" << endl;
    cerr << "Message: \"" << (char *)ex << "\"" << endl;
    return FALSE;
  }
}

1.10.2 The class PlTypeError

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.

1.10.3 The class PlDomainError

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.