Analysing Terms via the Foreign Interface

Each argument of a foreign function (except for the control argument) is of type term_t. To analyse a term one should first obtain the type of the term. Primitive terms can then be transformed into atomic data in internal Prolog representation. This atomic data can be transformed into C-data types. Complex terms are analysed in terms on their functor and arguments. The arguments themselves are terms, allowing the same procedure to be repeated recursively.

int

PL_type( term_t)
  Obtain the type of term, which should be a term returned by one of the other interface predicates or passed as an argument. The function returns the type of the Prolog term. The type identifiers are listed below.

The functions PL_is_<type> allow form an alternative to PL_type. The test ``PL_is_var(term)'' is equivalent to ``PL_type(term) == PL_VARIABLE'', but the first is considerably faster.

int

PL_is_var( term_t)
  Returns non-zero if term is a variable.

int

PL_is_atom( term_t)
  Returns non-zero if term is an atom.

int

PL_is_string( term_t)
  Returns non-zero if term is a string.

int

PL_is_int( term_t)
  Returns non-zero if term is an integer.

int

PL_is_float( term_t)
  Returns non-zero if term is a float.

int

PL_is_term( term_t)
  Returns non-zero if term is a compound term.

atomic_t

PL_atomic( term_t)
  Return the atomic value of term in Prolog internal representation. Term should be atomic (e.g. atom, integer, float or string).

long

PL_integer_value( atomic_t)
  Transforms an integer from Prolog internal representation into a C long.

double

PL_float_value( atomic_t)
  Transforms a float from Prolog internal representation into a C double.

char *

PL_atom_value( atomic_t)
  Transforms an atom from Prolog internal representation into a 0-terminated C char *. The pointer points directly into the Prolog heap and can assumed to be static. The contents of the character string however should under NO circumstances be modified.

char *

PL_string_value( string)
  Transform a string from Prolog internal representation into a C char *. The pointer points directly into the Prolog data area. Unlike the pointer returned by PL_atom_value() the C user should copy the value to a private data area if its value should survive the current foreign language call. Like PL_atom_value(), changing the contents of the character string is NOT allowed.

functor_t

PL_functor( term_t)
  term should be a complex term. The return value is a unique identifier of the term's name and arity. The following example demonstrates this:

pl_same_functor(term_t t1, term_t t2)
{ if ( !PL_is_term(t1) || !PL_is_term(t2) )
    PL_fail;
  if ( PL_functor(t1) == PL_functor(t2) )
    PL_succeed;
  PL_fail;
}

atomic_t

PL_functor_name( functor_t)
  Return an atom representing the name of functor. To get the functor name as char * of a term which is known to be compound:

#define functor_name(term) PL_atom_value(PL_functor_name(PL_functor(term)))

int

PL_functor_arity( functor_t)
  Return a C integer representing the arity of functor.

term

PL_arg( term_t, int)
  Return the int-th argument of term. Argument counting starts at 1 and is valid up to and including the arity of term. No checks on these boundaries are performed.

Figure shows a definition of display/1 to illustrate the described functions.

  
Figure: A Foreign definition of display/1