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


@defindex ir


@node Repository
@subsection Repository

G-Golf Introspection Repository low level API. @*
GIRepository — GObject Introspection repository manager.


@subheading Procedures


@indentedblock
@table @code
@item @ref{g-irepository-get-default}
@item @ref{g-irepository-get-dependencies}
@item @ref{g-irepository-get-loaded-namespaces}
@item @ref{g-irepository-get-n-infos}
@item @ref{g-irepository-get-info}
@item @ref{g-irepository-enumerate-versions}
@item @ref{g-irepository-get-typelib-path}
@item @ref{g-irepository-require}
@item @ref{g-irepository-get-c-prefix}
@item @ref{g-irepository-get-shared-library}
@item @ref{g-irepository-get-version}
@item @ref{g-irepository-find-by-gtype}
@item @ref{g-irepository-find-by-name}
@end table
@end indentedblock


@subheading Description

@code{GIRepository} is used to manage repositories of
namespaces. Namespaces are represented on disk by type libraries
(.typelib files).


@subheading Object Hierarchy

@indentedblock
GObject           @*
|___ GIRepository
@end indentedblock


@subheading Procedures

Note: in this section, when the @var{#:repository} optional keyword
argument is passed, it is [must be] a pointer to a
@code{GIRepository}. Its default value is @code{#f}, the scheme
representation for @code{NULL}, meaning the singleton process-global
default @code{GIRepository} (@pxref{g-irepository-get-default}).


@anchor{g-irepository-get-default}
@deffn Procedure g-irepository-get-default

Returns a pointer to the singleton process-global default
@code{GIRepository}.

GObject Introspection does not currently support multiple repositories
in a particular process, but this procedure is provided in the unlikely
eventuality that it would become possible.

All G-Golf low level API procedures on GIRepository also accept an
optional @var{#:repository} keyword argument which defaults to
@code{#f}, meaning this singleton process-global default
@code{GIRepository}.
@end deffn

@anchor{g-irepository-get-dependencies}
@deffn Procedure g-irepository-get-dependencies namespace [#:repository #f]

Returns a list of all (transitive) versioned dependencies for
@var{namespace}. Returned string are of the form
@code{namespace-version}.

Note: The @var{namespace} must have already been loaded using a
procedure such as @code{g-irepository-require} before calling this procedure.
@end deffn


@anchor{g-irepository-get-loaded-namespaces}
@deffn Procedure g-irepository-get-loaded-namespaces [#:repository #f]

Return the list of currently loaded namespaces.
@end deffn

@anchor{g-irepository-get-n-infos}
@deffn Procedure g-irepository-get-n-infos namespace [#:repository #f]

Returns the number of metadata entries in @var{namespace}. The
@var{namespace} must have already been loaded before calling this
procedure.
@end deffn


@anchor{g-irepository-get-info}
@deffn Procedure g-irepository-get-info namespace index [#:repository #f]

Returns a pointer to a particular metadata entry in the given
@var{namespace}.

The @var{namespace} must have already been loaded before calling this
procedure.  See @code{g-irepository-get-n-infos} to find the maximum number
of entries.

@var{index} is a 0-based offset into @var{namespace} for entry.
@end deffn


@anchor{g-irepository-enumerate-versions}
@deffn Procedure g-irepository-enumerate-versions namespace @
       [#:repository #f]

Returns a (possibly empty) list.

Obtains and returns an unordered (possibly empty) list of versions
(either currently loaded or available) for @var{namespace} in
@var{repository}.
@end deffn


@anchor{g-irepository-get-typelib-path}
@deffn Procedure g-irepository-get-typelib-path namespace [#:repository #f]

Returns the full path to the .typelib file @var{namespace} was loaded
from, if loaded. If @var{namespace} is not loaded or does not exist, it
will return @code{#f}. If the typelib for @var{namespace} was included
in a shared library, it returns the special string "<builtin>".
@end deffn


@anchor{g-irepository-require}
@deffn Procedure g-irepository-require namespace [#:version #f] @
       [#:repository #f]

Returns a pointer a @code{GITypelib} structure, if the @code{Typelib}
file for @var{namespace} exists. Otherwise, it raises an error.

Force the @var{namespace} to be loaded if it isn't already. If
@var{namespace} is not loaded, this procedure will search for a
@code{".typelib"} file using the repository search path. In addition, a
version version of namespace may be specified. If version is not
specified, the latest will be used.
@end deffn


@anchor{g-irepository-get-c-prefix}
@deffn Procedure g-irepository-get-c-prefix namespace [#:repository #f]

Returns the "C prefix", or the C level namespace associated with the
given introspection @var{namespace}. Each C symbol starts with this
prefix, as well each @code{GType} in the library.

Note: The @var{namespace} must have already been loaded using a
procedure such as @code{g-irepository-require} before calling this procedure.
@end deffn


@anchor{g-irepository-get-shared-library}
@deffn Procedure g-irepository-get-shared-library namespace [#:repository #f]

Returns a list of paths to the shared C libraries associated with the
given @var{namespace}. There may be no shared library path associated,
in which case this procedure will return an empty list.
@end deffn


@anchor{g-irepository-get-version}
@deffn Procedure g-irepository-get-version  namespace [#:repository #f]

Returns the loaded version associated with the given @var{namespace}.

Note: The @var{namespace} must have already been loaded using a
procedure such as @code{g-irepository-require} before calling this procedure.
@end deffn


@anchor{g-irepository-find-by-gtype}
@deffn Procedure g-irepository-find-by-gtype gtype [#:repository #f]

Returns a pointer to a @code{GIBaseInfo} representing metadata about
@var{gtype}, or @code{#f}.

Searches all loaded namespaces for a particular @code{GType}. Note that
in order to locate the metadata, the namespace corresponding to the type
must first have been loaded. There is currently no mechanism for
determining the namespace which corresponds to an arbitrary @code{GType}
- thus, this procedure will operate most reliably when you know the
@code{GType} to originate from be from a loaded namespace.
@end deffn


@anchor{g-irepository-find-by-name}
@deffn Procedure g-irepository-find-by-name namespace name [#:repository #f]

Returns a pointer to a @code{GIBaseInfo} representing metadata about
type, or @code{#f}.

Searches for a particular entry in @var{namespace}. Before calling this
function for a particular namespace, you must call
@code{g-irepository-require} once to load the @var{namespace}, or otherwise
ensure the @var{namespace} has already been loaded.
@end deffn


@c @subheading Types and Values

