@c -*-texinfo-*-
@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2016 - 2021 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-gerror}
@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-gerror}
@deffn Syntax with-gerror 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-gerror 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   <clutter-actor>
@c   #<<gobject-class> <clutter-actor> 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
