@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 Naming Conventions
@subsection Naming Conventions


G-Golf is, or at least tries to be, consistent in the way @samp{things}
are being named, whether the functionality being @samp{exposed} is from
an imported GNOME library or is part of a G-Golf's core reference
module.


@subheading GNOME Libraries

When G-Golf imports a GNOME library, its classes, properties, methods,
functions, types and constant are renamed, which is achieved by calling
@ref{g-name->class-name} and @ref{g-name->name} appropriately.

As described in their respective documentation entry, as well as in the
@ref{Customizing G-Golf} section, G-Golf offers a way to either ignore
or partially customize the renaming process.

@c playing ... attempt to 'replace' @U{10a52}, which only works for
@c x/html, pdf. @ @ @sup{_} @strong{...} seems the best, for now.

@c @ @ @U{10a52} @strong{Classes} @*
@c @ @ o @strong{Classes} @*
@c @ @ @textdegree{} @strong{Classes} @*
@c @ @ - @strong{Classes} @*
@c @ @ @sup{o} @strong{Classes} @*
@c @ @ @sup{o} @strong{Classes} @sup{o} @*
@c @ @ @bullet{} @strong{Classes} @*
@ @ @sup{_} @strong{Classes} @*


GNOME libraries classes are imported as GOOPS classes (the Guile Object
Oriented System, @pxref{GOOPS,,, guile, The GNU Guile Reference
Manual}), and their respective name is given by the result of calling
@ref{g-name->class-name}, for example:

@lisp
GtkWindow @result{} <gtk-window>
ClutterActor @result{} <clutter-actor>
WebKitWebView @result{} <webkit-web-view>@footnote{By default, G-Golf sets
@code{WebKit} as a renaming exception token, otherwise, the class name
would be <web-kit-web-view>.}
@dots{}
@end lisp


@ @ @sup{_} @strong{Properties}

GNOME libraries class properties are imported as GOOPS class slots, and
their respective name is given by calling @ref{g-name->name}. Each
property slot defines an @code{init-keyword} and an @code{accessor},
following G-Golf's accessors naming conventions (@xref{GOOPS Notes
and Conventions}).

As an example, the @code{<gtk-label>} class has a @code{label} slot,
with the @code{#:label} init-keyword and @code{!label} accessor.


@ @ @sup{_} @strong{Methods}

GNOME libraries methods are imported as GOOPS methods, the name of which
is obtained by calling @ref{g-name->name}.

Unless otherwise specified (@pxref{Customization Square} - @emph{GI
Method Short Name Skip}), 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 long
name.

For example, the @code{<gtk-label>} class, which defines a
@code{gtk-label-get-text} method, would also define, using G-Golf's
default settings, an @code{get-text} method.


@ @ @sup{_} @strong{Functions}

GNOME libraries functions are imported as procedures, renamed by calling
@ref{g-name->name}. For example:

@lisp
gtk_window_new @result{} gtk-window-new
clutter_actor_new @result{} clutter-actor-new
@dots{}
@end lisp


@ @ @sup{_} @strong{Enums, Flags and Boxed types}

GNOME libraries enums, flags and boxed types are renamed by calling
@ref{g-name->name} (and cached, @xref{Cache Park} section).

Enum and flag type members are renamed by calling @ref{g-name->name}. To
illustrate, here is an example:

@lisp
,use (g-golf)

(gi-import-by-name "Gtk" "WindowPosition")
@result{} $2 = #<<gi-enum> 5618c7a18090>

(describe $2)
@print{} #<<gi-enum> 5618c7a18090> is an instance of class <gi-enum>
@print{} Slots are:
@print{}      enum-set = ((none . 0) (center . 1) (mouse . 2) (center-always . 3) (center-on-parent . 4))
@print{}      g-type = 94664428197600
@print{}      g-name = "GtkWindowPosition"
@print{}      name = gtk-window-position
@end lisp



@subheading G-Golf Core Reference


@ @ @sup{_} @strong{Procedures and Variables}

G-Golf procedure names that bind a Glib, GObject or GObject
Introspection functions (always) use the @samp{original} name, except
that every @code{_} (underscore) occurrence is replaced by a @code{-}
(hyphens). For example:

@example
g_main_loop_new
@result{} @ref{g-main-loop-new}

g_irepository_get_loaded_namespaces
@result{} @ref{g-irepository-get-loaded-namespaces}
@end example

G-Golf also comes with its own set of procedures, syntax and variables,
aimed at not just reading a typelib, but making its functionality
available from @uref{@value{UGUILE}, Guile}.  Naming those, whenever
possible, is done following the @samp{traditional way} scheme name its
procedures, syntax and variables. For example:

@itemize
@item
procedure names that start with @code{call-with-input-},
@code{call-with-output-} followed by a Glib, GObject. Gdk or GI type,
such as:

@example
@ref{call-with-input-typelib}
@end example

@item
syntax names that start as @code{with-} followed by a Glib, GObject, Gdk
or GI type, such as:

@example
@ref{with-gerror}
@end example
@end itemize

When an @samp{obvious} name can't be find @samp{on its own}, or to avoid
possible conflict outside G-Golf@footnote{As an example, it would not be
a good idea to use (the name) @code{import} for the G-Golf procedure
that reads and build the interface for a @code{GIR} library, since it is
an R6RS reserved word.}, then the name starts using a @code{g-} prefix
(when the procedure context is GNOME in general) or @code{gi-} prefix
(when the procedure context is GI more specifically), and equally for
variables, using @code{%g-} or @code{%gi-}.


@ @ @sup{_} @strong{Types and Values}

G-Golf variables that bind Glib, GObject and GI types and values use the
same convention as for procedures, except that they always start with
@code{%} and their original type names are transformed by the same rules
that those applied when calling @ref{g-studly-caps-expand}.

For example, from the @code{GIBaseInfo} section:

@example
GIInfoType
@result{} @ref{%gi-info-type}
@end example
