5.6 Defining Bindings

► |  | The Racket Foreign Interface

1 | Overview
2 | Loading Foreign Libraries
3 | C Types
4 | Pointer Functions
5 | Derived Utilities
6 | Miscellaneous Support
7 | Unexported Primitive Functions
| Bibliography
| Index

▼ | 5 | Derived Utilities

5.1 | Safe Homogenous Vectors
5.2 | Safe C Vectors
5.3 | Tagged C Pointer Types
5.4 | Serializable C Struct Types
5.5 | Static Callout and Callback Cores
5.6 | Defining Bindings
5.7 | Allocation and Finalization
5.8 | Custodian Shutdown Registration
5.9 | Atomic Execution
5.10 | Speculatively Atomic Execution
5.11 | Thread Scheduling
5.12 | Ports
5.13 | Process-Wide and Place-Wide Registration
5.14 | Operating System Threads
5.15 | Garbage Collection Callbacks
5.16 | Objective-C FFI
5.17 | Cocoa Foundation
5.18 | COM (Common Object Model)
5.19 | File Security-Guard Checks
5.20 | Windows API Helpers
5.21 | Virtual Machine Primitives
5.22 | Declaring Foreign Libraries Needed at Run Time

► | 5.6 | Defining Bindings

5.6.1 | FFI Identifier Conventions

On this page:

define-ffi-definer
make-not-available
provide-protected
5.6.1 FFI Identifier Conventions
convention: hyphen->underscore
convention: hyphen->camel Case
convention: hyphen->Pascal Case
convention: hyphen->camelcase

Racket
top contents ← prev up next →

### 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

Binds define-id as a definition form to extract bindings from the library produced by ffi-lib-expr. The syntax of define-id is

> > (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

> (define-gtk gtk_rc_parse (_fun _path -> _void))

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?

Returns a procedure that takes any number of arguments, including keyword arguments, and raises and exn:fail:unsupported exception from name. This function is intended for using with #:make-fail or #:default-make-fail in define-ffi-definer

Changed in version 8.3.0.5 of package base: Added support for keyword arguments.
Changed in version 9.2.0.2: Changed to raise exn:fail:unsupported.

> syntax (provide-protected provide-spec ...)

Equivalent to (provide (protect-out provide-spec ...)). The provide-protected identifier is useful with #:provide in define-ffi-definer.

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

> syntax convention:hyphen->underscore

A convention that converts hyphens in an identifier to underscores. For example, the identifier underscore-variable will transform to underscore_variable.

> (define-ffi-definer define-unlib underscore-lib
> #:make-c-id convention:hyphen->underscore)
> (define-unlib underscore-variable (_fun -> _void))

> syntax convention:hyphen->camelCase

Similar to convention:hyphen->underscore, but converts the identifier to “camelCase,” following the string-downcase and string-titlecase functions. For example, the identifier camel-case-variable (or even cAmeL-CAsE-vaRiaBlE) will transform to camelCaseVariable.

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

> syntax convention:hyphen->PascalCase

Like convention:hyphen->camelCase, but converts the identifier to “PascalCase,” following the string-titlecase function. For example, the identifier pascal-case-variable (or even paSCaL-CAsE-vaRiaBlE) will transform to PascalCaseVariable.

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

> syntax convention:hyphen->camelcase

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

top contents ← prev up next →