- 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
- 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
The only defined value for flags is currently OPT_ALL
,
which causes this function to raise a domain error if an option is
passed that is not in specs. Default in SWI-Prolog is to
silently ignore unknown options, unless the Prolog flag iso
is true
. The opttype argument defines the type
(group) of the options, e.g., "write_option"
. Option types
are defined by the ISO standard. SWI-Prolog only uses this if OPT_ALL
is specified, to raise a domain_error
of the indicated type
if some option is unused. The type name is normally the name of the
predicate followed by
_option
or the name of a representative of a group of
predicates to which the options apply.
Defined option types and their corresponding pointer type are described below.
OPT_BOOL
int
- Convert the option value to a bool. This converts the values described
by PL_get_bool().
In addition, an option without a value (i.e., a plain atom that denotes
the option name) can act as a boolean
TRUE
. OPT_INT
int
OPT_INT64
int64_t
OPT_UINT64
uint64_t
OPT_SIZE
size_t
OPT_DOUBLE
double
- Numeric values of various types. Raises an error if the Prolog value cannot be represented by the C type.
OPT_STRING
char*
- Uses PL_get_chars()
using the flags
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
- Accepts an atom. Note that if the C function that implements the predicate wishes to keep hold of the atom after it returns it must use PL_register_atom().
OPT_TERM
term_t
- Accepts an arbitrary Prolog term. The term handle is scoped by the foreign predicate invocation. Terms can be preserved using PL_record().
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.3.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); Sprintf("%s", s); break; case PL_STRING: PL_get_string_chars(t, &s, &len); Sprintf("\"%s\"", s); break; case PL_TERM: { term_t a = PL_new_term_ref(); PL_get_name_arity(t, &name, &arity); Sprintf("%s(", PL_atom_chars(name)); for(n=1; n<=arity; n++) { PL_get_arg(n, t, a); if ( n > 1 ) Sprintf(", "); pl_display(a); } Sprintf(")"); break; default: PL_fail; /* should not happen */ } } PL_succeed; }
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.216Older 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.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 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