s function will make plain a reference to <rest> and fill module * with <module>. For further nested module constructs the innermost module is returned via module *. If raw is not a module construct, raw will simply be put in plain. The value pointed to by m must be initialized before calling PL_strip_module(), either to the default module or to NULL. A NULL value is replaced by the current context module if raw carries no module. The following example shows how to obtain the plain term and module if the default module is the user module:

{ module m = PL_new_module(PL_new_atom("user"));
  term_t plain = PL_new_term_ref();

  PL_strip_module(term, &m, plain);
  ...
}

atom_t PL_module_name(module_t module)

Return the name of module as an atom.

module_t PL_new_module(atom_t name)

Find an existing module or create a new module with the name name. Currently aborts the process with a fatal error on failure. Future versions may raise a resource exception and return (module_t)0.

12.4.14 Prolog exceptions in foreign code

This section discusses PL_exception() and PL_raise_exception(), the interface functions to detect and generate Prolog exceptions from C code. PL_raise_exception() from the C interface registers the exception term and returns FALSE. If a foreign predicate returns FALSE, while an exception term is registered, a Prolog exception will be raised by the virtual machine. This implies for a foreign function that implements a predicate and wishes to raise an exception, the function shall call PL_raise_exception(), perform any necessary cleanup and return the return code of PL_raise_exception() or explicitly FALSE. Calling PL_raise_exception() outside the context of a function implementing a foreign predicate results in undefined behaviour.

Note that many of the C API functions may call PL_raise_exception() and return FALSE. The user shall test for this, cleanup and make the foreign function return FALSE.

PL_exception() may be used to inspect the currently registered exception. It is normally called after a call to PL_next_solution() returns FALSE, and returns a term reference to an exception term if an exception is pedning, and (term_t)0 otherwise. It may also be called after, e.g., PL_unify() to distinguish a normal failing unification from a unification that raised an resource error exception.

If a C function implementing a predicate that calls Prolog should use PL_open_query() with the flag PL_Q_PASS_EXCEPTION and make the function return FALSE if PL_next_solution() returns FALSE and PL_exception() indicates an exception is pending.

Both for C functions implementing a predicate and when Prolog is called while the main control of the process is in C, user code should always check for exceptions. As explained above, C functions implementing a predicate should normally cleanup and return with FALSE. If the C function whishes to continue it may call PL_clear_exception(). Note that this may cause any exeption to be ignored, including time outs and abort. Typically the user should check the exeption details before ignoring an exception. If the C code does not implement a predicate it normally prints the exception and calls PL_clear_exception() to discard it. Exceptions may be printed by calling print_message/2 through the C interface.

int PL_raise_exception(term_t exception)

Generate an exception (as throw/1) and return FALSE. This function is rarely used directly. Instead, errors are typically raised using the functions in section 12.4.6 or the C api functions that end in _ex such as PL_get_atom_ex(). Below we give an example returning an exception from a foreign predicate the verbose way. Note that the exception is raised in a sequence of actions connected using &&. This ensures that a proper exception is raised should any of the calls used to build or raise the exception themselves raise an exception. In this simple case PL_new_term_ref() is guaranteed to succeed because the system guarantees at least 10 available term references before entering the foreign predicate. PL_unify_term() however may raise a resource exception for the global stack.

foreign_t
pl_hello(term_t to)
{ char *s;

  if ( PL_get_atom_chars(to, &s) )
  { Sprintf("Hello \"%s\"\n", s);

    return TRUE;
  } else
  { term_t except;

    return  ( (except=PL_new_term_ref()) &&
              PL_unify_term(except,
                            PL_FUNCTOR_CHARS, "type_error", 2,
                              PL_CHARS, "atom",
                              PL_TERM, to) &&
              PL_raise_exception(except) );
  }
}

For reference, the preferred implementation of the above is below. The CVT_EXCEPTION tells the system to generate an exception if the conversion fails. The other CVT_ flags define the admissible types and REP_MB requests the string to be provided in the current locale representation. This implies that Unicode text is printed correctly if the current environment can represent it. If not, a representation_error is raised.

foreign_t
pl_hello(term_t to)
{ char *s;

  if ( PL_get_chars(to, &s, CVT_ATOM|CVT_STRING|CVT_EXCEPTION|REP_MB) )
  { Sprintf("Hello \"%s\"\n", s);

    return TRUE;
  }

  return FALSE;
}

int PL_throw(term_t exception)

Similar to PL_raise_exception(), but returns using the C longjmp() function to the innermost PL_next_solution(). This function is deprecated as it does not provide the opportunity to cleanup.