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

int PL_put_variable(term_t -t)

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

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

int 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_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().

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

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

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)

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, while on SWI-Prolog version 7 this is [|]/2.

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

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

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.

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.