8.2 | Manipulating Prolog terms

8.2.1 | Introduction

In the following we presents a set of functions to manipulate Prolog terms. For simple foreign terms the functions manipulate simple C types (section 8.1.2).
Functions managing lists handle an array of 2 elements (of type `PlTerm`) containing the terms corresponding to the head and the tail of the list. For the empty list `NULL` is passed as the array. These functions require to flatten a list in each sub-list. To simplify the management of proper lists (i.e. lists terminated by `[]`) a set of functions is provided that handle the number of elements of the list (an integer) and an array whose elements (of type `PlTerm`) are the elements of the list. The caller of these functions must provide the array.
Functions managing compound terms handle a functor (the principal functor of the term), an arity `N` ³ 0 and an array of `N` elements (of type `PlTerm`) containing the sub-terms of the compound term. Since a list is a special case of compound term (functor = `'.'` and arity=2) it is possible to use any function managing compound terms to deal with a list but the error detection is not the same. Indeed many functions check if the Prolog argument is correct. The name of a read or unify function checking the Prolog arguments is of the form `Name``_Check()`. For each of these functions there is a also check-free version called `Name``()`. We then only present the name of checking functions.

8.2.2 | Managing Prolog atoms

Each atom has a unique internal key which corresponds to its index in the GNU Prolog atom table. It is possible to obtain the information about an atom and to create new atoms using:

      char *Atom_Name           (int atom)
      int   Atom_Length         (int atom)
      Bool  Atom_Needs_Quote    (int atom)
      Bool  Atom_Needs_Scan     (int atom)
      Bool  Is_Valid_Atom       (int atom)
      int   Create_Atom         (char *str)
      int   Create_Allocate_Atom(char *str)
      int   Find_Atom           (char *str)
      int   atom_char[256]
      int   atom_nil
      int   atom_false
      int   atom_true
      int   atom_end_of_file

The macro `Atom_Name(atom)` returns the internal string of `atom` (this string should not be modified). The function `Atom_Lengh(atom)` returns the length (of the name) of `atom`.
The function `Atom_Needs_Scan(atom)` indicates if the canonical form of `atom` needs to be quoted as done by `writeq/2` (section 6.14.6). In that case `Atom_Needs_Scan(atom)` indicates if this simply comes down to write quotes around the name of `atom` or if it necessary to scan each character of the name because there are some non-printable characters (or included quote characters). The function `Is_Valid_Atom(atom)` is true only if `atom` is the internal key of an existing atom.
The function `Create_Atom(str)` adds a new atom whose name is the content of `str` to the system and returns its internal key. If the atom already exists its key is simply returned. The string `str` passed to the function should not be modified later. The function `Create_Allocate_Atom(str)` is provided when this condition cannot be ensured. It simply makes a dynamic copy of `str`.
The function `Find_Atom(str)` returns the internal key of the atom whose name is `str` or `-1` if does not exist.
All atoms corresponding to a single character already exist and their key can be obtained via the global array `atom_char[]`. For instance `atom_char['.']` is the atom associated to `'.'` (this atom is the functor of lists). The other variables correspond to the internal key of frequently used atoms: `[]`, `false`, `true` and `end_of_file`.

8.2.3 | Reading Prolog terms

The name of all functions presented here are of the form `Rd_``Name``_Check()`. They all check the validity of the Prolog term to read emitting appropriate errors if necessary. Each function has a check-free version called `Rd_``Name``()`.
Simple foreign types: for each simple foreign type (section 8.1.2) there is a read function (used by the interface when an input argument is provided):

      int     Rd_Integer_Check  (PlTerm term)
      int     Rd_Positive_Check (PlTerm term)
      double  Rd_Float_Check    (PlTerm term)
      double  Rd_Number_Check   (PlTerm term)
      int     Rd_Atom_Check     (PlTerm term)
      int     Rd_Boolean_Check  (PlTerm term)
      int     Rd_Char_Check     (PlTerm term)
      int     Rd_In_Char_Check  (PlTerm term)
      int     Rd_Code_Check     (PlTerm term)
      int     Rd_In_Code_Check  (PlTerm term)
      int     Rd_Byte_Check     (PlTerm term)
      int     Rd_In_Byte_Check  (PlTerm term)
      char   *Rd_String_Check   (PlTerm term)
      char   *Rd_Chars_Check    (PlTerm term)
      char   *Rd_Codes_Check    (PlTerm term)
      int     Rd_Chars_Str_Check(PlTerm term, char *str)
      int     Rd_Codes_Str_Check(PlTerm term, char *str)

All functions returning a C string (`char *`) use a same buffer. The function `Rd_Chars_Str_Check()` is similar to `Rd_Chars_Check()` but accepts as argument a string to store the result and returns the length of that string (which is also the length of the Prolog list). Similarly for `Rd_Codes_Str_Check()`.
Complex terms: the following functions return the sub-arguments (terms) of complex terms as an array of `PlTerm` except `Rd_Proper_List_Check()` which returns the size of the list read (and initializes the array `element`). Refer to the introduction of this section for more information about the arguments of complex functions (section 8.2.1).

      int     Rd_Proper_List_Check(PlTerm term, PlTerm *arg)
      PlTerm *Rd_List_Check       (PlTerm term)
      PlTerm *Rd_Compound_Check   (PlTerm term, int *functor, int *arity)
      PlTerm *Rd_Callable_Check   (PlTerm term, int *functor, int *arity)

8.2.4 | Unifying Prolog terms

The name of all functions presented here are of the form `Un_``Name``_Check()`. They all check the validity of the Prolog term to unify emitting appropriate errors if necessary. Each function has a check-free version called `Un_``Name``()`.
Simple foreign types: for each simple foreign type (section 8.1.2) there is an unify function (used by the interface when an output argument is provided):

      Bool Un_Integer_Check (int n,     PlTerm term)
      Bool Un_Positive_Check(int n,     PlTerm term)
      Bool Un_Float_Check   (double n,  PlTerm term)
      Bool Un_Number_Check  (double n,  PlTerm term)
      Bool Un_Atom_Check    (int atom,  PlTerm term)
      Bool Un_Boolean_Check (int b,     PlTerm term)
      Bool Un_Char_Check    (int c,     PlTerm term)
      Bool Un_In_Char_Check (int c,     PlTerm term)
      Bool Un_Code_Check    (int c,     PlTerm term)
      Bool Un_In_Code_Check (int c,     PlTerm term)
      Bool Un_Byte_Check    (int b,     PlTerm term)
      Bool Un_In_Byte_Check (int b,     PlTerm term)
      Bool Un_String_Check  (char *str, PlTerm term)
      Bool Un_Chars_Check   (char *str, PlTerm term)
      Bool Un_Codes_Check   (char *str, PlTerm term)

The function `Un_Number_Check(n, term)` unifies `term` with an integer if `n` is an integer, with a floating point number otherwise. The function `Un_String_Check(str, term)` creates the atom corresponding to `str` and then unifies term with it (same as `Un_Atom_Check(Create_Allocate_Atom(str), term)`).
Complex terms: the following functions accept the sub-arguments (terms) of complex terms as an array of `PlTerm`. Refer to the introduction of this section for more information about the arguments of complex functions (section 8.2.1).

      Bool Un_Proper_List_Check(int size, PlTerm *arg, PlTerm term)
      Bool Un_List_Check       (PlTerm *arg, PlTerm term)
      Bool Un_Compound_Check   (int functor, int arity, PlTerm *arg,
                                PlTerm term)
      Bool Un_Callable_Check   (int functor, int arity, PlTerm *arg,
                                PlTerm term)

All these functions check the type of the term to unify and return the result of the unification. Generally if an unification fails the C function returns `FALSE` to enforce a failure. However if there are several arguments to unify and if an unification fails then the C function returns `FALSE` and the type of other arguments has not been checked. Normally all error cases are tested before doing any work to be sure that the predicate fails/succeeds only if no error condition is satisfied. So a good method is to check if the validity of all arguments to unify and later to do the unification (using check-free functions). Obviously if there is only one to unify it is more efficient to use a unify function checking the argument. For the other cases the interface provides a set of functions to check the type of a term.
Simple foreign types: for each simple foreign type (section 8.1.2) there is check-for-unification function (used by the interface when an output argument is provided):

      void Check_For_Un_Integer (PlTerm term)
      void Check_For_Un_Positive(PlTerm term)
      void Check_For_Un_Float   (PlTerm term)
      void Check_For_Un_Number  (PlTerm term)
      void Check_For_Un_Atom    (PlTerm term)
      void Check_For_Un_Boolean (PlTerm term)
      void Check_For_Un_Char    (PlTerm term)
      void Check_For_Un_In_Char (PlTerm term)
      void Check_For_Un_Code    (PlTerm term)
      void Check_For_Un_In_Code (PlTerm term)
      void Check_For_Un_Byte    (PlTerm term)
      void Check_For_Un_In_Byte (PlTerm term)
      void Check_For_Un_String  (PlTerm term)
      void Check_For_Un_Chars   (PlTerm term)
      void Check_For_Un_Codes   (PlTerm term)

Complex terms: the following functions check the validity of complex terms:

      void Check_For_Un_List    (PlTerm term)
      void Check_For_Un_Compound(PlTerm term)
      void Check_For_Un_Callable(PlTerm term)
      void Check_For_Un_Variable(PlTerm term)

The function `Check_For_Un_List(term)` checks if `term` can be unified with a list. This test is done for the entire list (not only for the functor/arity of `term` but also recursively on the tail of the list). The function `Check_For_Un_Variable(term)` ensures that `term` is not currently instantiated. These functions can be defined using functions to test the type of a Prolog term (section 8.2.6) and functions to raise Prolog errors (section 8.3). For instance `Check_For_Un_List(term)` is defined as follows:

      void Check_For_Un_List(PlTerm term)
      {
       if (!Blt_List_Or_Partial_List(term))
           Pl_Err_Type(type_list, term);
      }

8.2.5 | Creating Prolog terms

These functions are provided to creates Prolog terms. Each function returns a `PlTerm` containing the created term.
Simple foreign types: for each simple foreign type (section 8.1.2) there is a creation function:

      PlTerm Mk_Integer (int n)
      PlTerm Mk_Positive(int n)
      PlTerm Mk_Float   (double n)
      PlTerm Mk_Number  (double n)
      PlTerm Mk_Atom    (int atom)
      PlTerm Mk_Boolean (int b)
      PlTerm Mk_Char    (int c)
      PlTerm Mk_In_Char (int c)
      PlTerm Mk_Code    (int c)
      PlTerm Mk_In_Code (int c)
      PlTerm Mk_Byte    (int b)
      PlTerm Mk_In_Byte (int b)
      PlTerm Mk_String  (char *str)
      PlTerm Mk_Chars   (char *str)
      PlTerm Mk_Codes   (char *str)

The function `Mk_Number(n, term)` initializes `term` with an integer if `n` is an integer, with a floating point number otherwise. The function `Mk_String(str)` first creates an atom corresponding to `str` and then returns that Prolog atom (i.e. equivalent to `Mk_Atom(Create_Allocate_Atom(str))`).
Complex terms: the following functions accept the sub-arguments (terms) of complex terms as an array of `PlTerm`. Refer to the introduction of this section for more information about the arguments of complex functions (section 8.2.1).

      PlTerm Mk_Proper_List(int size, PlTerm *arg)
      PlTerm Mk_List       (PlTerm *arg)
      PlTerm Mk_Compound   (int functor, int arity, PlTerm *arg)
      PlTerm Mk_Callable   (int functor, int arity, PlTerm *arg)

8.2.6 | Testing the type of Prolog terms

The following functions test the type of a Prolog term. Each function corresponds to a type testing built-in predicate (section 6.1.1).

      Bool Blt_Var                 (PlTerm term)
      Bool Blt_Non_Var             (PlTerm term)
      Bool Blt_Atom                (PlTerm term)
      Bool Blt_Integer             (PlTerm term)
      Bool Blt_Float               (PlTerm term)
      Bool Blt_Number              (PlTerm term)
      Bool Blt_Atomic              (PlTerm term)
      Bool Blt_Compound            (PlTerm term)
      Bool Blt_Callable            (PlTerm term)
      Bool Blt_List                (PlTerm term)
      Bool Blt_Partial_List        (PlTerm term)
      Bool Blt_List_Or_Partial_List(PlTerm term)
      Bool Blt_Fd_Var              (PlTerm term)
      Bool Blt_Non_Fd_Var          (PlTerm term)
      Bool Blt_Generic_Var         (PlTerm term)
      Bool Blt_Non_Generic_Var     (PlTerm term)
      int  Type_Of_Term            (PlTerm term)
      int  List_Length             (PlTerm list)

The function `Type_Of_Term(term)` returns the type of `term`, the following constants can be used to test this type (e.g. in a `switch` instruction):

- `PLV`: Prolog variable.
- `FDV`: finite domain variable.
- `INT`: integer.
- `FLT`: floating point number.
- `ATM`: atom.
- `LST`: list.
- `STC`: structure

The tag `LST` means a term whose principal functor is `'.'` and whose arity is 2 (recall that the empty list is the atom `[]`). The tag `STC` means any other compound term.
The function `List_Length(list)` returns the number of elements of the `list` (`0` for the empty list). If list is not a list this function returns `-1`.

8.2.7 | Comparing Prolog terms

The following functions compares Prolog terms. Each function corresponds to a comparison built-in predicate (section 6.3.2).

      Bool Blt_Term_Eq (PlTerm term1, PlTerm term2)
      Bool Blt_Term_Neq(PlTerm term1, PlTerm term2)
      Bool Blt_Term_Lt (PlTerm term1, PlTerm term2)
      Bool Blt_Term_Lte(PlTerm term1, PlTerm term2)
      Bool Blt_Term_Gt (PlTerm term1, PlTerm term2)
      Bool Blt_Term_Gte(PlTerm term1, PlTerm term2)

All these functions are based on a general comparison function returning a negative integer if `term1` is less than `term2`, 0 if they are equal and a positive integer otherwise:

      int Term_Compare(PlTerm term1, PlTerm term2)

8.2.8 | Copying Prolog terms

The following functions make a copy of a Prolog term:

      void Copy_Term           (PlTerm *dst_adr, PlTerm *src_adr)
      void Copy_Contiguous_Term(PlTerm *dst_adr, PlTerm *src_adr)
      int  Term_Size           (PlTerm term)

The function `Copy_Term(dst_adr, src_adr)` makes a copy of the term located at `src_adr` and stores it from the address given by `dst_adr`. The result is a contiguous term. If it can be ensured that the source term is a contiguous term (i.e. result of a previous copy) the function `Copy_Contiguous_Term()` can be used instead (it is faster). In any case, sufficient space should be available for the copy (i.e. from `dst_adr`). The function `Term_Size(term)` returns the number of `PlTerm` needed by `term`.

8.2.9 | Comparing and evaluating arithmetic expressions

The following functions compare arithmetic expressions. Each function corresponds to a comparison built-in predicate (section 6.6.3).

      Bool Blt_Eq (PlTerm expr1, PlTerm expr2)
      Bool Blt_Neq(PlTerm expr1, PlTerm expr2)
      Bool Blt_Lt (PlTerm expr1, PlTerm expr2)
      Bool Blt_Lte(PlTerm expr1, PlTerm expr2)
      Bool Blt_Gt (PlTerm expr1, PlTerm expr2)
      Bool Blt_Gte(PlTerm expr1, PlTerm expr2)

The following function evaluates the expression `expr` and stores its result as a Prolog number (integer or floating point number) in `result`:

      void Math_Load_Value(PlTerm expr, PlTerm *result)

This function can be followed by a read function (section 8.2.3) to obtain the result.

Copyright (C) 1999,2000 Daniel Diaz
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
More about the copyright