1.15.1 The class PlException
All Application Manual Name SummaryHelp

  • Documentation
    • Reference manual
    • Packages
      • A C++ interface to SWI-Prolog
        • A C++ interface to SWI-Prolog
          • Exceptions
            • The class PlException
              • PlException class hierarchy
              • The function PlTypeError
              • The function PlDomainError

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.

std::exception
*-- PlExceptionBase
    *-- PlException
    |   *.. 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 &)
Create an exception from a general Prolog term. This provides the interface for throwing any Prolog terms as an exception.
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()