+TITLE: cl-gobject-introspection-wrapper

This library converts the elements from GObject Introspection into Lisp-style definitions, based on [[https://github.com/andy128k/cl-gobject-introspection][cl-gobject-introspection]].

• Usage It's very easy to create a binding to a new GObject-based library via ~cl-gobject-introspection-wrapper~:

  1. Clone this repository into the folder ~local-projects~ under your Quicklisp installation root, then load the library with ~(ql:quickload :cl-gobject-introspection-wrapper)~.
  2. Create a package to store the auto-generated symbols from GIR. To avoid potential symbol conflicts, we write the ~defpackage~ with an empty ~:use~ clause:

     +BEGIN_SRC lisp

     (cl:defpackage gtk (:use))

     +END_SRC

  3. Use ~gir-wrapper:define-gir-namespace~ to generate all definitions from the GIR namespace:

     +BEGIN_SRC lisp

     (gir-wrapper:define-gir-namespace "Gtk")

     +END_SRC

     Note that all the definition symbols are exported automatically.

  4. If there exist some definitions whose name is not converted correctly or cause symbol conflicts according to [[Conversion Rules][Conversion Rules]], you can set up the special variable ~gir-wrapper:quoted-name-alist~ to specify the corresponding symbol for a definition. This could also exclude some definitions by specifying the symbols to ~cl:nil~ so that you can define them by hand later:

     +BEGIN_SRC lisp

     (cltl2:compiler-let (gir-wrapper:quoted-name-alist '((("TextBuffer" . "get_insert") . text-buffer-get-insert) ; Specify a symbol for class method ("CSET_a_2_z" . +cset-a-z-lower-case+) ; Specify a symbol for function, constant, enumeration, class, interface, struct, or function argument. (("Widget" . "is_sensitive") . cl:nil) ; Exclude a class method. ("String" . cl:nil))) ; Exclude a function, constant, enumeration, class, struct, or interface. (gir-wrapper:define-gir-namespace "Gtk" "4.0"))

     +END_SRC

     For portability consideration, we set the variable before ~gir-wrapper:define-gir-namespace~, then reset it after that, to avoid using the ~compiler-let~ in CLTL2:

     +BEGIN_SRC lisp

     (cl:eval-when (:execute :compile-toplevel :load-toplevel) (cl:setf gir-wrapper:quoted-name-alist '((("TextBuffer" . "get_insert") . text-buffer-get-insert) ("CSET_a_2_z" . +cset-a-z-lower-case+) (("Widget" . "is_sensitive") . cl:nil) ("Widget"))))

     (gir-wrapper:define-gir-namespace "Gtk" "4.0")

     (cl:eval-when (:execute :compile-toplevel :load-toplevel) (cl:setf gir-wrapper:quoted-name-alist '()))

     +END_SRC

• Conversion Rules In our rule definitions:
• ~*~ is a placeholder that stands for any type.
• ~[]~ denote an optional part of the name.
• ~/~ splits multiple optional words. Class | GIR definition | Lisp definition | |----------------+-------------------------------------------------------| | ~Foo~ | ~(progn (defun foop (instance)) (deftype foo ()))~ | | ~FOOBar~ | ~(progn (defun foo-bar-p (instance)) (deftype foo-bar ()))~ | Constructor | GIR definition | Lisp definition | |-------------------------------------------------------------------------------+---------------------------------------| | ~Foo new/create[_from/for/with_bar]( arg1, arg2, ...)~ | ~(defun make-foo (&key arg1 arg2 ...))~ | | ~Foo new/create_from/for/with_bar(* arg)~ if ~arg~ is used by another constructor | ~(defun make-foo (&key bar))~ | Note that the constructors with identical name after conversion will be merged into a single Lisp function, and which constructor to be called is determined by the arguments provided for this function. Function/Method In class/interface/struct ~Foo~: | GIR definition | Lisp definition | |------------------------------------+---------------------------------------------------| | ~void set_bar()~ | ~(defun (setf foo-bar) (value instance))~ | | ~ get_bar()~ | ~(defun foo-bar (instance)))~ | | ~ set_bar_is_baz~ | ~(defun (setf foo-bar[-baz]-p) (value instance))~ | | ~boolean [bar_]is_baz()~ | ~(defun foo[-bar]-baz-p (instance))~ | | ~boolean get[_bar_is]baz()~ | ~(defun foo[-bar]-baz-p (instance))~ | | ~boolean [bar]has/should/can_baz()~ | ~(defun foo-[bar-]has/should/can-baz-p (instance))~ | | ~ bar( arg1, arg2, ...)~ | ~(defun foo-bar (instance arg1 arg2 ...))~ | Constant | GIR definition | Lisp definition | |----------------+----------------------------------------------------------| | ~FOO_BAR = 123~ | ~(alexandria:define-constant +​foo-bar​+ 123 :test #'equal)~ | ** Enumeration | GIR definition | Lisp definition | |-----------------------+-----------------------------------------------------------------| | ~Foo { Bar, Baz, ... }~ | ~(progn (defconstant +​foo-bar​+ 0) (defconstant +​foo-baz​+ 1) ...)~ |