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.

voidPL_put_variableterm_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. voidPL_put_atomterm_t -t, atom_t a Put an atom in the term reference from a handle. See also PL_new_atom and PL_atom_chars. voidPL_put_atom_charsterm_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. voidPL_put_string_charsterm_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. voidPL_put_string_ncharsterm_t -t, unsigned int 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 foreigndata. voidPL_put_list_charsterm_t -t, const char *chars Put a list of ASCII values in the term-reference. voidPL_put_integerterm_t -t, long i Put a Prolog integer in the term reference. voidPL_put_pointerterm_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. voidPL_put_floatterm_t -t, double f Put a floating-point value in the term-reference. voidPL_put_functorterm_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. voidPL_put_listterm_t -l Same as PL_put_functorl, PL_new_functor(PL_new_atom(".", 2)). voidPL_put_nilterm_t -l Same as PL_put_atom_chars"[]". voidPL_put_termterm_t -t1, term_t +t2 Make t1 point to the same term as t2. voidPL_cons_functorterm_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:

After this sequence, the term-references a1 and a2 may be used for other purposes. voidPL_cons_functor_vterm_t -h, functor_t f, term_t a0 Creates 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. voidPL_cons_listterm_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.

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.