@c -*-texinfo-*-

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


@c @defindex ei


@node Import_
@subsection Import

G-Golf GI import interfaces.@*
The G-Golf GI namespace (Typelib) import interfaces.


@subheading Procedures

@indentedblock
@table @code
@item @ref{gi-import-info}
@item @ref{gi-import-enum}
@item @ref{gi-import-flags}
@item @ref{gi-import-struct}
@item @ref{gi-import-function}
@item @ref{gi-import-constant}
@end table
@end indentedblock


@subheading Variables

@indentedblock
@table @code
@item @ref{%gi-base-info-types}
@item @ref{%gi-imported-base-info-types}
@end table
@end indentedblock


@c @subheading Description


@subheading Procedures


@anchor{gi-import-info}
@deffn Procedure gi-import-info info

Returns the object or constant returned by the one of the
@code{gi-import-enum}, @code{gi-import-flags}, @dots{}, called upon
@code{info}.

Obtains the GIBaseInfo type for @code{info} and uses it to dispatch a
call to @code{gi-import-enum}, @code{gi-import-enum}, @dots{}, and
returns the object or constant returned by the procedure that has been
called.

You probably will prefer to call @ref{gi-import-by-name} most of the
time, but here is a example:

@lisp
,use (g-golf)
(g-irepository-require "Clutter")
@result{} $2 = #<pointer 0x5642cb065e30>

(g-irepository-find-by-name "Clutter" "ActorFlags")
@result{} $3 = #<pointer 0x5642cb067de0>

(gi-import-info $3)
@result{} $4 = #<<gi-flags> 5642cb13c5d0>

(describe $4)
@print{} #<<gi-flags> 5642cb13c5d0> is an instance of class <gi-flags>
@print{} Slots are:
@print{}      enum-set = ((mapped . 2) (realized . 4) (reactive . 8) (visible . 16) (no-layout . 32))
@print{}      g-type = 94844874149456
@print{}      g-name = "ClutterActorFlags"
@print{}      name = clutter-actor-flags
@end lisp
@end deffn


@anchor{gi-import-enum}
@anchor{gi-import-flags}
@anchor{gi-import-struct}
@deffn Procedure gi-import-enum info [#:with-method #t]
@deffnx Procedure gi-import-flags info [#:with-method #t]
@deffnx Procedure gi-import-struct info [#:with-method #t]

Returns a @ref{<gi-enum>}, a @ref{<gi-flags>} or a @ref{<gi-struct>}
instance, respectively.

The @var{info} argument is (must be) a pointer to @code{GIEnumInfo}, a
@code{GIEnumInfo} for which @code{(@ref{g-base-info-get-type} info)}
returned @code{'flags} and a @code{GIStructInfo} respectively. It is an
error to call any of these procedures upon an invalid @var{info}
argument.

The optional keyword @var{#:with-method} argument - which is #t by
default - is passed using #f, then @var{info} will be imported without
its respective methods. A description and an example ware also given
here above, as part of the @ref{gi-import-by-name} documentation entry.

Every imported @ref{<gi-enum>}, @ref{<gi-flags>} and @ref{<gi-struct>}
instance is cached under the @code{'enum}, @code{'flags} and
@code{'boxed} main key (respectively), using the content of their
(symbol) @code{name} slot as the secondary key. For example, reusing the
"Clutter" "ActorFlags" namespace/name introduced above, you would
retreive its @ref{<gi-flags>} instance as is:

@lisp
@dots{}
(gi-cache-ref 'flags 'clutter-actor-flags)
@result{} $6 = #<<gi-flags> 5642cb13c5d0>
@end lisp
@end deffn


@anchor{gi-import-function}
@deffn Procedure gi-import-function info

Returns a @ref{<function>} instance.

Imports @var{info} - a pointer to a @code{GIFunctionInfo} (see
@ref{Function Info}), which represents a function, a method or a
constructor - in Guile and exports its interface. This procedure also
imports, recursively (and exports the interface of) its argument's
type(s) and method(s).

Every imported function, method and constructor is cached under
@code{'function} main key, and using the value of their @ref{<function>}
instance @code{name} slot as the secondary key. Here is an example:

@lisp
,use (g-golf)
(g-irepository-require "Clutter")
@result{} $2 = #<pointer 0x55c191f3fe30>

(g-irepository-find-by-name "Clutter" "init")
@result{} $3 = #<pointer 0x55c191f41de0>

(gi-import-function $3)
@result{} $4 = #<<function> 55c191e81510>

(describe $4)
@print{} #<<function> 55c191e81510> is an instance of class <function>
@print{} Slots are:
@print{}      info = #<pointer 0x55c191f41de0>
@print{}      name = clutter-init
@print{}      flags = ()
@print{}      n-arg = 2
@print{}      caller-owns = nothing
@print{}      return-type = interface
@dots{}

(gi-cache-ref 'function 'clutter-init)
@result{} $5 = #<<function> 55c191e81510>
@end lisp

@emph{Returned value(s):}

In most situations - unless the @code{return-type} is @code{'void} (in
which case nothing is returned) - the function or method returned value
comes first, then in order, if any, the value(s) of its @code{'inout}
and @code{'out} argument(s).

However, some function and method, that have at least one @code{'inout}
or @code{'out} argument(s), do return @code{#t} or @code{#f} solely to
indicate that the function or method call was successful or not. It is
only if the call is successful that the @code{'inout} and @code{'out}
argument(s) have been @samp{correctly} set and may safely be used.

In scheme, when binding such a function or method, we would rather (a)
when the call is successful, elude the boolean and return, in order,
the @code{'inout} and/or @code{'out} argument(s) value(s); and (b), when
the call is unsuccessful, raise an exception.

Since it is not possible to automatically detect these functions and
methods, G-Golf provides a series of interfaces to maintain, at user
discretion and responsibility, a list of GI typelib functions and
methods for which G-Golf is expected to elude their result value from
the returned value(s). G-Golf interfaces to maintain this list are
documented in the @ref{Customization Square} section.
@end deffn


@anchor{gi-import-constant}
@deffn Procedure gi-import-constant info

Returns two values, the constant value and its name.

Obtains and returns the @var{info} constant value and its name. For
example:

@lisp
,use (g-golf)
(g-irepository-require "GLib")
@result{} #<pointer 0x55ad58e6ae00>

(g-irepository-find-by-name "GLib" "PRIORITY_DEFAULT_IDLE")
@result{} $3 = #<pointer 0x55ad58e6cde0>

(gi-import-constant $3)
@result{} $4 = 200
@result{} $5 = "PRIORITY_DEFAULT_IDLE"
@end lisp

Constants are curently not being automatically imported, though this
will probably change in the near future, stay tuned.
@end deffn


@subheading Variables


@anchor{%gi-base-info-types}
@anchor{%gi-imported-base-info-types}
@defvar %gi-base-info-types
@defvarx %gi-imported-base-info-types

A (cumulative) list of the distinct (top level) base info types
contained in the imported namespace(s).

These two variables have no other purpose then offering a feedback
about: (a) the (top level) base info types contained in the namespace(s)
passed to @ref{gi-import}; (b) the (top level) base info types that have
effectively been imported - when @code{G-Golf} is complete, both lists
should be identical.

Initially, these variables are empty. As @ref{gi-import},
@ref{gi-import-info} and/or @ref{gi-import-by-name} are being called,
they are filled with new types, which are added to both lists.

Note that the order in which base info types appear in these two lists
is rrelevant, and may slightly vary, depending on the order of the
namespace used for the successive @ref{gi-import} calls and how complete
is @code{G-Golf}.
@end defvar
