1.15.1 The class PlException

This subclass of PlExceptionBase is used to represent exceptions.

1.15.1.1 PlException class hierarchy

The various exceptions are arranged into a hierarchy as follows. For PlException, there are convenience functions that create and wrap a Prolog term, similar to the PL_domain_error(), etc. The hierarchy allows catch statements to easily handle combinations.

A PlException object contains a Prolog term, so its what() method must be called either within a Prolog predicate or within the context of a PlEngine (and PlFrame; see section 1.16). The term is copied so that it is available outside of the context of the frame that created it.

You cannot create a PlExceptionBase or PlException because their constructors are protected.

In this diagram, names with () are functions; the others are classes.

std::exception
*-- PlExceptionBase
    *-- PlException
    |   *.. PlExceptionFromTerm
    |   *.. PlExceptionFromQid
    |   *.. PlDomainError()
    |   *.. PlExistenceError()
    |   *.. PlGeneralError()
    |   *.. PlInstantiationError()
    |   *.. PlPermissionError()
    |   *.. PlRepresentationError()
    |   *.. PlResourceError()
    |   *.. PlTypeError()
    |   *.. PlUninstantiationError()
    |   *.. PlUnknownError()
    *-- PlExceptionFailBase
    |   *-- PlExceptionFail
    |   *-- PlFail
    *-- PlEngineInitialisationFailed
    *-- PlOpenForeignFrameFailed

Note that everything under PlException can contain a Prolog term; if the what() method is called, it must be within the context of a Prolog frame. If you wish to pass the exception outside the frame, you can use the set_what_str() method to avoid evaluating the term after it has been freed by Prolog:

  try
  { PlCall("p(123)");
      ...
  } catch ( PlException &ex )
  { ex.set_what_str();
    throw; // rethrow the exception
  }

Currently defined methods are:

PlException :: PlException(const PlTerm &t)

Create an exception from a general Prolog term. This provides the interface for throwing any Prolog terms as an exception. This constructor is protected; instead you should use PlExceptionFromTerm or PlExceptionFromQid.

char* what()

See ctypestd::exception::what(). Note that if this is called outside the Prolog frame where the exception was created, there must have been a call to PlException::set_what_str() inside the Prolog frame.

std::string as_string()

The exception is translated into a message as produced by print_message/2. Note that if this is called outside the Prolog frame where the exception was created, there must have been a call to PlException::set_what_str() inside the Prolog frame. See also std::exception::what().

  ...;
  try
  { PlCall("consult(load)");
  } catch ( const PlException& ex )
  { cerr << ex.as_string() << endl;
  }

int plThrow()

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

void set_what_str()

1.15.1.2 The function PlTypeError

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.

1.15.1.3 The function 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 std::string& expected, const PlTerm &actual)

Creates an ISO standard Prolog error term expressing a the expected domain and the actual term found.