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().
- bool PL_put_variable(term_t
-t)
- Put a fresh variable in the term, resetting the term reference to its
initial state.220Older versions
created a variable on the global stack.
- bool 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().
- bool 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().
- bool PL_put_chars(term_t
-t, int flags, size_t len, const char *chars)
- New function to deal with setting a term from a
char* with
various encodings. The flags argument is a bitwise or
specifying the Prolog target type and the encoding of chars.
A Prolog type is one of PL_ATOM, PL_STRING,
PL_CODE_LIST or PL_CHAR_LIST. A representation
is one of
REP_ISO_LATIN_1, REP_UTF8 or REP_MB.
See
PL_get_chars()
for a definition of the representation types. If
len is -1 chars must be
zero-terminated and the length is computed from chars using strlen().
- bool 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.
- bool 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().
- bool 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
12.4.24.
- bool PL_put_list_chars(term_t
-t, const char *chars)
- Put a list of ASCII values in the term reference.
- bool PL_put_integer(term_t
-t, long i)
- Put a Prolog integer in the term reference.
- bool PL_put_int64(term_t
-t, int64_t i)
- Put a Prolog integer in the term reference.
- bool PL_put_uint64(term_t
-t, uint64_t i)
- Put a Prolog integer in the term reference. Note that unbounded integer
support is required for
uint64_t values with the highest
bit set to 1. Without unbounded integer support, too large values raise
a
representation_error exception.
- bool 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.
- bool PL_put_float(term_t
-t, double f)
- Put a floating-point value in the term reference.
- bool 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().
- bool PL_put_list(term_t
-l)
- As PL_put_functor(),
using the list-cell functor. Note that on classical Prolog systems or in
SWI-Prolog using the option
--traditional, this is
./2[|]/2
- bool PL_put_nil(term_t
-l)
- Put the list terminator constant in l. Always returns
TRUE. Note that in classical Prolog systems or in
SWI-Prolog using the option --traditional, this is the
same as
PL_put_atom_chars("[]").
See section 5.1.
- bool PL_put_term(term_t
-t1, term_t +t2)
- Make t1 point to the same term as t2. Under the
unusual condition that t2 is a fresh term reference this
function requires a global stack cell and may thus return FALSE
and leave a resource exception in the environment.
- bool 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.
- bool 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.
- bool 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. As with PL_cons_functor(),
the term references h and t may be used for other
purposes after the call to PL_cons_list().
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 instead 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);
}
}
- int PL_put_dict(term_t
-h, atom_t tag, size_t len, const atom_t *keys, term_t values)
- Create a dict from a tag and vector of atom-value pairs and
put the result in h. The dict's key is set by tag,
which may be
0 to leave the tag unbound. The keys
vector is a vector of atoms of at least len long. The values
is a term vector allocated using PL_new_term_refs()
of at least len long. This function returns TRUE
on success, FALSE on a resource error (leaving a resource
error exception in the environment),
-1 if some key or the tag is invalid and -2
if there are duplicate keys.
0 
