3.1.1 Wrapsets

A wrapset is roughly an object that holds a representation of all the C types, constants, and functions what one is willing to “wrap”. Wrapset specifications as seen in See A Simple Example, are in fact a piece of Scheme code that creates a wrapset object, adds a number of C functions, types, etc. to be wrapped and then generates code for this wrapset. The code generation phase will be described in more details in See G-Wrap's Code Generation API.

Wrapset are instances of the <gw-wrapset> class. Since G-Wrap can generate code for more than one implementation (at least theoretically), each particular back-end defines a sub-class of this class. For instance, the Guile back-end defines the <gw-guile-wrapset> class in the (g-wrap guile) module.

When creating your own wrapset, you will have to create a sub-class of <gw-wrapset> with appropriate parameters, and then instantiate it. For instance, you may write:

(define-class <my-new-wrapset> (<gw-guile-wrapset>)
  #:id 'my-new-wrapset
  #:dependencies '(standard my-other-wrapset))

This creates a new wrapset for Guile, whose name is my-new-wrapset and which depends on the standard wrapset (see C Types Provided in the Standard Wrapset) and on the wrapset named my-other-wrapset. Each of the wrapset <my-new-wrapset> depends on must be visible at this point, typically by using the modules that define them:

(use-modules (g-wrap ws standard) ;; the standard wrapset
             (my-other-wrapset))

Of course, the module that defines <my-other-wrapset> does not need to be called (my-other-wrapset) but sticking to this naming scheme is usually a good idea.

The main methods that apply to <gw-wrapset> objects are listed below. Note that if you are simply willing to use G-Wrap’s high-level API (see G-Wrap's High-level API), you certainly do not need to know them, except initialize.

method: initialize (wrapset <gw-wrapset>) . args

Initialize wrapset, an newly created instance of <gw-wrapset>. This method is part of the GOOPS meta-object protocol (see Instance Creation Protocol in The GNU Guile Reference Manual).

Since you will actually always use your own sub-class of <gw-wrapset> (e.g. <my-new-wrapset>), you will want to specialize this method in order to perform initialization steps which are specific to your wrapset. In particular, this is where you will add new wrapped types, add wrapped functions, specify a Guile module name and a shared library name:

(define-method (initialize (ws <my-new-wrapset>) initargs)

  ;; Invoke the initialization method of the parent class, passing it
  ;; the #:module and #:shlib-path initialization
  ;; arguments.  Note that these two parameters are valid only if
  ;; <my-new-wrapset> is a subclass of <gw-guile-wrapset>.

  (next-method #:append '(#:module (my module)
                          #:shlib-path "libguile-my-module")
                        initargs)

  ;; Add a wrapped type.
  (add-type! ws ...)

  ;; and another one...
  (wrap-simple-type! ws ...)

  ;; and a wrapped function...
  (wrap-function! ws ...))

The tutorial contains more detailed examples of this, see See Creating a Wrapper Module.

method: name (wrapset <gw-wrapset>)

Return the name (a symbol) of wrapset wrapset. The name of a wrapset is the one that was passed as a #:id named parameter to that wrapset’s call to initialize.

method: language (wrapset <gw-wrapset>)

Return the language run-time (a symbol, e.g. guile) this wrapset is targeting.

method: wrapsets-depended-on (wrapset <gw-wrapset>)

Return a list of <gw-wrapset> instances representing the wrapsets wrapset depends on. This wrapsets correspond to those named in the #:dependencies named parameter that was passed when defining a sub-class of <gw-wrapset> (see above).

method: add-type! (ws <gw-wrapset>) (type <gw-type>)

Add the wrapped type type to the list of wrapped type of ws.

method: add-function! (ws <gw-wrapset>) (function <gw-function>)

Add the wrapped function function to the list of functions wrapped by ws.

method: add-constant! (ws <gw-wrapset>) (constant <gw-constant>)

Add the wrapped constant constant to the list of constants wrapped by ws.

method: for-each-type proc (ws <gw-wrapset>)

For each type (i.e. <gw-type> instance) wrapped by ws call proc (a procedure or generic function). The result is unspecified.