SWI-Prolog -- Convenient functions to generate Prolog exceptions

Documentation
- Reference manual
  - Foreign Language Interface
    - The Foreign Include File
- Packages

PL_LISTint length, ...

Create a list of the indicated length. The remaining arguments contain the elements of the list.

For example, to unify an argument with the term language(dutch), the following skeleton may be used:

static functor_t FUNCTOR_language1;

static void
init_constants()
{ FUNCTOR_language1 = PL_new_functor(PL_new_atom("language"),1);
}

foreign_t
pl_get_lang(term_t r)
{ return PL_unify_term(r,
                       PL_FUNCTOR, FUNCTOR_language1,
                           PL_CHARS, "dutch");
}

install_t
install()
{ PL_register_foreign("get_lang", 1, pl_get_lang, 0);
  init_constants();
}

int PL_chars_to_term(const char *chars, term_t -t)

Parse the string chars and put the resulting Prolog term into t. chars may or may not be closed using a Prolog full-stop (i.e., a dot followed by a blank). Returns FALSE if a syntax error was encountered and TRUE after successful completion. In addition to returning FALSE, the exception-term is returned in t on a syntax error. See also term_to_atom/2.

The following example builds a goal term from a string and calls it.

int
call_chars(const char *goal)
{ fid_t fid = PL_open_foreign_frame();
  term_t g = PL_new_term_ref();
  BOOL rval;

  if ( PL_chars_to_term(goal, g) )
    rval = PL_call(goal, NULL);
  else
    rval = FALSE;

  PL_discard_foreign_frame(fid);
  return rval;
}
  ...
  call_chars("consult(load)");
  ...

PL_chars_to_term() is defined using PL_put_term_from_chars() which can deal with not null-terminated strings as well as strings using different encodings:

int
PL_chars_to_term(const char *s, term_t t)
{ return PL_put_term_from_chars(t, REP_ISO_LATIN_1, (size_t)-1, s);
}

int PL_wchars_to_term(const pl_wchar_t *chars, term_t -t)

Wide character version of PL_chars_to_term().

char * PL_quote(int chr, const char *string)

Return a quoted version of string. If chr is '\'', the result is a quoted atom. If chr is '"', the result is a string. The result string is stored in the same ring of buffers as described with the BUF_STACK argument of PL_get_chars();

In the current implementation, the string is surrounded by chr and any occurrence of chr is doubled. In the future the behaviour will depend on the character_escapes Prolog flag.

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_size(), 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 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().