Customization Square - G-Golf customization functionality.
g-name-transform-exceptiong-name-transform-exception?g-name-transform-exception-addg-name-transform-exception-removeg-name-transform-exception-resetg-studly-caps-expand-token-exceptiong-studly-caps-expand-token-exception?g-studly-caps-expand-token-exception-addg-studly-caps-expand-token-exception-removeg-studly-caps-expand-token-exception-resetgi-strip-boolean-resultgi-strip-boolean-result?gi-strip-boolean-result-addgi-strip-boolean-result-removegi-strip-boolean-result-resetgi-method-short-name-skipgi-method-short-name-skip?gi-method-short-name-skip-allgi-method-short-name-skip-addgi-method-short-name-skip-removegi-method-short-name-skip-resetsyntax-name-protect-prefixsyntax-name-protect-prefix-setsyntax-name-protect-prefix-resetsyntax-name-protect-postfixsyntax-name-protect-postfix-setsyntax-name-protect-postfix-resetsyntax-name-protect-renamersyntax-name-protect-renamer-setsyntax-name-protect-renamer-resetsyntax-name-protect-reset
Welcome to the G-Golf Customization Square.
This section is organized per customization theme: (-) GI Name Transformation; (-) GI Strip Boolean Result; (-) GI Method Short Name Skip and (-) GI Syntax Name Protect.
In this corner of the square, we expose how you may customize G-Golf with respect to GI Name Transformation that occurs when importing GNOME libraries.
When G-Golf imports a GNOME library, its classes, properties, methods, functions, types and constants are renamed (See Naming Conventions), mainly to (a) avoid ‘Camel Case’, (b) surround class names by ‘<’ ‘>’ and (c) replace ‘_’ (underscore) occurrences using the ‘-’ (hyphen) character.
As the context of name transformation is GNOME in general, as opposed to
GI more specifically, (all) procedures involved are named using a
g- prefix.
Here is a summary of how the name transformation happens:
Returns an alist.
Obtains and returns the list of GI name transform exception (key
. value) pairs. Both key and value are strings.
The GI name transform exception alist is never empty, as it is
initialized and always kept to at least contain the '("GObject"
. "gobject") pair20.
As a consequence <gobject> (as opposed to <g-object> is
the G-Golf class name for the base class of the GLib Object
System.
This only affects the class name though - any procedure or method name
that comes from the "GObject" namespace is transformed using the
g-object prefix, as the upstream library prefix is
g_object.
Returns #t if key is a key member of the GI name transform
exception alist. Otherwise, it returns #f.
Returns nothing.
Add (remove) a (key . value) pair to (from) the GI name transform exception alist.
Returns nothing.
This procedure resets the GI name transform exception alist to its
default value - which is to contain the single '("GObject"
. "gobject") pair.
Returns an alist.
Obtains and returns the list of GI studly caps expand token exception
(key . value) pairs. Both key and value are
strings.
The GI studly caps expand token exception alist is never empty, as it is
initialized and always kept to at least contain the '("WebKit"
. "webkit") pair.
Returns #t if key is a key member of the GI studly caps
expand token exception alist. Otherwise, it returns #f.
Returns nothing.
Add (remove) a (key . value) pair to (from) the GI studly caps expand token exception alist.
Returns nothing.
This procedure resets the GI studly caps expand token exception alist to
its default value - which is to contain the single '("WebKit"
. "webkit") pair.
In this corner of the square, we expose how you may customize G-Golf
with respect to GI Strip Boolean Result, which addresses the
problem of typelib functions and methods that (1) have at least one
'inout or 'out argument(s) and (2) return either #t
or #f, solely to indicate that the function or method call was
successful or not.
The default G-Golf behavior, when there is at least one 'inout or
'out argument(s), is to return multiple values. The first
returned value is the function or method result, followed by the
'inout and 'out values, in order of appearance in the
function or method call.
G-Golf also offers - through a series of interfaces to get, check, add,
remove and reset a list of such function or methods names - to instead
elude the function or method returned value when it is #t and
raise an exception if the returned value is #f.
Here is a concrete example, for the "Clutter" namespace and
the clutter-color-from-string procedure:
,use (g-golf) (gi-import "Clutter") (clutter-color-from-string "Blue") ⇒ $2 = #t ⇒ $3 = (0 0 255 255)
And call it with an undefined color name:
(clutter-color-from-string "Bluee") ⇒ $4 = #f ⇒ $5 = (0 0 0 0)
Now, let’s add clutter-color-from-string to the list of GI
funtions and methods for which we wish to elude the result of the call
from the returned value(s), then experiment the above calls and see how
G-Golf changed the way it handles the results:
(gi-strip-boolean-result-add clutter-color-from-string) (clutter-color-from-string "Blue") ⇒ $7 = (0 0 255 255)
As expected, if we call it with an undefined color name, it will raise an exception21
(clutter-color-from-string "Bluee") -| ice-9/boot-9.scm:1686:16: In procedure raise-exception: -| clutter-color-from-string " failed." -| -| Entering a new prompt. Type `,bt' for a backtrace or `,q' to continue.
G-Golf default is that the list of GI funtions and methods for which to elude the result of the call from the returned value(s) is empty. It is a user responsibility to fill it appropriately, for each namespace they are importing.
Returns a (possibly empty) list of (symbol) name(s).
Obtains and returns the list of GI funtions and methods for which G-Golf will elude the result of the call from the returned value(s).
Returns #t if name is a member of the list of GI funtions
and methods for which G-Golf will elude the result of the call from the
returned value(s). Otherwise, it returns #f.
Add (remove) the names to (from) the list of GI funtions and methods for which G-Golf will elude the result of the call from the returned value(s).
Resets the list of GI funtions and methods for which G-Golf will elude the result of the call from the returned value(s) to the empty list.
In this corner of the square, we expose how you may customize G-Golf with respect to GI Method Short Name, more specifically, whether you wish to skip the method short name creation, and doing so individually or for all GI imported methods.
By default, as it imports a GI typelib, G-Golf creates a method short name for each imported method, obtained by dropping the container name (and its trailing hyphen) from the GI typelib method full/long name.
For example, the <gtk-label> class, which defines the
gtk-label-get-text method, would also define, using G-Golf’s
default settings, the get-text method. To be more precise, G-Golf
would create (if it does not exist) or reuse (if it exists) the
get-text generic function, make and add a method with its
specializer(s), in this case <gtk-label>.
Now, let’s add gtk-label-get-text to the list of the GI methods
for which we wish to skip the short name creation step. In this case, as
G-Golf imports the GtkLabel class, it would only create the
gtk-label-get-text method, but not the get-text method
anymore.
Returns a (possibly empty) list of (symbol) name(s).
Obtains and returns the list of GI method long name for which G-Golf will skip the method short name creation step.
Returns #t if name is a member of the list of GI method
long name for which G-Golf will skip the method short name creation
step. Otherwise, it returns #f.
Returns nothing.
Sets the GI method short name skip creation step to 'all.
Add (remove) the names to (from) the list of GI method long name for which G-Golf will skip the method short name creation step.
Resets the list of GI method long name for which G-Golf will skip the method short name creation step to the empty list.
In this corner of the square, we expose how you may customize G-Golf with respect to GI Syntax Name Protect.
When G-Golf creates a method short name, obtained by dropping the container name (and its trailing hyphen) from the GI typelib method full/long name, it may lead to a ‘name clash’, with an already defined procedure or syntax.
GI methods are added to their respective generic function, which is created if it does not already exist. When a generic function is created, G-Golf checks if the name is used, and when it is bound to a procedure, the procedure is ‘captured’ into an unspecialized method, which is added to the newly created generic function.
However, when the name is used but its variable value is a syntax, the above can’t be done and the name must be ‘protected’, which is what syntax-name->method-name does22, using a renamer, or by adding a prefix, a postfix or both to its (symbol) name argument.
G-Golf defines the following interfaces to get, set and reset the syntax name protect prefix, postfix and renamer, of which at least one must be set.
Respectively get, set and reset the syntax name protect
prefix. Its default value is #f.
Respectively get, set and reset the syntax name protect
postfix. Its default value is '_ (the symbol _).
Respectively get, set and reset the syntax name protect
renamer. Its default value is '_ (the symbol _).
The syntax name protect renamer, unless set to #f, must be
a procedure that takes a (symbol) name as its single argument, and
return a ‘none clashing’ (symbol) name.
This procedure will conveniently reset all three syntax name protect prefix, postfix and renamer to their default value, which are:
syntax-name-protect-prefix #fsyntax-name-protect-postfix '_(the symbol _) syntax-name-protect-renamer #f
This is the only name for which G-Golf maintains compatibility with Guile-GNOME (which has a long list of exceptions)..
Note that the raised exception message and
formatting depends on the version of guile you are using. Fwiw, this
example was produced using GNU Guile 3.0.8.
Users should normally not call this procedure - except for testing purposes, if/when they customize its default settings - it is appropriately and automatically called by G-Golf when importing a GI typelib.