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.
PL_VARIABLE | An unbound variable. The value of term as such is a unique identifier for the variable. |
PL_ATOM | A Prolog atom. |
PL_STRING | A Prolog string. |
PL_INTEGER | A Prolog integer. |
PL_FLOAT | A Prolog floating point number. |
PL_TERM | A compound term. Note that a list is a compound term with name `.' and arity 2. |
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.