TRUE if t1 and t2 refer to
physically the same compound term and FALSE otherwise.
In some applications it is useful to store and retrieve Prolog terms from C code. For example, the XPCE graphical environment does this for storing arbitrary Prolog data as slot-data of XPCE objects.
Please note that the returned handles have no meaning at the Prolog level and the recorded terms are not visible from Prolog. The functions PL_recorded() and PL_erase() are the only functions that can operate on the stored term.
Two groups of functions are provided. The first group (PL_record() and friends) store Prolog terms on the Prolog heap for retrieval during the same session. These functions are also used by recorda/3 and friends. The recorded database may be used to communicate Prolog terms between threads.
(record_t)0.(record_t)0 if the record is an
external record (see PL_record_external()).TRUE
on success, and FALSE if there is not enough space on the
stack to accommodate the term. See also PL_record()
and PL_erase().The second group (headed by PL_record_external()) provides the same functionality, but the returned data has properties that enable storing the data on an external device. It has been designed for fast and compact storage of Prolog terms in an external database. Here are the main features:
NULL if the term contains blobs that cannot be
serialized, such as streams.
These functions are used to implement library library(fastrw)
as well as for storing Prolog terms in external databases such as
BerkeleyDB (library library(bdb)) or RocksDB. The
representation is optimized for plain atoms and numbers.
Records that are used only in the same Prolog process should use PL_record() as this can represent any term, is more compact and faster.
The returned string may be copied. Note that the string may contain null bytes and is not null terminated. The length in bytes is returned in len. After copying, the returned string may be discarded using PL_erase_external().
PL_recorded_external() is used to copy the term represented in the data back to the Prolog stack. PL_recorded_external() can be used on the returned string as well as on a copy.
On success this function returns TRUE. On failure FALSE
is returned and an exception is left in the environment that describes
the reason of failure. See PL_exception().
This predicate bypasses creating a Prolog callback environment and is faster than setting up a call to assertz/1. It may be used together with PL_chars_to_term(), but the typical use case will create a number of clauses for the same predicate. The fastest way to achieve this is by creating a term that represents the invariable structure of the desired clauses using variables for the variable sub terms. Now we can loop over the data, binding the variables, asserting the term and undoing the bindings. Below is an example loading words from a file that contains a word per line.
#include <SWI-Prolog.h>
#include <stdio.h>
#include <string.h>
#define MAXWLEN 256
static foreign_t
load_words(term_t name)
{ char *fn;
if ( PL_get_file_name(name, &fn, PL_FILE_READ) )
{ FILE *fd = fopen(fn, "r");
char word[MAXWLEN];
module_t m = PL_new_module(PL_new_atom("words"));
term_t cl = PL_new_term_ref();
term_t w = PL_new_term_ref();
fid_t fid;
if ( !PL_unify_term(cl, PL_FUNCTOR_CHARS, "word", 1, PL_TERM, w) )
return FALSE;
if ( (fid = PL_open_foreign_frame()) )
{ while(fgets(word, sizeof word, fd))
{ size_t len;
if ( (len=strlen(word)) )
{ word[len-1] = '\0';
if ( !PL_unify_chars(w, PL_ATOM|REP_MB, (size_t)-1, word) ||
!PL_assert(cl, m, 0) )
return FALSE;
PL_rewind_foreign_frame(fid);
}
}
PL_close_foreign_frame(fid);
}
fclose(fd);
return TRUE;
}
return FALSE;
}
install_t
install(void)
{ PL_register_foreign("load_words", 1, load_words, 0);
}
The function PL_get_file_name() provides access to Prolog filenames and its file-search mechanism described with absolute_file_name/3. Its existence is motivated to realise a uniform interface to deal with file properties, search, naming conventions, etc., from foreign code.
BUF_STACK, which is popped upon return from the
foreign predicate to Prolog. Conversion from the internal UNICODE
encoding is done using standard C library functions. flags is
a bit-mask controlling the conversion process. On failure, PL_FILE_NOERRORS
controls whether an exception is raised. Options are:
PL_FILE_ABSOLUTEPL_FILE_OSPATH\/PL_FILE_SEARCHPL_FILE_EXISTPL_FILE_READPL_FILE_WRITEPL_FILE_EXECUTEPL_FILE_NOERRORSPL_FILE_OSPATH must be provided to fetch a
filename in OS native (e.g., C:\x\y) notation.
Foreign code can set or create Prolog flags using PL_set_prolog_flag(). See set_prolog_flag/2 and create_prolog_flag/3. To retrieve the value of a flag you can use PL_current_prolog_flag().
TRUE on success and FALSE on failure. This
function can be called before PL_initialise(),
making the flag available to the Prolog startup code.
PL_BOOLtrue or false) flag. The
argument must be an int.PL_ATOMconst char *.PL_INTEGERintptr_t *.atom_t (see current_prolog_flag/2).
type specifies the kind of value to be retrieved, it is one
of the values below. value is a pointer to a location where
to store the value. The user is responsible for making sure this memory
location is of the appropriate size/type (see the returned types below
to determine the size/type). The function returns TRUE on
success and FALSE on failure.
PL_ATOMatom. The returned value
is an atom handle of type atom_t.PL_INTEGERinteger. The returned
value is an integer of type int64_t.PL_FLOATfloat. The returned value
is a floating point number of type double.PL_TERMterm. The returned value
is a term handle of type term_t.
FALSE if the delay list is empty (and answer is well
defined) and TRUE if the delay list is not empty. If dl
is 0 no list is instantiated, while the return value is the same. This
allows for testing that an answer is undefined as below.
if ( PL_get_delay_list(0) )
<undefined>
else
<normal answer>
For now, we consider the content of the list elements opaque. See
boot/tabling.pl for examples.