9.4.2 Creating Prolog Terms

These functions create a term and store it as the value of an SP_term_ref, which must exist prior to the call. They return zero if the conversion fails (as far as failure can be detected), and a nonzero value otherwise, assigning to t the converted value.

Please note: here, the term `chars' refers to a code-list, rather than to a char-list.

int SP_read_from_string(SP_term_ref t, const char*string, SP_term_ref vals[])

Assigns to t the result of reading a term from the its textual representation string. Variables that occur in the term are bound to the corresponding term in val.

The SP_term_ref vector val is terminated by 0 (zero). val may be NULL, this is treated as an empty vector.

The variables in the term are ordered according to their first occurence during a depth first traversal in increasing argument order. That is, the same order as used by terms:term_variables_bag/2 (see Term Utilities). Variables that do not have a corresponding entry in vals are ignored. Entries in vals that do not correspond to a variable in the term are ignored.

The string should be encoded using the internal encoding of SICStus Prolog, the UTF-8 encoding (see WCX Concepts).

This example creates the term foo(X,42,42,X) (without error checking):

          SP_term_ref x = SP_new_term_ref();
          SP_term_ref y = SP_new_term_ref();
          SP_term_ref term = SP_new_term_ref();
          SP_term_ref vals[] = {x,y,x, 0/* zero termination */};
          
          SP_put_variable(x);
          SP_put_integer(y,42);
          
          SP_read_from_string(term, "foo(A,B,B,C).", vals);
          /* A corresponds to vals[0] (x),
             B to vals[1] (y),
             C to vals[2] (x).
             A and C therefore both are bound to
             the variable referred to by x.
             B is bound to the term referred to by y (42).
             So term refers to a term foo(X,42,42,X).
          */
     

See Calling Prolog from C, for an example of using SP_read_from_string() to call an arbitrary goal.

int SP_put_variable(SP_term_ref t)

Assigns to t a new Prolog variable.

int SP_put_integer(SP_term_ref t, long l)

Assigns to t a Prolog integer from a C long integer.

int SP_put_float(SP_term_ref t, double d)

Assigns to t a Prolog float from a C double.

int SP_put_atom(SP_term_ref t, SP_atom a)

Assigns to t a Prolog atom from a, which must be the canonical representation of a Prolog atom. (see Calling C from Prolog).

int SP_put_string(SP_term_ref t, char *name)

Assigns to t a Prolog atom from a C encoded string.

int SP_put_address(SP_term_ref t, void *pointer)

Assigns to t a Prolog integer representing a pointer.

int SP_put_list_chars(SP_term_ref t, SP_term_ref tail, char *s)

Assigns to t a Prolog code-list represented by the encoded string s, prepended to the value of tail.

int SP_put_list_n_chars(SP_term_ref t, SP_term_ref tail, size_t n, char *s)

Assigns to t a Prolog code-list represented by the first n bytes in encoded string s, prepended in front of the value of tail.

int SP_put_list_n_bytes(SP_term_ref t, SP_term_ref tail, size_t n, unsigned char *s)

Assigns to t a list of integers represented by the first n bytes of the byte array s, prepended to the value of tail.

int SP_put_integer_bytes(SP_term_ref tr, void *buf, size_t buf_size, int native)

Allows C to pass arbitrarily sized integers to SICStus. buf consists of the buf_size bytes of the twos complement representation of the integer. Less significant bytes are at lower indices. If native is non-zero, buf is instead assumed to be a pointer to the native buf_size byte integral type. Supported native sizes typically include two, four and eight (64bit) bytes. If the native size is not supported or if some other error occurs, zero is returned.

int SP_put_number_chars(SP_term_ref t, char *s)

Assigns to t a Prolog number by parsing the string in s.

int SP_put_functor(SP_term_ref t, SP_atom name, int arity)

Assigns to t a Prolog compound term with all the arguments unbound variables. If arity is 0, assigns the Prolog atom whose canonical representation is name to t. This is similar to calling functor/3 with the first argument unbound and the second and third arguments bound to an atom and an integer, respectively.

int SP_put_list(SP_term_ref t)

Assigns to t a Prolog list whose head and tail are both unbound variables.

int SP_cons_functor(SP_term_ref t, SP_atom name, int arity, SP_term_ref arg, ...)

Assigns to t a Prolog compound term whose arguments are the values of arg... If arity is 0, assigns the Prolog atom whose canonical representation is name to t. This is similar to calling =../2 with the first argument unbound and the second argument bound.

int SP_cons_list(SP_term_ref t, SP_term_ref head, SP_term_ref tail)

Assigns to t a Prolog list whose head and tail are the values of head and tail.