Analysing Terms via the Foreign Interface

Each argument of a foreign function (except for the control argument) is of type term. 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.

.BF .F int PL_type 1 term 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.

.BF .F int PL_is_var 1 term Returns non-zero if term is a variable. .F int PL_is_atom 1 term Returns non-zero if term is an atom. .F int PL_is_string 1 term Returns non-zero if term is a string. .F int PL_is_int 1 term Returns non-zero if term is an integer. .F int PL_is_float 1 term Returns non-zero if term is a float. .F int PL_is_term 1 term Returns non-zero if term is a compound term. .F atomic PL_atomic 1 term Return the atomic value of term in Prolog internal representation. Term should be atomic (e.g. atom, integer, float or string). .F long PL_integer_value 1 atomic Transforms an integer from Prolog internal representation into a C long. .F double PL_float_value 1 atomic Transforms a float from Prolog internal representation into a C double. .F char * PL_atom_value 1 atomic 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. .F char * PL_string_value 1 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. .F functor PL_functor 1 term 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:

.F atomic PL_functor_name 1 functor 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)))

.F int PL_functor_arity 1 functor Return a C integer representing the arity of functor. .F term PL_arg 2 term, 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. .EF

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

Figure: Foreign definition of display/1