Function

Package

foreign-parser

Syntax

process-foreign-file source &key dff language preprocess preprocessor preprocessor-options case-sensitive =>

Arguments

source

One or more filenames.

dff

A filename.

language

:c .

preprocess

A boolean.

preprocessor

A string.

preprocessor-options

A string.

case-sensitive

See description.

Description

The process-foreign-file function takes a file or files of foreign declarations -- usually header files -- and parses them, producing `dff' files of Lisp calls to fli:define-foreign-function , fli:define-foreign-variable , fli:define-foreign-type , and so on, providing a Lisp interface to the foreign code.

source gives the name of the header files or file to be processed. The name of a file consists of source-file-name and source-file-type (typically .h ).

dff is an output file which will contain the Lisp foreign function definitions. The default value is nil , in which case the dff file will be source-file-name -dff.lisp . (See source , above.)

language specifies the language the header files are written in. Currently the supported languages are :c (standard K&R C header files) and :ansi-c .

preprocess , when non- nil , runs the preprocessor on the input files. The default value is t .

preprocessor is a string containing the pathname of the preprocessor program. By default this is the value of *preprocessor*.

preprocessor-options is a string containing command line options to be passed to the preprocessor if it is called. By default this is the value of *preprocessor-options*.

case-sensitive specifies whether to maintain case sensitivity in symbol names as in the source files. Values can be:

t -- the names of all Lisp functions and classes created are of the form |name|. This is the default value.

nil -- all foreign names are converted to uppercase and an error is signalled if any name clashes occur as a result of this conversion. For example, OneTwoTHREE becomes ONETWOTHREE .

:split-name -- attempts to split the name up into something sensible. For example, OneTwoTHREE becomes ONE-TWO-THREE .

:prefix -- changes lowercase to uppercase and concatenates the string with the string held in sys:*prefix-name-string* . For example, OneTwoTHREE becomes FOREIGN-ONETWOTHREE .

(list :user-routine function-name ) -- enables you to pass your own function for name formatting. Your function must take a string argument and return a string result. It is not advised to use destructive functions (e.g. nreverse ) as this may cause unusual side effects.

If case-sensitive takes any other value, names are not changed.

Note that in some cases the derived Lisp FLI definitions will not be quite correct, due to an ambiguity in C. char* can mean a pointer to a character, or a string, and in many cases you will want to pass a string. Therefore, process-foreign-file is useful for generating prototype FLI definitions, especially when there are many, but you do need to check the results when char* is used.

See also

register-module
*preprocessor*
*preprocessor-options*

 

Glossary

aggregate type

Any FLI type which is made up of other FLI types. This can be either an array of instances of a given FLI type, or a structured object.

Arrays, string, structure, and unions are all aggregate types Pointers are not aggregates.

callable function

A Lisp function, defined with the FLI macro define-foreign-callable , which can be called from a foreign language.

coerced pointer

A coerced pointer is a pointer that is dereferenced with the :type key in order to return the value pointed to as a different type than specified by the pointer type. For example, a pointer to a byte can be coerced to return a boolean on dereferencing.

FLI

The Foreign Language Interface, which consists of the macros, functions, types and variables defined in the fli package.

FLI code

Code written in Lisp using the functions, macros and types in the fli package.

FLI function

A function in the fli package used to interface Lisp with a foreign language.

FLI type

A data type specifier in the fli package used to define data objects that interface between Lisp and the foreign language. For example, a C long might be passed to LispWorks through an instance of the FLI type :long , from which it is transferred to a Lisp integer .

foreign callable function

See callable function .

foreign function

A Lisp function, defined using the FLI macro define-foreign-function , which calls a function written in a foreign language. A foreign function contains no body, consisting only of a name and a list of arguments. The function in the foreign language provides the body of the foreign function.

foreign language

A language to which Lisp can be interfaced using the FLI. Currently the FLI interfaces to C, and therefore also the Win32 API functions.

immediate type

See scalar type.

pointer

An FLI type consisting of an address and a type specification. A pointer normally points to the memory location of an instance of the type specified, although there might not actually be an allocated instance of the type at the pointer location.

A pointer is a boxed foreign object because it contains type information about the type it is pointing to (so that we can dereference it). In 'C' a pointer can be represented by a single register.

scalar type

An FLI type that is not an aggregate type. The FLI type maps directly to a single foreign type such as integer, floating point, enumeration and pointer.

wrapper

A description of the :wrapper FLI type which "wraps" around an object, allowing data to be passed to or obtained from the object as though it was of a different type. A wrapper can be viewed as a set of conversion functions defined on the object which are automatically invoked when the wrapped object is accessed.