qpforeign.pl -- Quintus compatible foreign loader

This module defines a Quintus compatible foreign language interface based on the foreign_file/2 and foreign/3 declarations.

Predicates:

load_foreign_files: Load all foreign files defined with foreign_file/2 statement in the current module.
load_foreign_files(+Files, +Libs): Load specified foreign files, linking them with the given libraries
load_foreign_files(+SharedObject, +Files, +Libs): As load_foreign_files/2, but first tries to load `SharedObject'. If the SharedObject exists it is loaded using load_foreign_library/1. Otherwise it is first created with make_shared_object/3.
make_shared_object(+SharedObject, +Files, +Libs): Generate a wrapper and link it using plld to the given SharedObject.
make_foreign_wrapper_file(+Files, +OutBase): Generate wrapper for the named object files in OutBase.c.
make_foreign_wrapper_file(+Files): Generate wrapper for all declared object files in OutBase.c.

Example:

foreign_file('-lm', [sin/2]).
foreign(sin, c, sin(+float, [-float])).
:- load_foreign_files,
   abolish(foreign_file, 2),
   abolish(foreign, 3).

Supported types:

Spec	Prolog	C
integer	integer	long
float	float,integer	double
single	float,integer	single
string	atom,string	char *
atom	atom	atom identifier (type atomic)

NOTE This modules requires a correctly functioning swipl-ld and load_foreign_library/1 on your system. If this isn't the case use make_foreign_wrapper_file/[1,2] to generate a wrapper and use static embedding.

bug: - Only supports C-interface; - Insufficient checking for misusage.; - Documentation is too short and very outdated

make_wrappers(+PrologHeads, +Module, +OutStream)[private]
make_wrapper(+Stream, :PrologHead)[private]: Generates a C-wrapper function for the given foreign defined Prolog predicate. The wrapper is called _plw_<predname><arity>.
get_foreign_head(:Spec, -Func, -Head)[private]: Get 3rd argument of relevant foreign/3 clause. Seems there are two versions. In Quintus Spec was a predicate specification and in SICStus it seems to be a (C) function name.
cvt_name(+Type, +IO, -Suffix) is det[private]
make_C_header(+Stream, +WrapperName, +Arity)[private]: Write function-header for the wrapper. This is easy as the the return-type is always foreign_t and the arguments are always of type `term_t'. The arguments are simply named `a', `b', ...
make_C_decls(+Stream, :PrologHead)[private]: Writes the C variable declarations. If the return value is used a variable named `rval' is created. For each input parameter a C variable named i<argname> is created; for each output variable o<argname>.
make_C_prototype(+Stream, :PrologHead)[private]: If the function handles floats or doubles, make a prototype declaration for it to avoid unwanted conversions.
make_C_input_conversions(+Stream, :PrologHead)[private]: Generate the input checking and conversion code. Assumes boolean functions that take a Prolog term_t as first argument and a pointer to the requested C-type as a second argument. Function returns 0 if the conversion fails.
make_C_call(+Stream, :PrologHead, +CFunction)[private]: Generate the actual call to the foreign function. Input variables may be handed directly; output variables as a pointer to the o<var>, except for output-variables of type term.
make_C_wrapper_setup(+Stream)[private]: Call SP_WRAP_INIT() when running on SICStus. This supports SP_fail() and SP_raise_exception().
make_C_wrapper_check(+Stream)[private]: Call SP_WRAP_CHECK_STATE() when running on SICStus. This supports SP_fail() and SP_raise_exception().
make_C_output_conversions(+Stream, :PrologHead)[private]: Generate conversions for the output arguments and unify them with the Prolog term_t arguments.
make_C_init(+Stream, +InstallFunc, +InitFunc, +Module, +PredList)[private]: Generate an array of PL_extension structures, that may be used to create a statically linked image as well as through the PL_load_extensions() call.
Of the supported PL_FA_<FLAGS>, TRANSPARENT may be declared by looking at the transparent (meta_predivate) attribute of the predicate.
make_C_deinit(+Stream, +UninstallFunc, +DeInitFunc) is det[private]: Write the uninstall function
make_C_file_header(+Stream)[private]: Output the generic header declarations needed and some comments
load_foreign_files is det
load_foreign_files(:Files, +Libs) is det
load_foreign_files(+SharedObject, :Files, +Libs) is det: Calls make_foreign_wrapper_file(+File), compiles the wrapper and loads the predicates.
make_shared_object(+Object, :Files, +Libs) is det: Generate a wrapper and link it using plld to the given SharedObject.
make_foreign_wrapper_file(:OutFile) is det
make_foreign_wrapper_file(:Files, +OutFile) is det: Just output the wrapper file to the named .c file. May be used to prepare for static linking or the preparation of the native SWI-Prolog foreign-file.
make_foreign_resource_wrapper(:Resource, +ResBase, +FileBase): Create a wrapper-file for the given foreign resource
load_foreign_resource(:Resource, +Dir): Load a foreign module. First try to load from the same direcory as the Prolog file. Otherwise load using SWI-Prolog's default search path.
map_C_type(+Prolog, -C)[private]: Map Prolog interface type declarations into C types.

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

load_foreign_files is det
load_foreign_files(:Files, +Libs) is det
load_foreign_files(+SharedObject, :Files, +Libs) is det: Calls make_foreign_wrapper_file(+File), compiles the wrapper and loads the predicates.
load_foreign_files is det
load_foreign_files(:Files, +Libs) is det
load_foreign_files(+SharedObject, :Files, +Libs) is det: Calls make_foreign_wrapper_file(+File), compiles the wrapper and loads the predicates.
make_foreign_wrapper_file(:OutFile) is det
make_foreign_wrapper_file(:Files, +OutFile) is det: Just output the wrapper file to the named .c file. May be used to prepare for static linking or the preparation of the native SWI-Prolog foreign-file.