Modulemd.ModuleIndex: Modulemd Reference Manual

Modulemd.ModuleIndex

Modulemd.ModuleIndex — The primary interface to dealing with repodata in the module metadata format.

Stability Level

Stable, unless otherwise indicated

Functions

gint	(*ModulemdReadHandler) ()
gint	(*ModulemdWriteHandler) ()
ModulemdModuleIndex *	modulemd_module_index_new ()
gboolean	modulemd_module_index_update_from_file ()
gboolean	modulemd_module_index_update_from_string ()
gboolean	modulemd_module_index_update_from_stream ()
gboolean	modulemd_module_index_update_from_custom ()
gchar *	modulemd_module_index_dump_to_string ()
gboolean	modulemd_module_index_dump_to_stream ()
gboolean	modulemd_module_index_dump_to_custom ()
GStrv	modulemd_module_index_get_module_names_as_strv ()
ModulemdModule *	modulemd_module_index_get_module ()
gboolean	modulemd_module_index_remove_module ()
gboolean	modulemd_module_index_add_module_stream ()
gboolean	modulemd_module_index_add_defaults ()
gboolean	modulemd_module_index_add_translation ()
ModulemdDefaultsVersionEnum	modulemd_module_index_get_defaults_mdversion ()
ModulemdModuleStreamVersionEnum	modulemd_module_index_get_stream_mdversion ()
gboolean	modulemd_module_index_upgrade_streams ()
gboolean	modulemd_module_index_upgrade_defaults ()

Types and Values

#define	MODULEMD_TYPE_MODULE_INDEX
	ModulemdModuleIndex

Description

This object provides an interface to the complete metadata read from a repository or manually added to this object.

NOTE: When adding or updating this object from YAML, all objects imported will be automatically upgraded to match the highest version of that object that is seen. This means that if the repository has a mix of ModulemdModuleStreamV1 and ModulemdModuleStreamV2 objects, the index will contain only ModulemdModuleStreamV2. You can check the versions the index upgraded to with the modulemd_module_index_get_stream_mdversion() and modulemd_module_index_get_defaults_mdversion(). If your application would prefer to always work with a particular stream or defaults version (such as to avoid extra branching logic), the modulemd_module_index_upgrade_streams() and modulemd_module_index_upgrade_defaults() functions can be used to force the contents of the index to upgrade to those versions.

Interacting with ModulemdModuleIndex is relatively simple. A common Python example for working with Fedora repodata might be (assuming the metadata has already been read into strings):

fedora_repo_index = Modulemd.ModuleIndex.new()
fedora_repo_index.update_from_string(fedora_modulemd)

# Get the list of all module names in the index
module_names = fedora_repo_index.get_module_names()

# Retrieve information about a particular module from the index
module = fedora_repo_index.get_module('module_name')

See the ModulemdModule documentation for details on retrieving information about specific modules, including how to get ModulemdDefaults information and retrieve individual ModulemdModuleStream objects.

See the ModulemdModuleIndexMerger documentation for details on merging ModulemdModuleIndex objects from separate repositories together.

Functions

ModulemdReadHandler ()

gint
(*ModulemdReadHandler) (void *data,
                        unsigned char *buffer,
                        size_t size,
                        size_t *size_read);

The prototype of a read handler.

The read handler is called when the parser needs to read more bytes from the source. The handler should write not more than size bytes to the buffer . The number of written bytes should be set to the size_read variable.

This handler is identical to a yaml_read_handler_t but is included here to avoid depending on yaml.h in modulemd headers.

Parameters

data	A private pointer to the data being read.	[inout]
buffer	The buffer to write the data from the source.	[out]
size	The size of the buffer.	[in]
size_read	The actual number of bytes read from the source.	[out]

Returns

On success, the handler must return 1. If the handler failed, the returned value must be 0. On EOF, the handler must set the size_read to 0 and return 1.

Since: 2.3

ModulemdWriteHandler ()

gint
(*ModulemdWriteHandler) (void *data,
                         unsigned char *buffer,
                         size_t size);

The prototype of a write handler.

The write handler is called when the emitter needs to flush the accumulated characters to the output. The handler should write size bytes of the buffer to the output.

This handler is identical to a yaml_write_handler_t but is included here to avoid depending on yaml.h in modulemd headers.

Parameters

data	A private pointer that includes the data source.	[inout]
buffer	The buffer with bytes to be written.	[out]
size	The size of the buffer.	[in]

Returns

On success, the handler must return 1. If the handler failed, the returned value must be 0.

Since: 2.3

modulemd_module_index_new ()

ModulemdModuleIndex *
modulemd_module_index_new (void);

Returns

A newly-allocated ModulemdModuleIndex object.

[transfer full]

Since: 2.0

modulemd_module_index_update_from_file ()

gboolean
modulemd_module_index_update_from_file
                               (ModulemdModuleIndex *self,
                                const gchar *yaml_file,
                                gboolean strict,
                                GPtrArray **failures,
                                GError **error);

Parameters

self	This ModulemdModuleIndex object
yaml_file	A YAML file containing the module metadata and other related information such as default streams.	[in]
strict	Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it.	[in]
failures	An array containing any subdocuments from the YAML file that failed to parse. See ModulemdSubdocumentInfo for more details.	[out][element-type ModulemdSubdocumentInfo][transfer container]
error	A GError containing additional information if this function fails in a way that prevents program continuation.	[out]

Returns

TRUE if the update was successful. Returns FALSE and sets failures approriately if any of the YAML subdocuments were invalid or sets error if there was a fatal parse error.

Since: 2.0

modulemd_module_index_update_from_string ()

gboolean
modulemd_module_index_update_from_string
                               (ModulemdModuleIndex *self,
                                const gchar *yaml_string,
                                gboolean strict,
                                GPtrArray **failures,
                                GError **error);

Parameters

self	This ModulemdModuleIndex object
yaml_string	A YAML string containing the module metadata and other related information such as default streams.	[in]
strict	Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it.	[in]
failures	An array containing any subdocuments from the YAML file that failed to parse. See ModulemdSubdocumentInfo for more details.	[out][element-type ModulemdSubdocumentInfo][transfer container]
error	A GError containing additional information if this function fails in a way that prevents program continuation.	[out]

Returns

TRUE if the update was successful. Returns FALSE and sets failures approriately if any of the YAML subdocuments were invalid or sets error if there was a fatal parse error.

Since: 2.0

modulemd_module_index_update_from_stream ()

gboolean
modulemd_module_index_update_from_stream
                               (ModulemdModuleIndex *self,
                                FILE *yaml_stream,
                                gboolean strict,
                                GPtrArray **failures,
                                GError **error);

[skip]

Parameters

self	This ModulemdModuleIndex object
yaml_stream	A YAML stream containing the module metadata and other related information such as default streams.	[in]
strict	Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it.	[in]
failures	An array containing any subdocuments from the YAML file that failed to parse. See ModulemdSubdocumentInfo for more details.	[out][element-type ModulemdSubdocumentInfo][transfer container]
error	A GError containing additional information if this function fails in a way that prevents program continuation.	[out]

Returns

TRUE if the update was successful. Returns FALSE and sets failures approriately if any of the YAML subdocuments were invalid or sets error if there was a fatal parse error.

Since: 2.0

modulemd_module_index_update_from_custom ()

gboolean
modulemd_module_index_update_from_custom
                               (ModulemdModuleIndex *self,
                                ModulemdReadHandler custom_read_fn,
                                void *custom_pvt_data,
                                gboolean strict,
                                GPtrArray **failures,
                                GError **error);

[skip]

Parameters

self	This ModulemdModuleIndex object
custom_read_fn	A ModulemdReadHandler.	[in]
custom_pvt_data	The private data needed by the ModulemdReadHandler.	[inout]
strict	Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it.	[in]
failures	An array containing any subdocuments from the YAML file that failed to parse. See ModulemdSubdocumentInfo for more details.	[out][element-type ModulemdSubdocumentInfo][transfer container]
error	A GError containing additional information if this function fails in a way that prevents program continuation.	[out]

Returns

TRUE if the update was successful. Returns FALSE and sets failures approriately if any of the YAML subdocuments were invalid or sets error if there was a fatal parse error.

Since: 2.3

modulemd_module_index_dump_to_string ()

gchar *
modulemd_module_index_dump_to_string (ModulemdModuleIndex *self,
                                      GError **error);

Parameters

self	This ModulemdModuleIndex
error	A GError containing the reason the function failed, NULL if the function succeeded.	[out]

Returns

A YAML representation of the index as a string. In the event of an error, sets error appropriately and returns NULL.

[transfer full]

Since: 2.0

modulemd_module_index_dump_to_stream ()

gboolean
modulemd_module_index_dump_to_stream (ModulemdModuleIndex *self,
                                      FILE *yaml_stream,
                                      GError **error);

[skip]

Parameters

self	This ModulemdModuleIndex
yaml_stream	A stream to write the module metadata and other related information to.	[in]
error	A GError containing the reason the function failed, NULL if the function succeeded.	[out]

Returns

TRUE if written successfully, FALSE and sets error appropriately in the event of an error.

Since: 2.0

modulemd_module_index_dump_to_custom ()

gboolean
modulemd_module_index_dump_to_custom (ModulemdModuleIndex *self,
                                      ModulemdWriteHandler custom_write_fn,
                                      void *custom_pvt_data,
                                      GError **error);

[skip]

Parameters

self	This ModulemdModuleIndex
custom_write_fn	A ModulemdWriteHandler.	[in]
custom_pvt_data	The private data needed by the ModulemdWriteHandler.	[inout]
error	A GError containing the reason the function failed, NULL if the function succeeded.	[out]

Returns

TRUE if written successfully, FALSE and sets error appropriately in the event of an error.

Since: 2.3

modulemd_module_index_get_module_names_as_strv ()

GStrv
modulemd_module_index_get_module_names_as_strv
                               (ModulemdModuleIndex *self);

[rename-to modulemd_module_index_get_module_names]

Parameters

self

This ModulemdModuleIndex

Returns

An ordered list of string keys in this index.

[transfer full]

Since: 2.0

modulemd_module_index_get_module ()

ModulemdModule *
modulemd_module_index_get_module (ModulemdModuleIndex *self,
                                  const gchar *module_name);

Parameters

self	This ModulemdModuleIndex
module_name	The module name to look up in the index.

Returns

The ModulemdModule object matching the provided module name or NULL if the key was not present in the index.

[transfer none]

Since: 2.0

modulemd_module_index_remove_module ()

gboolean
modulemd_module_index_remove_module (ModulemdModuleIndex *self,
                                     const gchar *module_name);

Remove a module, including all of its streams, its defaults and its translations from a ModulemdModuleIndex.

Parameters

self	This ModulemdModuleIndex
module_name	The name of the module to remove from the index.

Returns

TRUE if the module name was present in the index. FALSE if it was not.

Since: 2.2

modulemd_module_index_add_module_stream ()

gboolean
modulemd_module_index_add_module_stream
                               (ModulemdModuleIndex *self,
                                ModulemdModuleStream *stream,
                                GError **error);

Add a ModuleStream to the ModuleIndex. While being added, the ModuleStream will be upgraded to MD_MODULESTREAM_VERSION_LATEST to ensure that merges done with ModulemdModuleIndexMerger will always occur between streams of the same version. If this upgrade cannot be performed, the function will return error set appropriately.

Parameters

self	This ModulemdModuleIndex
stream	The ModulemdModuleStream to add to the index. The stream added must have a module name and stream name set on it or it will be rejected.
error	A GError containing the reason the ModulemdModuleStream object could not be added or NULL if the function succeeded.	[out]

Returns

TRUE if the ModulemdModule was added succesfully. If the stream already existed in the index, it will be replaced by the new one. On failure, returns FALSE and sets error appropriately.

Since: 2.0

modulemd_module_index_add_defaults ()

gboolean
modulemd_module_index_add_defaults (ModulemdModuleIndex *self,
                                    ModulemdDefaults *defaults,
                                    GError **error);

Parameters

self	This ModulemdModuleIndex
defaults	The ModulemdDefaults object to add to the index.
error	A GError containing the reason the ModulemdDefaults object could not be added or NULL if the function succeeded.	[out]

Returns

TRUE if the ModulemdDefaults was added succesfully. If the defaults already existed in the index, it will be replaced by the new one. On failure, returns FALSE and sets error approriately.

Since: 2.0

modulemd_module_index_add_translation ()

gboolean
modulemd_module_index_add_translation (ModulemdModuleIndex *self,
                                       ModulemdTranslation *translation,
                                       GError **error);

modulemd_module_index_get_defaults_mdversion ()

ModulemdDefaultsVersionEnum
modulemd_module_index_get_defaults_mdversion
                               (ModulemdModuleIndex *self);

Parameters

self

This ModulemdModuleIndex

Returns

The metadata version of ModulemdDefaults in use for this index.

Since: 2.0

modulemd_module_index_get_stream_mdversion ()

ModulemdModuleStreamVersionEnum
modulemd_module_index_get_stream_mdversion
                               (ModulemdModuleIndex *self);

Parameters

self

This ModulemdModuleIndex

Returns

The metadata version of ModulemdModuleStream in use for this index.

Since: 2.0

modulemd_module_index_upgrade_streams ()

gboolean
modulemd_module_index_upgrade_streams (ModulemdModuleIndex *self,
                                       ModulemdModuleStreamVersionEnum mdversion,
                                       GError **error);

Upgrades all ModulemdModuleStream objects in this index to mdversion if they are not already at that version.

Parameters

self	This ModulemdModuleIndex
mdversion	The ModulemdModuleStream metadata version to upgrade to.
error	A GError that contains information on why the index could not be upgraded in the event of an error.	[out]

Since: 2.0

modulemd_module_index_upgrade_defaults ()

gboolean
modulemd_module_index_upgrade_defaults
                               (ModulemdModuleIndex *self,
                                ModulemdDefaultsVersionEnum mdversion,
                                GError **error);

Upgrades all ModulemdDefaults objects in this index to mdversion if they are not already at that version.

Parameters

self	This ModulemdModuleIndex
mdversion	The ModulemdDefaults metadata version to upgrade to.
error	A GError that contains information on why the index could not be upgraded in the event of an error.	[out]

Since: 2.0

Types and Values

MODULEMD_TYPE_MODULE_INDEX

#define MODULEMD_TYPE_MODULE_INDEX (modulemd_module_index_get_type ())

ModulemdModuleIndex

typedef struct _ModulemdModuleIndex ModulemdModuleIndex;