- Documentation
- Reference manual
- Foreign Language Interface
- The Foreign Include File
- Argument Passing and Control
- Atoms and functors
- Analysing Terms via the Foreign Interface
- Constructing Terms
- PL_put_variable()
- PL_put_atom()
- PL_put_bool()
- PL_put_chars()
- PL_put_atom_chars()
- PL_put_string_chars()
- PL_put_string_nchars()
- PL_put_list_chars()
- PL_put_integer()
- PL_put_int64()
- PL_put_uint64()
- PL_put_pointer()
- PL_put_float()
- PL_put_functor()
- PL_put_list()
- PL_put_nil()
- PL_put_term()
- PL_cons_functor()
- PL_cons_functor_v()
- PL_cons_list()
- PL_put_dict()
- Unifying data
- Convenient functions to generate Prolog exceptions
- Foreign language wrapper support functions
- Serializing and deserializing Prolog terms
- BLOBS: Using atoms to store arbitrary binary data
- Exchanging GMP numbers
- Calling Prolog from C
- Discarding Data
- String buffering
- Foreign Code and Modules
- Prolog exceptions in foreign code
- Catching Signals (Software Interrupts)
- Miscellaneous
- Errors and warnings
- Environment Control from Foreign Code
- Querying Prolog
- Registering Foreign Predicates
- Foreign Code Hooks
- Storing foreign data
- Embedding SWI-Prolog in other applications
- The Foreign Include File
- Foreign Language Interface
- Packages
- Reference manual
TRUE
.
OPT_INT
int
OPT_INT64
int64_t
OPT_UINT64
uint64_t
OPT_SIZE
size_t
OPT_DOUBLE
double
OPT_STRING
char*
CVT_ALL|REP_UTF8|BUF_STACK|CVT_EXCEPTION
. The buffered
string must be guarded using PL_STRINGS_MARK()
and PL_STRINGS_RELEASE().OPT_ATOM
atom_t
OPT_TERM
term_t
The ISO standard demands that if an option is repeated the last occurance holds. This implies that PL_scan_options() must scan the option list to the end.
12.4.4.7 An example: defining write/1 in C
Figure 6 shows a simplified definition of write/1 to illustrate the described functions. This simplified version does not deal with operators. It is called display/1, because it mimics closely the behaviour of this Edinburgh predicate.
foreign_t pl_display(term_t t) { functor_t functor; int arity, len, n; char *s; switch( PL_term_type(t) ) { case PL_VARIABLE: case PL_ATOM: case PL_INTEGER: case PL_FLOAT: PL_get_chars(t, &s, CVT_ALL); if (! Sfprintf(Scurrent_output, "%s", s) ) PL_fail; break; case PL_STRING: if ( !PL_get_string_chars(t, &s, &len) && !Sfprintf(Scurrent_output, "\"%s\"", s) ) PL_fail; break; case PL_TERM: { term_t a = PL_new_term_ref(); if ( !PL_get_name_arity(t, &name, &arity) && !Sfprintf(Scurrent_output, "%s(", PL_atom_chars(name)) ) PL_fail for(n=1; n<=arity; n++) { if ( ! PL_get_arg(n, t, a) ) PL_fail; if ( n > 1 ) if ( ! Sfprintf(Scurrent_output, ", ") ) PL_fail; if ( !pl_display(a) ) PL_fail; } if ( !Sfprintf(Scurrent_output, ")") ) PL_fail; break; default: PL_fail; /* should not happen */ } } PL_succeed; }
12.4.5 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.218Older 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
orfalse
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 ofPL_ATOM
,PL_STRING
,PL_CODE_LIST
orPL_CHAR_LIST
. A representation is one ofREP_ISO_LATIN_1
,REP_UTF8
orREP_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.24.
- 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 arepresentation_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
, while on SWI-Prolog version 7 this is.
/2
.[|]
/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