5.6.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. The new variable lives on the global stack. Note that the initial variable lives on the local stack and is lost after a write to the term-references. After using this function, the variable will continue to live.

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_string_from_atom().

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

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

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

Put a string in the term-reference. The data will be copied.

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

Put a list of ASCII values in the term-reference.

void PL_put_integer(term_t -t, long i)

Put a Prolog integer in the term reference.

void 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.

void PL_put_float(term_t -t, double f)

Put a floating-point value in the term-reference.

void 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().

void PL_put_list(term_t -l)

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

void PL_put_nil(term_t -l)

Same as PL_put_atom_chars("[]").

void PL_put_term(term_t -t1, term_t +t2)

Make t1 point to the same term as t2.

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

Create a term, whose arguments are filled from 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_put_atom_chars(a1, "gnu"); PL_put_integer(a2, 50); PL_cons_functor(t, PL_new_functor(PL_new_atom("animal"), 2), a1, a2);

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

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

Create a list (cons-) cell in l from the head and tail. 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_put_list(l, a, l); } }