9.4.4 Constructing Terms

Terms can be constructed using functions from the PL_put_*() and PL_cons_*() families. This approach builds the term `inside-out', starting at the leaves and subsequently creating compound terms. Alternatively, terms may be created `top-down', first creating a compound holding only variables and subsequently unifying the arguments. This section discusses functions for the first approach. This approach is generally used for creating arguments for PL_call() and PL_open_query().

void PL_put_variable(term_t -t)

Put a fresh variable in the term, resetting the term reference to its initial state.^{112Older versions created a variable on the global stack.}

void PL_put_atom(term_t -t, atom_t a)

Put an atom in the term reference from a handle. See also PL_new_atom() and PL_atom_chars().

void PL_put_bool(term_t -t, int val)

Put one of the atoms true or false in the term reference See also PL_put_atom(), PL_unify_bool() and PL_get_bool().

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

Put an atom in the term reference constructed from the zero-terminated string. The string itself will never be referenced by Prolog after this function.

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

Put a zero-terminated string in the term reference. The data will be copied. See also PL_put_string_nchars().

int PL_put_string_nchars(term_t -t, size_t len, const char *chars)

Put a string, represented by a length/start pointer pair in the term reference. The data will be copied. This interface can deal with 0-bytes in the string. See also section 9.4.20.

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

Put a list of ASCII values in the term reference.

int PL_put_integer(term_t -t, long i)

Put a Prolog integer in the term reference.

int PL_put_int64(term_t -t, int64_t i)

Put a Prolog integer in the term reference.

int PL_put_pointer(term_t -t, void *ptr)

Put a Prolog integer in the term reference. Provided ptr is in the `malloc()-area', PL_get_pointer() will get the pointer back.

int PL_put_float(term_t -t, double f)

Put a floating-point value in the term reference.

int PL_put_functor(term_t -t, functor_t functor)

Create a new compound term from functor and bind t to this term. All arguments of the term will be variables. To create a term with instantiated arguments, either instantiate the arguments using the PL_unify_*() functions or use PL_cons_functor().

int PL_put_list(term_t -l)

Same as PL_put_functor(l, PL_new_functor(PL_new_atom("."), 2)).

int PL_put_nil(term_t -l)

Same as PL_put_atom_chars("[]"). Always returns TRUE.

void PL_put_term(term_t -t1, term_t +t2)

Make t1 point to the same term as t2.

int PL_cons_functor(term_t -h, functor_t f, ...)

Create a term whose arguments are filled from a variable argument list holding the same number of term_t objects as the arity of the functor. To create the term animal(gnu, 50), use:

{ term_t a1 = PL_new_term_ref();
  term_t a2 = PL_new_term_ref();
  term_t t  = PL_new_term_ref();
  functor_t animal2;

  /* animal2 is a constant that may be bound to a global
     variable and re-used
  */
  animal2 = PL_new_functor(PL_new_atom("animal"), 2);

  PL_put_atom_chars(a1, "gnu");
  PL_put_integer(a2, 50);
  PL_cons_functor(t, animal2, a1, a2);
}

After this sequence, the term references a1 and a2 may be used for other purposes.

int PL_cons_functor_v(term_t -h, functor_t f, term_t a0)

Create a compound term like PL_cons_functor(), but a0 is an array of term references as returned by PL_new_term_refs(). The length of this array should match the number of arguments required by the functor.

int PL_cons_list(term_t -l, term_t +h, term_t +t)

Create a list (cons-) cell in l from the head h and tail t. The code below creates a list of atoms from a char **. The list is built tail-to-head. The PL_unify_*() functions can be used to build a list head-to-tail.

void
put_list(term_t l, int n, char **words)
{ term_t a = PL_new_term_ref();

  PL_put_nil(l);
  while( --n >= 0 )
  { PL_put_atom_chars(a, words[n]);
    PL_cons_list(l, a, l);
  }
}

Note that l can be redefined within a PL_cons_list call as shown here because operationally its old value is consumed before its new value is set.