@c -*-texinfo-*-
@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2016 - 2022 Free Software Foundation, Inc.
@c See the file g-golf.texi for copying conditions.


@node Utilities_
@subsection Utilities


@subheading Procedures

@indentedblock
@table @code
@item @ref{g-studly-caps-expand}
@item @ref{g-name->name}
@item @ref{g-name->class-name}
@item @ref{g-name->short-name}
@item @ref{class-name->name}
@item @ref{class-name->g-name}
@item @ref{name->g-name}
@item @ref{syntax-name->method-name}
@item @ref{gi-type-tag->ffi}
@item @ref{gi-type-tag->init-val}
@end table
@end indentedblock


@c @subheading Variables

@c @indentedblock
@c @table @code
@c @end table
@c @end indentedblock


@subheading Description

G-Golf utilities low level API.@*


@subheading Procedures


@anchor{g-studly-caps-expand}
@deffn Procedure g-studly-caps-expand str

Returns a string@footnote{This procedure, as well as @ref{g-name->name}
and @ref{g-name->class-name} come from @uref{@value{UGG}, Guile-GNOME},
where there are named @code{GStudlyCapsExpand},
@code{gtype-name->scm-name} and @code{gtype-name->class-name}.@*@*In
G-Golf, these procedures are also be used to transform other (GObject
Introspection) names, such as function names, hence they use the
@code{g-name->} prefix instead}.

Expand the StudlyCaps @var{str} to a more schemey-form, according to the
conventions of GLib libraries. For example:

@lisp
(g-studly-caps-expand "GStudlyCapsExpand")
@result{} "g-studly-caps-expand"

(g-studly-caps-expand "GSource")
@result{} "g-source"

(g-studly-caps-expand "GtkIMContext")
@result{} "im-context"
@end lisp

G-Golf slightly modified the original code to also allow the possibility
to specially treat the @var{str} (expanded) tokens, such as:

@lisp
(g-studly-caps-expand "WebKitWebContext")
@result{} "webkit-web-context" ;; not "web-kit-web-context"
@end lisp

The list of StudlyCaps token exception pairs are maintained in the
@ref{g-studly-caps-expand-token-exception} alist.
@end deffn


@anchor{g-name->name}
@anchor{g-name->class-name}
@deffn Procedure g-name->name g-name [as-string? #f]
@deffnx Procedure g-name->class-name g-name [as-string? #f]

Return a symbol name, or a string name if @var{as-string} is #t.

@ref{g-name->name} first obtains, the scheme representation of
@var{g-name}, as a string, by looking for a possible entry in
@ref{g-name-transform-exception}, or if it failed, by calling
@ref{g-studly-caps-expand}.

If the optional @var{as-string} argument is #t, it returns
that string, otherwise, it calls and returns the result of
@code{string->symbol}.

@ref{g-name->class-name} calls @ref{g-name->name}, surrounds the result
using @code{#\<} and @code{#\>} characters then either return that
string, if @var{as-string?} is @code{#t}, otherwise it calls and returns
the result of @code{string->symbol}:

@lisp
(g-name->class-name "GtkWindow")
@result{} <gtk-window>
@end lisp
@end deffn


@anchor{g-name->short-name}
@deffn Procedure g-name->short-name g-name g-class-name [as-string? #f]

Return a symbol name, or a string name if @var{as-string} is #t.

Obtains and returns a (method) short name for @var{g-name}. It first
obtains the @abbr{sro, scheme representation of} both @var{g-name} and
@var{g-class-name} (which is expected to be the upstream method
container (class) name), as a string, then:

@itemize
@item
if the sro @var{g-class-name} is (fully) contained in the sro
@var{g-name}, it drops the sro @var{g-class-name} prefix - or its plural
form - and its trailing #\- (hiphen) delimiter from the sro
@var{g-name};
@ifhtml
@*@*
@end ifhtml

@item
otherwise, it drops the longest common sro string prefix it finds.
@end itemize

If the optional @var{as-string} argument is #t, it returns
that string, otherwise, it calls and returns the result of
@code{string->symbol}.

To illustrate, here is an example for each of the three above exposed
cases:

@lisp
(g-name->shortname "gdk_event_get_event_type" "GdkEvent")
@result{} get-event-type

(g-name->shortname "gdk_events_get_angle" "GdkEvent")
@result{} get-angle

(g-name->short-name "gtk_drag_begin" "GtkWidget")
@result{} drag-begin
@end lisp
@end deffn


@anchor{class-name->name}
@deffn Procedure class-name->name class-name

Returns a (symbol) name.

Obtains and returns the (symbol) name for @var{class-name}, by dropping
the surrounding @code{'<'} and @code{'>'} characters. For example:

@lisp
(class-name->name '<foo-bar>)
@result{} 'foo-bar
@end lisp
@end deffn


@anchor{class-name->g-name}
@deffn Procedure class-name->g-name class-name

Returns a string.

Obtains and returns the StudlyCaps string reprentation for
@var{class-name}. For example:

@lisp
(class-name->g-name '<foo-bar>)
@result{} "FooBar"
@end lisp
@end deffn


@anchor{name->g-name}
@deffn Procedure name->g-name name [as-string? #f]

Return a symbol, or a string if @var{as-string} is #t.

Unless @var{name} is a string, it first calls @code{(symbol->string
name)}, then changes all occurrences of @code{-} (hyphen) to @code{_}
(underscore) (other characters are not valid in a g-name).

If the optional @var{as-string} argument is #t, it returns
that string, otherwise, it calls and returns the result of
@code{string->symbol}.
@end deffn


@anchor{syntax-name->method-name}
@deffn Procedure syntax-name->method-name name

Returns a (symbol) name.

This procedure is used to @samp{protect} syntax names, from being
redefined as generic functions and methods.

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.

Here is what it does:

@itemize
@item
it first checks if a renamer is available, by calling
@ref{syntax-name-protect-renamer}, and if so, calls it passing
@var{name} and returns the result;
@*@*

@item
if no renamer is available, it checks if either or both
@ref{syntax-name-protect-prefix} and @ref{syntax-name-protect-postfix}
is(are) available, calls @code{symbol-append} adequately passing either
or both and @var{name} and returns the result.
@*@*

@item
It will raise an exception if none of the syntax name protect
prefix, postfix and renamer is available.
@end itemize

@xref{Customization Square} - @emph{GI Syntax Name Protect}. G-Golf GI
Syntax Name Protect default values are:

@indentedblock
@multitable @columnfractions .30 .05 .25
@item @ref{syntax-name-protect-prefix}
@tab @code{#f}

@item @ref{syntax-name-protect-postfix}
@tab @code{'_}
@tab (the symbol _)

@item @ref{syntax-name-protect-renamer}
@tab @code{#f}
@end multitable
@end indentedblock

As an example, using these default settings, the method short name for
@code{gcr-secret-exchange-begin} would be @code{begin_}.

@c If the @code{(ice-9 receive)} has also been imported, then the short
@c name method for @code{gcr-secret-exchange-receive} would be
@c @code{receive_}, otherwise, since there would be no syntax name
@c @samp{clash}, it would be @code{receive}.
@end deffn


@anchor{gi-type-tag->ffi}
@deffn Procedure gi-type-tag->ffi type-tag

Returns an integer or @code{'*} (the symbol @code{*}).

Obtains the correponding Guile's ffi tag value for @var{type-tag}, which
must be a member of @ref{%gi-type-tag}.  If @var{type-tag} is unknown,
an exception is raised. Note that Guile's ffi tag values are integers or
@code{'*} (the symbol @code{*}, used by convention to denote pointer
types.
@end deffn


@anchor{gi-type-tag->init-val}
@deffn Procedure gi-type-tag->init-val type-tag

Returns the default init value for @var{type-tag}.

Obtains and returns the default init value for @var{type-tag}, which
will either be @code{0} (zero), or @code{%null-pointer}.
@end deffn


@c @subheading Variables
