process-foreign-file

process-foreign-file Function

Summary

Parses foreign declarations to create Lisp FLI definition.

Package

foreign-parser

Signature

process-foreign-file source &key dff language preprocess preprocessor preprocessor-format-string preprocessor-options include-path case-sensitive package

Arguments

`source`⇩	One or more filenames.
`dff`⇩	A filename.
`language`⇩	A keyword.
`preprocess`⇩	A boolean.
`preprocessor`⇩	A string.
`preprocessor-format-string`⇩
	A string.
`preprocessor-options`⇩	A string.
`include-path`⇩	A list.
`case-sensitive`⇩	See description.
`package`⇩	A package designator or `nil`.

Description

The function process-foreign-file takes a file or files of foreign declarations — usually header files — and parses them, producing `dff' files of Lisp definitions using define-foreign-function, define-foreign-variable, 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. The default value is :ansi-c.

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

preprocessor-format-string should be a format string which is used to make a preprocessor command line. The format arguments are a pathname or string giving the preprocessor executable, a list of strings giving the preprocessor options, a list of strings giving macro names to define, a list of pathnames or strings contain the include path, and a source pathname. On Windows, the default contains options needed for VC++. The default is the value of *preprocessor-format-string*.

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*.

include-path should be a list of pathnames or strings that will be added as the include path for the preprocessor. The default is the value of *preprocessor-include-path*.

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`.
`(: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 (for example, nreverse) as this may cause unusual side effects.

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

package is used to generate an in-package form at the start of the output (dff) file. The name of the package designated by package is used in this form. The default value of package is the value of *package*.

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.