The more-cffi Reference Manual

This is the more-cffi Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Fri Sep 15 06:05:33 2023 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 more-cffi

Extension of the CFFI project. A facility to wrap C bindings and write documentation.

Author

Hector Galbis Sanchis <>

License

The Unlicense

Dependencies
  • cffi (system).
  • alexandria (system).
  • iterate (system).
  • adp (system).
Source

more-cffi.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 more-cffi/more-cffi.asd

Source

more-cffi.asd.

Parent Component

more-cffi (system).

ASDF Systems

more-cffi.


3.1.2 more-cffi/package.lisp

Source

more-cffi.asd.

Parent Component

more-cffi (system).

Packages

more-cffi.


4 Packages

Packages are listed by definition order.


5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Macros

Macro: define-callback-definer (name &body arg-descriptors)

Define a macro named NAME to define callbacks. Each ARG-DESCRIPTOR must have the following syntax:

ARG-DESCRIPTOR ::= (SLOT-NAME [[slot-option]])
SLOT-OPTION ::= {:create expr | :return expr}1 | {:type type}1 | :virtual expr

To understand how this macro works we need to talk about C-arguments and Lisp-arguments. If you define a callback using CFFI:DEFCALLBACK the resulting function will receive C-args. That arguments should be translated to the Lisp world resulting on Lisp-arguments. Regarding the result value it will be first on the Lisp world and it should be translated to C. With this macro we can establish what are these arguments.

If you add an ARG-DESCRIPTOR you are indicating that your callback will have a C-arg named SLOT-NAME. Using :TYPE gives to that arg the specified type. Right now a Lisp-argument is created but no translation will be done. To do a custom translation you must use the :CREATE option. The associated expression must use SLOT-NAME and return the new value. But, if expression is NIL no Lisp-argument will be created. In this case you should use this value in the :CREATE expression of another ARG-DESCRIPTOR. In other words, the resulting callbacks will have one less argument.

You can use :RETURN instead of :CREATE to indicate SLOT-NAME is not a callback argument but a return value.

The last available option is :VIRTUAL. Using this option indicates that SLOT-NAME is not a C-arg but will be a Lisp arg. You should use :CREATE and an expression using the rest of SLOT-NAMEs.

Package

more-cffi.

Source

more-cffi.lisp.

Macro: define-foreign-struct (struct-type infix options &body slot-descriptors)

Define a wraper around the foreign struct (or union) STRUCT-TYPE. The symbol INFIX is used to generate the function names.
OPTIONS is a list of keywords that modify the way this macro works.

OPTIONS ::= [[OPTION]]
OPTION ::= :no-constructor | :no-destructor | :default-constructors | :default-readers | :default-writers | :include-invisibles

If :no-constructor is specified, then this macro will not define a constructor. In the same way, if :no-destructor is specified
no destructor will be defined. If :default-constructors is used each slot member has no need to define an explicit constructor. Instead,
a default initialization of the foreign slot is done (no translation). The same occurs with :default-readers and :default-writers when
defining the accessors. You will need to write every slot you want to define a constructor, destructor, reader or writer for. However,
if :include-invisibles is used that functions are defined even if you don’t specify the existence of that slot.

The SLOT-DESCRIPTIONS specify the translations of each foreign member. The systaxis is as follows:

SLOT-DESCRIPTIONS ::= (SLOT-NAME [[SLOT-OPTION]])
SLOT-OPTION ::= :name NAME | :type TYPE | :pointer POINTER | :virtual VIRTUAL | :constructor CONSTRUCTOR | :destructor DESTRUCTOR | :reader READER | :writer WRITER

The SLOT-NAME is a symbol denoting a foreign member of the struct STRUCT-TYPE (unless :virtual is used). The different options allow you to
specify the translations of each member:

- NAME: If used, that symbol will be used to create the accessors names.
- TYPE: If used, specify the Lisp type of SLOT-NAME.
- CONSTRUCTOR: This option is used to specify a translation when receiving a parameter in the constructor. If the expression after :constructor
is NIL or neither this option nor :default-constructors are used a constructor will not be defined. If this option is not used
but :default-constructors is, a parameter is still received to initialize the foreign member but no translation will be performed.
The expression after :constructor, if not NIL, must be a list where the first element is NIL or a list with a symbol. If NIL,
no argument will be received in the constructor. Otherwise, an argument with name the specified symbol will be received. In both cases,
the rest of elements of the list after :constructor must be expressions to initialize the member SLOT-NAME (using setf, for example).
It is possible to use the arguments specified from other :constructor options. Also, every SLOT-NAME is accessible from here.
- DESTRUCTOR: This must be an expression doing something with SLOT-NAME, like cffi:free-ing it.
- READER: This option works the same as :constructor about when an accessor is defined or not. Depending on the expression after :reader and
:default-readers the accessor may be defined or not. If the expression after :reader is not NIL, then it must be a list where the first
element is the lambda list of the accessor. The rest of elements are forms that must return the desired value. Every SLOT-NAME is accessible.
- WRITER: Same as :reader but indicates that the accessor is setf-able. The same rules apply here when using or not :default-writers.
The expression after :writer, if not NIL, must be a list where its first element is the lambda list of the setf function. So, a first
symbol is required always denoting the new value. The rest of elements are forms that should modify SLOT-NAME. Every SLOT-NAME is accessible.
- POINTER: Some structs have as a member another struct. You may want to use its pointer rather than the struct itself. To do that you only need to
use a non-NIL expression after :pointer.
- VIRTUAL: Using :virtual you can receive an additional parameter in the constructor, or create additional accessors.

Package

more-cffi.

Source

more-cffi.lisp.

Macro: defwith (name create destroy &optional arity docstring)

Define a macro named NAME. This new macro has the following syntax:

(NAME var-or-vars (&rest args) &body body)

When using this new macro CREATE is called with ARGS and the results are stored in VAR-OR-VARS. If VAR-OR-VARS
is a symbol, the rest of returned values are ignored. Afterwards, the BODY forms are evaluated. Finally,
DESTROY is called. The arguments used by DESTROY depends on ARITY. If ARITY is a list of non-negative integers
then they denote the arguments returned by CREATE to be used by DESTROY in the order they appear. For example, using the list (3 0 2) indicates that DESTROY will receive the fourth, first and third values returned by CREATE and in that order. If ARITY is just a non-negative integer then it indicates the number of arguments
to be used by DESTROY. For example, if 2 is specified, then DESTROY will receive the first 2 values returned by CREATE.

Package

more-cffi.

Source

more-cffi.lisp.


5.2 Internals


5.2.1 Ordinary functions

Function: check-callback-definer-arg-descriptor (arg-descriptor)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-callback-definer-arg-descriptors (arg-descriptors)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-constructor-option (constructor-value virtual-value slot-name)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-destructor-option (destructor-value slot-name)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-infix (infix)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-initform-option (constructorp constructor-value slot-name)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-options (options)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-reader-option (reader-value virtual-value slot-name)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-slot-descriptor (descriptor slot-names struct-type no-constructor-p no-destructor-p)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-slot-descriptors (descriptors slot-names struct-type no-constructor-p no-destructor-p)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-slot-name (slot-name virtualp slot-names struct-type)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-struct-type (struct-type)
Package

more-cffi.

Source

more-cffi.lisp.

Function: check-foreign-struct-writer-option (writer-value virtual-value slot-name)
Package

more-cffi.

Source

more-cffi.lisp.

Function: create-constructor-code (constructor-infos pointer-slots name-infos initform-infos struct-type enable-default-constructors enable-invisibles suffix)
Package

more-cffi.

Source

more-cffi.lisp.

Function: create-definer-code (name docstring create-arguments return-argument)
Package

more-cffi.

Source

more-cffi.lisp.

Function: create-destructor-code (destructor-infos pointer-slots struct-type suffix)
Package

more-cffi.

Source

more-cffi.lisp.

Function: create-readers-code (reader-infos pointer-slots name-infos struct-type enable-default-readers enable-invisibles prefix)
Package

more-cffi.

Source

more-cffi.lisp.

Function: create-with-code (suffix)
Package

more-cffi.

Source

more-cffi.lisp.

Function: create-writers-code (writer-infos pointer-slots name-infos struct-type enable-default-writers enable-invisibles prefix)
Package

more-cffi.

Source

more-cffi.lisp.

Function: define-foreign-struct-aux (struct-type infix options &rest slot-descriptors)
Package

more-cffi.

Source

more-cffi.lisp.

Function: exists-rec (syms l)

Return a non-nil value if there is some symbol from syms in l

Package

more-cffi.

Source

more-cffi.lisp.

Function: extract-create-arguments (arg-descriptors)

Return a list of lists with 5 elements: The slot name, the create expression, the type, whether is a foreign argument and whether is a lisp argument.

Package

more-cffi.

Source

more-cffi.lisp.

Function: extract-descriptor-info (slot-name descriptor keyword)

Return a list with four elements: The slot name, whether the slot is invisible, the option expr, whether the option is used.

Package

more-cffi.

Source

more-cffi.lisp.

Function: extract-return-argument (arg-descriptors)

Return a list with three elements: The slot name, the return expression and the type.

Package

more-cffi.

Source

more-cffi.lisp.

Function: find-slot-names (slot-names expr)

Return the list of symbols from slot-names that appear in expr

Package

more-cffi.

Source

more-cffi.lisp.

Function: memset (str c n)
Package

more-cffi.

Source

more-cffi.lisp.

Function: rec-substitute (assoc-symbols l)

Substitute every ocurrence of each symbol in assoc-symbol by its associated symbol. assoc-symbols is a property list.

Package

more-cffi.

Source

more-cffi.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   C   D   E   F   M   R  
Index Entry  Section

C
check-callback-definer-arg-descriptor: Private ordinary functions
check-callback-definer-arg-descriptors: Private ordinary functions
check-foreign-struct-constructor-option: Private ordinary functions
check-foreign-struct-destructor-option: Private ordinary functions
check-foreign-struct-infix: Private ordinary functions
check-foreign-struct-initform-option: Private ordinary functions
check-foreign-struct-options: Private ordinary functions
check-foreign-struct-reader-option: Private ordinary functions
check-foreign-struct-slot-descriptor: Private ordinary functions
check-foreign-struct-slot-descriptors: Private ordinary functions
check-foreign-struct-slot-name: Private ordinary functions
check-foreign-struct-struct-type: Private ordinary functions
check-foreign-struct-writer-option: Private ordinary functions
create-constructor-code: Private ordinary functions
create-definer-code: Private ordinary functions
create-destructor-code: Private ordinary functions
create-readers-code: Private ordinary functions
create-with-code: Private ordinary functions
create-writers-code: Private ordinary functions

D
define-callback-definer: Public macros
define-foreign-struct: Public macros
define-foreign-struct-aux: Private ordinary functions
defwith: Public macros

E
exists-rec: Private ordinary functions
extract-create-arguments: Private ordinary functions
extract-descriptor-info: Private ordinary functions
extract-return-argument: Private ordinary functions

F
find-slot-names: Private ordinary functions
Function, check-callback-definer-arg-descriptor: Private ordinary functions
Function, check-callback-definer-arg-descriptors: Private ordinary functions
Function, check-foreign-struct-constructor-option: Private ordinary functions
Function, check-foreign-struct-destructor-option: Private ordinary functions
Function, check-foreign-struct-infix: Private ordinary functions
Function, check-foreign-struct-initform-option: Private ordinary functions
Function, check-foreign-struct-options: Private ordinary functions
Function, check-foreign-struct-reader-option: Private ordinary functions
Function, check-foreign-struct-slot-descriptor: Private ordinary functions
Function, check-foreign-struct-slot-descriptors: Private ordinary functions
Function, check-foreign-struct-slot-name: Private ordinary functions
Function, check-foreign-struct-struct-type: Private ordinary functions
Function, check-foreign-struct-writer-option: Private ordinary functions
Function, create-constructor-code: Private ordinary functions
Function, create-definer-code: Private ordinary functions
Function, create-destructor-code: Private ordinary functions
Function, create-readers-code: Private ordinary functions
Function, create-with-code: Private ordinary functions
Function, create-writers-code: Private ordinary functions
Function, define-foreign-struct-aux: Private ordinary functions
Function, exists-rec: Private ordinary functions
Function, extract-create-arguments: Private ordinary functions
Function, extract-descriptor-info: Private ordinary functions
Function, extract-return-argument: Private ordinary functions
Function, find-slot-names: Private ordinary functions
Function, memset: Private ordinary functions
Function, rec-substitute: Private ordinary functions

M
Macro, define-callback-definer: Public macros
Macro, define-foreign-struct: Public macros
Macro, defwith: Public macros
memset: Private ordinary functions

R
rec-substitute: Private ordinary functions


A.3 Variables