5.6 Defining Bindings
(require ffi/unsafe/define) | package: base |
syntax
(define-ffi-definer define-id ffi-lib-expr option ...)
option = #:provide provide-id | #:define core-define-id | #:default-make-fail default-make-fail-expr | #:make-c-id make-c-id
(define-id id type-expr bind-option ...)
bind-option = #:c-id c-id | #:c-id (unquote c-id-expr) | #:wrap wrap-expr | #:make-fail make-fail-expr | #:fail fail-expr | #:variable
A define-id form binds id by extracting a binding with the foreign name c-id from the library produced by ffi-lib-expr, where c-id defaults to id. The other options support further wrapping and configuration:
Before the extracted result is bound as id, it is passed to the result of wrap-expr, which defaults to values. Expressions such as (allocator delete) or (deallocator) are useful as wrap-exprs.
The #:make-fail and #:fail options are mutually exclusive; if make-fail-expr is provided, it is applied to 'id to obtain the last argument to get-ffi-obj; if fail-expr is provided, it is supplied directly as the last argument to get-ffi-obj. The make-not-available function is useful as make-fail-expr to cause a use of id to report an error when it is applied if c-id was not found in the foreign library.
If the #:c-id option is provided with an identifier argument c-id, then c-id is used as the foreign name. If the argument has the form (unquote c-id-expr), then the foreign name is the result of evaluating c-id-expr. In either case, the #:make-c-id argument is ignored.
If the #:c-id option is absent, the foreign name is based on id. If define-id was defined with the #:make-c-id option, it computes the foreign name using an ffi identifier convention, such as converting hyphens to underscores or camel case. Several conventions are provided by ffi/unsafe/define/conventions. If #:make-c-id was absent, then id is used as the foreign name.
If the #:variable keyword is given, then make-c-parameter is used instead of get-ffi-obj to get the foreign value.
If provide-id is provided to define-ffi-definer, then define-id also provides its binding using provide-id. The provide-protected form is usually a good choice for provide-id.
If core-define-id is provided to define-ffi-definer, then core-define-id is used in place of define in the expansion of define-id for each binding.
If default-make-fail-expr is provided to define-ffi-definer, it serves as the default #:make-fail value for define-id.
For example,
(define-ffi-definer define-gtk gtk-lib)
binds define-gtk to extract FFI bindings from gtk-lib, so that gtk_rc_parse could be bound as
If gtk_rc_parse is not found, then define-gtk reports an error immediately. If define-gtk is instead defined with
(define-ffi-definer define-gtk gtk-lib #:default-make-fail make-not-available)
then if gtk_rc_parse is not found in gtk-lib, an error is reported only when gtk_rc_parse is called.
Changed in version 6.9.0.5 of package base: Added #:make-c-id parameter.
Changed in version 8.4.0.5: Added #:variable option.
Added unquote variant of
#:c-id argument.
procedure
(make-not-available name) → procedure?
name : symbol?
Changed in version 8.3.0.5 of package base: Added support for keyword arguments.
syntax
(provide-protected provide-spec ...)
5.6.1 FFI Identifier Conventions
(require ffi/unsafe/define/conventions) | package: base |
This module provides several FFI identifier conventions for use with #:make-c-id in define-ffi-definer. A FFI identifier convention is any syntax transformer that converts one identifier to another.
Added in version 6.9.0.5 of package base.
(define-ffi-definer define-unlib underscore-lib #:make-c-id convention:hyphen->underscore) (define-unlib underscore-variable (_fun -> _void))
(define-ffi-definer define-calib camel-lib #:make-c-id convention:hyphen->camelCase) (define-calib camel-case-variable (_fun -> _void))
Added in version 8.11.1.8 of package base.
(define-ffi-definer define-palib pascal-lib #:make-c-id convention:hyphen->PascalCase) (define-palib pascal-case-variable (_fun -> _void))
Added in version 8.11.1.8 of package base.
NOTE: This convention is deprecated; use convention:hyphen->PascalCase, instead. This convention unfortunately converts to “PascalCase” as opposed to what its name suggests.
Changed in version 8.11.1.8 of package base: Deprecated due to the wrong behavior.