@c -*-texinfo-*- @c This is part of the GNU G-Golf Reference Manual. @c Copyright (C) 2016 - 2025 Free Software Foundation, Inc. @c See the file g-golf.texi for copying conditions. @c @defindex tl @node Utilities @subsection Utilities G-Golf GObject Introspetion Utilities low level API.@* @subheading Procedures and Syntax @indentedblock @table @code @item @ref{gi-pointer-new} @item @ref{gi-pointer-inc} @item @ref{gi-attribute-iter-new} @item @ref{with-g-error} @item @ref{gi->scm} @item @ref{gi-boolean->scm} @item @ref{gi-string->scm} @item @ref{gi-n-string->scm} @item @ref{gi-strings->scm} @item @ref{gi-csv-string->scm} @item @ref{gi-pointer->scm} @item @ref{gi-n-pointer->scm} @item @ref{gi-pointers->scm} @item @ref{gi-n-gtype->scm} @item @ref{gi-glist->scm} @item @ref{gi-gslist->scm} @item @ref{scm->gi} @item @ref{scm->gi-boolean} @item @ref{scm->gi-string} @item @ref{scm->gi-n-string} @item @ref{scm->gi-strings} @item @ref{scm->gi-pointer} @item @ref{scm->gi-n-pointer} @item @ref{scm->gi-pointers} @item @ref{scm->gi-n-gtype} @item @ref{scm->gi-gslist} @end table @end indentedblock @subheading Types and Values @indentedblock @table @code @item @ref{%gi-pointer-size} @end table @end indentedblock @c @subheading Struct Hierarchy @c @indentedblock @c GIBaseInfo @* @c @ @ +--- GIRegisteredTypeInfo @* @c @ @ @ @ @ @ @ @ @ @ @ +--- GIEnumInfo @c @end indentedblock @subheading Description G-Golf GObject Introspection utilities low level API.@* @subheading Procedures and Syntax @anchor{gi-pointer-new} @deffn Procedure gi-pointer-new Returns a newly allocated (Glib) pointer. @end deffn @anchor{gi-pointer-inc} @deffn Procedure gi-pointer-inc pointer [#:offset %gi-pointer-size] Returns a foreign pointer object pointing to the address of @var{pointer} increased by @var{offset}. @end deffn @anchor{gi-attribute-iter-new} @deffn Procedure gi-attribute-iter-new Returns a pointer. Creates and returns a foreign pointer to a C struct for a @code{GIAttributeIter} (a C struct containg four pointers, initialized to @code{%null-pointer}). @end deffn @anchor{with-g-error} @deffn Syntax with-g-error var body Returns the result of the execution of @var{body}, or raises an exception. @var{var} must be an identifier. Evaluate @var{body} in a lexical environment where @var{var} is bound to a pointer to a newly allocated (and @samp{empty}) @code{GError}. @var{var} will always be freed. If no exception is raised, the result of the execution of @var{body} is returned. @c Here is an example, taken from the definition of @c @ref{g-irepository-require}, in the @code{(g-golf gi repository)} @c module: @c @lisp @c (define* (g-irepository-require namespace @c #:key (version #f) @c (repository %null-pointer)) @c (with-g-error g-error @c (g_irepository_require repository @c (string->pointer namespace) @c (if version @c (string->pointer version) @c %null-pointer) @c 0 @c g-error))) @c @end lisp @end deffn @anchor{gi->scm} @deffn Procedure gi->scm value type [cmpl #f] Returns the scheme representation of @var{value}. The @var{type}, a symbol name (also called a @code{type tag} or just a @code{tag} in the @code{GI} terminology) supported values are: @c @footnote{All (G-Golf) procedures that accept a GI tag as an argument @c will accept the tag as an integer (the GI representation) or a symbol @c (the scheme representation). All (G-Golf) procedures that return a @c tag will always return the scheme representation.} @indentedblock @table @code @item 'boolean Calls @ref{gi-boolean->scm}. @item 'string @itemx 'pointer Calls @ref{gi-string->scm} or @ref{gi-pointer->scm}. @item 'n-string @itemx 'n-pointer @itemx 'n-gtype Calls @ref{gi-n-string->scm}, @ref{gi-n-pointer->scm} or @ref{gi-n-gtype->scm}. The optional @var{cmpl} (complement) argument must be passed and set to the number of string(s), pointer(s) or gtype(s) contained in @var{value}, . @item 'strings @item 'pointers Calls @ref{gi-strings->scm} or @ref{gi-pointers->scm}. @item 'csv-string Calls @ref{gi-csv-string->scm}. @item 'glist @itemx 'gslist Calls @ref{gi-glist->scm} or @ref{gi-gslist->scm}, repsectively. @c Note: currently, the only supported item type is @code{object} (which @c implies that the @var{type} argument is a type description as documented @c below (see @ref{gi-glist->scm}, @ref{gi-gslist->scm}). G-Golf will of @c course provide translation for all other glist gslist item types, but in @c the mean time, if you encounter such a missing glist gslist item type, @c please @ref{Contact} us so we immediately fix that for you. @end table @end indentedblock @end deffn @anchor{gi-boolean->scm} @deffn Procedure gi-boolean->scm value Returns @code{#t} or @code{#f}. The GType of @var{value} must be a @code{gboolean}. @end deffn @anchor{gi-string->scm} @anchor{gi-pointer->scm} @deffn Procedure gi-string->scm value @deffnx Procedure gi-pointer->scm value Returns a string, a pointer or @code{#f} if @var{value} is the @code{%null-pointer}. The GType of @var{value} must be a @code{gchar*} or a @code{gpointer}. @end deffn @anchor{gi-n-string->scm} @anchor{gi-n-pointer->scm} @anchor{gi-n-gtype->scm} @deffn Procedure gi-n-string->scm value n-string @deffnx Procedure gi-n-pointer->scm value n-pointer @deffnx Procedure gi-n-gtype->scm value n-gtype Returns a (possibly empty list) of string(s), pointer(s) or GType(s). The GType of @var{value} must be a @code{gchar**}, a @code{gpointer[]} or a @code{GType[]}. The @var{n-string}, @var{n-pointer} and @var{n-gtype} argument must be the length of the @var{value} array. @end deffn @anchor{gi-strings->scm} @anchor{gi-pointers->scm} @deffn Procedure gi-strings->scm value @deffnx Procedure gi-pointers->scm value Returns a (possibly empty) list of strings or pointer. The GType of @var{value} must be a @code{gchar**} or @code{gpointer[]}. The array must be NULL terminated. @end deffn @anchor{gi-csv-string->scm} @deffn Procedure gi-csv-string->scm value Returns a list of string(s) or @code{#f} if @var{value} is the @code{%null-pointer}. The GType of @var{value} is @code{gchar*}. Unless @code{#f}, the list of string(s) is obtained by splitting the (comma separated value) string pointed to by @var{value } using using @code{#\,} as the @code{char-pred}. @end deffn @anchor{gi-glist->scm} @anchor{gi-gslist->scm} @deffn Procedure gi-glist->scm g-list @deffnx Procedure gi-gslist->scm g-slist Returns a (possibly empty) list. Obtains and returns a (possibly empty) list of the pointers stored in the @code{data} field of each element of @var{g-list} or @var{g-slist}. @c The @var{type-desc} is a list composed of the @var{g-list} or @c @var{g-slist} type tag, @code{'interface} if the list element @c param-tag is interface or #f otherwise, the interface description (if @c the previous is not #f), followed by a boolean which is #t if the @c g-list (g-slist) @code{data} field is a pointer, #f otherwise. @c An interface description is a list composed of the interface GI type @c tag, the G-Golf type name, the G-Golf type, the g-type id and a @c boolean which is #t if the last three values have been @c verified@footnote{It happens, due to the (unspecified) order at which @c @samp{things} are imported from a GI typelib, that a G-Golf class or @c instance hasn't been finalized when the procedure or method is being @c imported, hence these must be verified, which is done at the first @c (and only once) procedure or method call.}. As an example, here is @c the type description of the returned value for @c @code{clutter-actor-get-children}: @c @lisp @c (glist @c interface @c (object @c @c #< 561c2e9c2960> @c 94679044057632 @c #f) @c #f) @c @end lisp @end deffn @anchor{scm->gi} @deffn Procedure scm->gi value type [cmpl #f] Returns the GI representation of @var{value}. The @var{type}, a symbol name (also called a @code{type tag} or just a @code{tag} in the @code{GI} terminology) supported values are: @indentedblock @table @code @item 'boolean Calls @ref{scm->gi-boolean}. @item 'string @itemx 'pointer Calls @ref{scm->gi-string} or @ref{scm->gi-pointer}. @item 'n-string @itemx 'n-pointer @itemx 'n-gtype Calls @ref{scm->gi-n-string}, @ref{scm->gi-n-pointer} or @ref{scm->gi-n-gtype}. The optional @var{cmpl} (complement) argument may be passed and set to the number of string(s), pointer(s) or gtype(s) contained in @var{value}. @item 'strings @item 'pointers Calls @ref{scm->gi-strings} or @ref{scm->gi-pointers}. @c @item 'glist @item 'gslist Calls @ref{scm->gi-gslist}. @end table @end indentedblock @end deffn @anchor{scm->gi-boolean} @deffn Procedure scm->gi-boolean value Returns @code{0} if @var{value} is @code{#f}, otherwise, it returns @code{1}. @end deffn @anchor{scm->gi-string} @anchor{scm->gi-pointer} @deffn Procedure scm->gi-string value @deffnx Procedure scm->gi-pointer value Returns a pointer. If @var{value} is @code{#f}, it returns @code{%null-pointer}. Otherwise, it returns a pointer to the string in @var{value} or @var{value}. @end deffn @anchor{scm->gi-n-string} @anchor{scm->gi-strings} @deffn Procedure scm->gi-n-string value [n-string #f] @deffnx Procedure scm->gi-strings value Returns two values. If @var{value} is the empty list, it returns @code{%null-pointer} and an empty list. Otherwise, it returns a pointer to an array of pointer(s) to the string(s) in @var{value} and a list of the @samp{inner} string pointer(s). It is the caller's responsibility to maintain a reference to those inner pointer(s), until the array @samp{itself} (the first returned value) is no longer needed/used. The array returned by @ref{scm->gi-strings} is @code{NULL} terminated, where as the array returned by @ref{scm->gi-n-string} is not. @end deffn @anchor{scm->gi-n-pointer} @anchor{scm->gi-n-gtype} @deffn Procedure scm->gi-n-pointer value [n-pointer #f] @deffnx Procedure scm->gi-n-gtype value [n-gtype #f] Returns a pointer. If @var{value} is an empty list, it returns @code{%null-pointer}. Otherwise, it returns a pointer to an array the pointer(s) or GType(s) in @var{value}. The returned array is not @code{NULL} nor @code{0-} terminated. @end deffn @anchor{scm->gi-pointers} @deffn Procedure scm->gi-pointers value Returns a pointer. If @var{value} is an empty list, it returns @code{%null-pointer}. Otherwise, it returns a pointer to an array the pointer(s) in @var{value}. The returned array is @code{NULL} terminated. @end deffn @anchor{scm->gi-gslist} @deffn Procedure scm->gi-gslist value Returns a pointer. If @var{value} is an empty list, it returns @code{%null-pointer}. Otherwise, it returns a pointer to a @code{GSList}, with its element's data being (in order), the pointer(s) in @var{value}. @end deffn @subheading Types and Values @anchor{%gi-pointer-size} @defvar %gi-pointer-size The size (the number of bytes) that a (Glib) pointer occupies in memory (which is architecture dependent). @end defvar