12.4.7 Convenient functions to generate Prolog exceptions

The typical implementation of a foreign predicate first uses the PL_get_*() functions to extract C data types from the Prolog terms. Failure of any of these functions is normally because the Prolog term is of the wrong type. The *_ex() family of functions are wrappers around (mostly) the PL_get_*() functions, such that we can write code in the style below and get proper exceptions if an argument is uninstantiated or of the wrong type. Section 12.4.8 documents an alternative API to fetch values for the C basic types.

/** set_size(+Name:atom, +Width:int, +Height:int) is det.

static foreign_t
set_size(term_t name, term_t width, term_t height)
{ char *n;
  int w, h;

  if ( !PL_get_chars(name, &n, CVT_ATOM|CVT_EXCEPTION) ||
       !PL_get_integer_ex(with, &w) ||
       !PL_get_integer_ex(height, &h) )
    return FALSE;

  ...

}

int PL_get_atom_ex(term_t t, atom_t *a)

As PL_get_atom(), but raises a type or instantiation error if t is not an atom.

int PL_get_integer_ex(term_t t, int *i)

As PL_get_integer(), but raises a type or instantiation error if t is not an integer, or a representation error if the Prolog integer does not fit in a C int.

int PL_get_long_ex(term_t t, long *i)

As PL_get_long(), but raises a type or instantiation error if t is not an atom, or a representation error if the Prolog integer does not fit in a C long.

int PL_get_int64_ex(term_t t, int64_t *i)

As PL_get_int64(), but raises a type or instantiation error if t is not an integer, or a representation error if the Prolog integer does not fit in a C int64_t.

int PL_get_uint64_ex(term_t t, uint64_t *i)

As PL_get_uint64(), but raises a type, domain or instantiation error if t is not an integer or t is less than zero, or a representation error if the Prolog integer does not fit in a C int64_t.

int PL_get_intptr_ex(term_t t, intptr_t *i)

As PL_get_intptr(), but raises a type or instantiation error if t is not an atom, or a representation error if the Prolog integer does not fit in a C intptr_t.

int PL_get_size_ex(term_t t, size_t *i)

As PL_get_intptr(), but raises a type or instantiation error if t is not an integer, or a representation error if the Prolog integer does not fit in a C size_t.

int PL_get_bool_ex(term_t t, int *i)

As PL_get_bool(), but raises a type or instantiation error if t is not a valid boolean value (true, false, on, constoff, 1 or 0). Note that the pointer is to an int because C has no bool type.

int PL_get_float_ex(term_t t, double *f)

As PL_get_float(), but raises a type or instantiation error if t is not a float.

int PL_get_char_ex(term_t t, int *p, int eof)

Get a character code from t, where t is either an integer or an atom with length one. If eof is TRUE and t is -1, p is filled with -1. Raises an appropriate error if the conversion is not possible.

int PL_get_pointer_ex(term_t t, void **addrp)

As PL_get_pointer(), but raises a type or instantiation error if t is not a pointer.

int PL_get_list_ex(term_t l, term_t h, term_t t)

As PL_get_list(), but raises a type or instantiation error if t is not a list.

int PL_get_nil_ex(term_t l)

As PL_get_nil(), but raises a type or instantiation error if t is not the empty list. Because PL_get_nil_ex() is commonly used after a while loop over PL_get_list_ex(), it fails immediately if there is an exception pending (from PL_get_list_ex()).

int PL_unify_list_ex(term_t l, term_t h, term_t t)

As PL_unify_list(), but raises a type error if t is not a variable, list-cell or the empty list.

int PL_unify_nil_ex(term_t l)

As PL_unify_nil(), but raises a type error if t is not a variable, list-cell or the empty list.

int PL_unify_bool_ex(term_t t, int val)

As PL_unify_bool(), but raises a type error if t is not a variable or a boolean.

The second family of functions in this section simplifies the generation of ISO compatible error terms. Any foreign function that calls this function must return to Prolog with the return code of the error function or the constant FALSE. If available, these error functions add the name of the calling predicate to the error context. See also PL_raise_exception().

int PL_instantiation_error(term_t culprit)

Raise instantiation_error. Culprit is ignored, but should be bound to the term that is insufficiently instantiated. See instantiation_error/1.

int PL_uninstantiation_error(term_t culprit)

Raise uninstantiation_error(culprit). This should be called if an argument that must be unbound at entry is bound to culprit. This error is typically raised for a pure output arguments such as a newly created stream handle (e.g., the third argument of open/3).

int PL_representation_error(const char *resource)

Raise representation_error(resource). See representation_error/1.

int PL_type_error(const char *expected, term_t culprit)

Raise type_error(expected, culprit). See type_error/2.

int PL_domain_error(const char *expected, term_t culprit)

Raise domain_error(expected, culprit). See domain_error/2.

int PL_existence_error(const char *type, term_t culprit)

Raise existence_error(type, culprit). See existence_error/2.

int PL_permission_error(const char *operation, const char *type, term_t culprit)

Raise permission_error(operation, type, culprit). See permission_error/3.

int PL_resource_error(const char *resource)

Raise resource_error(resource). See resource_error/1.

int PL_syntax_error(const char *message, IOSTREAM *in)

Raise syntax_error(message). If arg is not NULL, add information about the current position of the input stream.