YAML Manipulation Tools: Modulemd Reference Manual

YAML Manipulation Tools

YAML Manipulation Tools — Provides private YAML utilities for internal use.

Stability Level

Private, unless otherwise indicated

Functions

int	write_yaml_string ()
void	modulemd_yaml_string_free ()
const gchar *	mmd_yaml_get_event_name ()
#define	MMD_INIT_YAML_PARSER()
#define	MMD_INIT_YAML_EMITTER()
#define	MMD_INIT_YAML_EVENT()
#define	MMD_INIT_YAML_STRING()
#define	MMD_REINIT_YAML_STRING()
#define	YAML_PARSER_PARSE_WITH_EXIT_FULL()
#define	YAML_PARSER_PARSE_WITH_EXIT_BOOL()
#define	YAML_PARSER_PARSE_WITH_EXIT_INT()
#define	YAML_PARSER_PARSE_WITH_EXIT()
#define	MMD_EMIT_WITH_EXIT_FULL()
#define	MMD_EMIT_WITH_EXIT()
#define	MMD_EMIT_WITH_EXIT_PTR()
#define	MMD_YAML_ERROR_EVENT_EXIT_FULL()
#define	MMD_YAML_ERROR_EVENT_EXIT()
#define	MMD_YAML_ERROR_EVENT_EXIT_BOOL()
#define	MMD_YAML_ERROR_EVENT_EXIT_INT()
#define	MMD_SET_PARSED_YAML_STRING()
gboolean	mmd_emitter_start_stream ()
gboolean	mmd_emitter_end_stream ()
gboolean	mmd_emitter_start_document ()
gboolean	mmd_emitter_end_document ()
gboolean	mmd_emitter_start_mapping ()
gboolean	mmd_emitter_end_mapping ()
gboolean	mmd_emitter_start_sequence ()
gboolean	mmd_emitter_end_sequence ()
gboolean	mmd_emitter_scalar ()
gboolean	mmd_emitter_scalar_string ()
gboolean	mmd_emitter_strv ()
GDate *	modulemd_yaml_parse_date ()
gchar *	modulemd_yaml_parse_string ()
gboolean	modulemd_yaml_parse_bool ()
gint64	modulemd_yaml_parse_int64 ()
guint64	modulemd_yaml_parse_uint64 ()
GHashTable *	modulemd_yaml_parse_string_set ()
GHashTable *	modulemd_yaml_parse_string_set_from_map ()
GHashTable *	modulemd_yaml_parse_string_string_map ()
GHashTable *	modulemd_yaml_parse_nested_set ()
gboolean	modulemd_yaml_emit_nested_set ()
ModulemdSubdocumentInfo *	modulemd_yaml_parse_document_type ()
gboolean	modulemd_yaml_emit_document_headers ()
gboolean	modulemd_yaml_emit_variant ()
GVariant *	mmd_variant_from_scalar ()
GVariant *	mmd_variant_from_mapping ()
GVariant *	mmd_variant_from_sequence ()
GVariant *	mmd_parse_xmd ()
gboolean	skip_unknown_yaml ()
#define	SKIP_UNKNOWN()
#define	NON_EMPTY_TABLE()
#define	NON_EMPTY_ARRAY()
#define	EMIT_SCALAR_FULL()
#define	EMIT_SCALAR()
#define	EMIT_SCALAR_STRING()
#define	EMIT_KEY_VALUE_FULL()
#define	EMIT_KEY_VALUE()
#define	EMIT_KEY_VALUE_STRING()
#define	EMIT_KEY_VALUE_IF_SET()
#define	EMIT_KEY_VALUE_STRING_IF_SET()
#define	EMIT_MAPPING_START_WITH_STYLE()
#define	EMIT_MAPPING_START()
#define	EMIT_MAPPING_END()
#define	EMIT_SEQUENCE_START_WITH_STYLE()
#define	EMIT_SEQUENCE_START()
#define	EMIT_SEQUENCE_END()
#define	EMIT_HASHTABLE_VALUES_IF_NON_EMPTY()
#define	EMIT_HASHTABLE_KEY_VALUES_IF_NON_EMPTY()
#define	EMIT_STRING_SET()
#define	EMIT_STRING_SET_IF_NON_EMPTY()
#define	EMIT_STRING_SET_FULL()
#define	EMIT_ARRAY_VALUES()
#define	EMIT_ARRAY_VALUES_IF_NON_EMPTY()

Types and Values

enum	ModulemdYamlDocumentTypeEnum

Description

Functions

write_yaml_string ()

int
write_yaml_string (void *data,
                   unsigned char *buffer,
                   size_t size);

Additionally memory for data is automatically allocated if necessary.

Parameters

data	A void pointer to a modulemd_yaml_string object.	[inout]
buffer	YAML text to append to `data` .	[in]
size	The number of bytes from `buffer` to append to `data` .	[in]

Since: 2.0

modulemd_yaml_string_free ()

void
modulemd_yaml_string_free (modulemd_yaml_string *yaml_string);

Parameters

yaml_string

A pointer to a modulemd_yaml_string to be freed.

[inout]

Since: 2.0

mmd_yaml_get_event_name ()

const gchar *
mmd_yaml_get_event_name (yaml_event_type_t type);

Parameters

type

A libyaml event type.

[in]

Returns

The string representation for type .

Since: 2.0

MMD_INIT_YAML_PARSER()

#define             MMD_INIT_YAML_PARSER(_parser)

This convenience macro allocates and initializes a new libyaml parser object named _parser .

Parameters

_parser

A variable name to use for the new parser object.

[out]

Since: 2.0

MMD_INIT_YAML_EMITTER()

#define             MMD_INIT_YAML_EMITTER(_emitter)

This convenience macro allocates and initializes a new libyaml emitter object named _emitter .

Parameters

_emitter

A variable name to use for the new emitter object.

[out]

Since: 2.0

MMD_INIT_YAML_EVENT()

#define             MMD_INIT_YAML_EVENT(_event)

This convenience macro allocates and initializes a new libyaml event object named _event .

Parameters

_event

A variable name to use for the new event object.

[out]

Since: 2.0

MMD_INIT_YAML_STRING()

#define             MMD_INIT_YAML_STRING(_emitter, _string)

This convenience macro allocates and initializes a new yaml string object named _string and associates it as the output target for the libyaml emitter object _emitter .

Parameters

_emitter	A libyaml emitter object.	[inout]
_string	A variable name to use for the new yaml string object.	[out]

Since: 2.0

MMD_REINIT_YAML_STRING()

#define             MMD_REINIT_YAML_STRING(_emitter, _string)

This convenience macro deletes then initializes a new libyaml emitter named _emitter , then deletes, reallocates, and initializes a new yaml string object named _string and associates it as the output target for _emitter .

Parameters

_emitter	A libyaml emitter object to reinitialize.	[inout]
_string	A variable name to reinitialize with a new yaml string object.	[inout]

Since: 2.0

YAML_PARSER_PARSE_WITH_EXIT_FULL()

#define             YAML_PARSER_PARSE_WITH_EXIT_FULL(_parser, _returnval, _event, _error)

DIRECT USE OF THIS MACRO SHOULD BE AVOIDED. This is the internal implementation for YAML_PARSER_PARSE_WITH_EXIT_BOOL, YAML_PARSER_PARSE_WITH_EXIT_INT, and YAML_PARSER_PARSE_WITH_EXIT which should be used instead.

Parameters

_parser	A libyaml parser object positioned at the beginning of an event.	[inout]
_returnval	The value to return in case of a parsing error.	[in]
_event	Returns the libyaml event that was parsed.	[out]
_error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

Continues on if parsing of the event was successful. Returns _returnval if a parse error occurred and sets _error appropriately.

Since: 2.0

YAML_PARSER_PARSE_WITH_EXIT_BOOL()

#define             YAML_PARSER_PARSE_WITH_EXIT_BOOL(_parser, _event, _error)

Parameters

_parser	A libyaml parser object positioned at the beginning of an event.	[inout]
_event	Returns the libyaml event that was parsed.	[out]
_error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

Continues on if parsing of the event was successful. Returns FALSE if a parse error occurred and sets _error appropriately.

Since: 2.0

YAML_PARSER_PARSE_WITH_EXIT_INT()

#define             YAML_PARSER_PARSE_WITH_EXIT_INT(_parser, _event, _error)

Parameters

_parser	A libyaml parser object positioned at the beginning of an event.	[inout]
_event	Returns the libyaml event that was parsed.	[out]
_error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

Continues on if parsing of the event was successful. Returns 0 if a parse error occurred and sets _error appropriately.

Since: 2.0

YAML_PARSER_PARSE_WITH_EXIT()

#define             YAML_PARSER_PARSE_WITH_EXIT(_parser, _event, _error)

Parameters

_parser	A libyaml parser object positioned at the beginning of an event.	[inout]
_event	Returns the libyaml event that was parsed.	[out]
_error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

Continues on if parsing of the event was successful. Returns NULL if a parse error occurred and sets _error appropriately.

Since: 2.0

MMD_EMIT_WITH_EXIT_FULL()

#define             MMD_EMIT_WITH_EXIT_FULL(_emitter, _returnval, _event, _error, ...)

DIRECT USE OF THIS MACRO SHOULD BE AVOIDED. This is the internal implementation for MMD_EMIT_WITH_EXIT and MMD_EMIT_WITH_EXIT_PTR which should be used instead.

Parameters

_emitter	A libyaml emitter object positioned where `_event` belongs in the YAML document.	[inout]
_returnval	The value to return in case of an output error.	[in]
_event	The libyaml event to be emitted.	[in]
_error	A GError that will return the reason for an output error.	[out]
...	Additional argument(s) to pass to `g_set_error()` when setting `_error` in case of failure.	[in]

Returns

Continues on if emitting of the event was successful. Returns _returnval if an output error occurred and sets _error appropriately.

Since: 2.0

MMD_EMIT_WITH_EXIT()

#define             MMD_EMIT_WITH_EXIT(_emitter, _event, _error, ...)

Parameters

_emitter	A libyaml emitter object positioned where `_event` belongs in the YAML document.	[inout]
_event	The libyaml event to be emitted.	[in]
_error	A GError that will return the reason for an output error.	[out]
...	Additional argument(s) to pass to `g_set_error()` when setting `_error` in case of failure.	[in]

Returns

Continues on if emitting of the event was successful. Returns FALSE if an output error occurred and sets _error appropriately.

Since: 2.0

MMD_EMIT_WITH_EXIT_PTR()

#define             MMD_EMIT_WITH_EXIT_PTR(_emitter, _event, _error, ...)

Parameters

_emitter	A libyaml emitter object positioned where `_event` belongs in the YAML document.	[inout]
_event	The libyaml event to be emitted.	[in]
_error	A GError that will return the reason for an output error.	[out]
...	Additional argument(s) to pass to `g_set_error()` when setting `_error` in case of failure.	[in]

Returns

Continues on if emitting of the event was successful. Returns NULL if an output error occurred and sets _error appropriately.

Since: 2.0

MMD_YAML_ERROR_EVENT_EXIT_FULL()

#define             MMD_YAML_ERROR_EVENT_EXIT_FULL(                                       \
              _error, _errorcode, _event, _returnval, ...)

DIRECT USE OF THIS MACRO SHOULD BE AVOIDED. This is the internal implementation for MMD_YAML_ERROR_EVENT_EXIT, MMD_YAML_ERROR_EVENT_EXIT_BOOL, and MMD_YAML_ERROR_EVENT_EXIT_INT which should be used instead.

Parameters

_error	A GError that will return the reason for the error.	[out]
_errorcode	The exact error code that should be set on `_error` .	[in]
_event	The libyaml event for which an error is to be reported.	[in]
_returnval	The error value to return.	[in]
...	Additional argument(s) to pass to `g_set_error()` when setting `_error` .	[in]

Returns

Returns _returnval and sets _error appropriately.

Since: 2.0

MMD_YAML_ERROR_EVENT_EXIT()

#define             MMD_YAML_ERROR_EVENT_EXIT(_error, _event, ...)

Parameters

_error	A GError that will return the reason for the error.	[out]
_event	The libyaml event for which an error is to be reported.	[in]
...	Additional argument(s) to pass to `g_set_error()` when setting `_error` .	[in]

Returns

Returns NULL and sets _error appropriately.

Since: 2.0

MMD_YAML_ERROR_EVENT_EXIT_BOOL()

#define             MMD_YAML_ERROR_EVENT_EXIT_BOOL(_error, _event, ...)

Parameters

_error	A GError that will return the reason for the error.	[out]
_event	The libyaml event for which an error is to be reported.	[in]
...	Additional argument(s) to pass to `g_set_error()` when setting `_error` .	[in]

Returns

Returns FALSE and sets _error appropriately.

Since: 2.0

MMD_YAML_ERROR_EVENT_EXIT_INT()

#define             MMD_YAML_ERROR_EVENT_EXIT_INT(_error, _event, ...)

Parameters

_error	A GError that will return the reason for the error.	[out]
_event	The libyaml event for which an error is to be reported.	[in]
...	Additional argument(s) to pass to `g_set_error()` when setting `_error` .	[in]

Returns

Returns 0 and sets _error appropriately.

Since: 2.0

MMD_SET_PARSED_YAML_STRING()

#define             MMD_SET_PARSED_YAML_STRING(_parser, _error, _fn, _obj)

This convenience macro can be used when a YAML string (scalar) event is expected, and that string is to be stored in a property of libmodulemd object _obj via setter method _fn .

Parameters

_parser	A libyaml parser object positioned at the beginning of an expected string event.	[inout]
_error	A GError that will return the reason for a parsing or validation error.	[out]
_fn	A setter method for a property of object `_obj` to be called with the successfully parsed string.	[in]
_obj	The object that is to store the parsed string via its `_fn` setter method.	[inout]

Returns

Continues on if parsing of the event was successful. Returns NULL if a parse error occurred and sets _error appropriately.

Since: 2.0

mmd_emitter_start_stream ()

gboolean
mmd_emitter_start_stream (yaml_emitter_t *emitter,
                          GError **error);

Parameters

emitter	A libyaml emitter object that will be positioned at the beginning of a new YAML output stream.	[inout]
error	A GError that will return the reason for any error.	[out]

Returns

TRUE if the YAML stream was started successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

mmd_emitter_end_stream ()

gboolean
mmd_emitter_end_stream (yaml_emitter_t *emitter,
                        GError **error);

Parameters

emitter	A libyaml emitter object that is positioned at the end of a YAML output stream to be closed.	[inout]
error	A GError that will return the reason for any error.	[out]

Returns

TRUE if the YAML stream was closed successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

mmd_emitter_start_document ()

gboolean
mmd_emitter_start_document (yaml_emitter_t *emitter,
                            GError **error);

Emits a YAML document start header line.

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new YAML document will be written.	[inout]
error	A GError that will return the reason for any error.	[out]

Returns

TRUE if the YAML document was started successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

mmd_emitter_end_document ()

gboolean
mmd_emitter_end_document (yaml_emitter_t *emitter,
                          GError **error);

Emits a YAML document termination line.

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a YAML document terminator will be written.	[inout]
error	A GError that will return the reason for any error.	[out]

Returns

TRUE if the YAML document was terminated successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

mmd_emitter_start_mapping ()

gboolean
mmd_emitter_start_mapping (yaml_emitter_t *emitter,
                           yaml_mapping_style_t style,
                           GError **error);

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new mapping will be written.	[inout]
style	The YAML mapping style for the output.	[in]
error	A GError that will return the reason for any error.	[out]

Returns

TRUE if the YAML mapping was started successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

mmd_emitter_end_mapping ()

gboolean
mmd_emitter_end_mapping (yaml_emitter_t *emitter,
                         GError **error);

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a mapping ending will be written.	[inout]
error	A GError that will return the reason for any error.	[out]

Returns

TRUE if the YAML mapping was ended successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

mmd_emitter_start_sequence ()

gboolean
mmd_emitter_start_sequence (yaml_emitter_t *emitter,
                            yaml_sequence_style_t style,
                            GError **error);

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new sequence will be written.	[inout]
style	The YAML sequence style for the output.	[in]
error	A GError that will return the reason for any error.	[out]

Returns

TRUE if the YAML sequence was started successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

mmd_emitter_end_sequence ()

gboolean
mmd_emitter_end_sequence (yaml_emitter_t *emitter,
                          GError **error);

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a sequence ending will be written.	[inout]
error	A GError that will return the reason for any error.	[out]

Returns

TRUE if the YAML sequence was ended successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

mmd_emitter_scalar ()

gboolean
mmd_emitter_scalar (yaml_emitter_t *emitter,
                    const gchar *scalar,
                    yaml_scalar_style_t style,
                    GError **error);

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a scalar will be written.	[inout]
scalar	The scalar (string) to be written.	[in]
style	The YAML scalar style for the output.	[in]
error	A GError that will return the reason for any error.	[out]

Returns

TRUE if the YAML scalar was written successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

mmd_emitter_scalar_string ()

gboolean
mmd_emitter_scalar_string (yaml_emitter_t *emitter,
                           const gchar *scalar,
                           GError **error);

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a scalar will be written.	[inout]
scalar	The scalar string to be written. If the string looks like a number or is empty or undefined, it will be explicitly quoted.	[in][nullable]
error	A GError that will return the reason for any error.	[out]

Returns

TRUE if the YAML scalar was written successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.15

mmd_emitter_strv ()

gboolean
mmd_emitter_strv (yaml_emitter_t *emitter,
                  yaml_sequence_style_t seq_style,
                  GStrv list,
                  GError **error);

Parameters

emitter	A libyaml emitter object positioned at the start of where a string sequence will be written.	[inout]
seq_style	The YAML sequence style for the output.	[in]
list	A list that will be emitted to the YAML emitter.	[in]
error	A GError that will return the reason for an emitting error.	[out]

Returns

TRUE if the sequence emitted successfully. FALSE if an error was encountered and sets error appropriately.

Since: 2.0

modulemd_yaml_parse_date ()

GDate *
modulemd_yaml_parse_date (yaml_parser_t *parser,
                          GError **error);

Parameters

parser	A libyaml parser object positioned at the beginning of a date (YYYY-MM-DD) scalar entry.	[inout]
error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

A newly-allocated GDate representing the parsed value. NULL if a parse or validation error occurred and sets error appropriately.

[transfer full]

Since: 2.0

modulemd_yaml_parse_string ()

gchar *
modulemd_yaml_parse_string (yaml_parser_t *parser,
                            GError **error);

Parameters

parser	A libyaml parser object positioned at the beginning of a string scalar entry.	[inout]
error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

A newly-allocated gchar * representing the parsed value. NULL if a parse error occurred and sets error appropriately.

[transfer full]

Since: 2.0

modulemd_yaml_parse_bool ()

gboolean
modulemd_yaml_parse_bool (yaml_parser_t *parser,
                          GError **error);

Parameters

parser	A libyaml parser object positioned at the beginning of a boolean scalar entry.	[inout]
error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

A boolean representing the parsed value. Returns FALSE if a parse error occurred and sets error appropriately.

Since: 2.2

modulemd_yaml_parse_int64 ()

gint64
modulemd_yaml_parse_int64 (yaml_parser_t *parser,
                           GError **error);

Parameters

parser	A libyaml parser object positioned at the beginning of a int64 scalar entry.	[inout]
error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

A 64-bit signed integer representing the parsed value. Returns 0 if a parse error occurred and sets error appropriately.

[transfer full]

Since: 2.0

modulemd_yaml_parse_uint64 ()

guint64
modulemd_yaml_parse_uint64 (yaml_parser_t *parser,
                            GError **error);

Parameters

parser	A libyaml parser object positioned at the beginning of a uint64 scalar entry.	[inout]
error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

A 64-bit unsigned integer representing the parsed value. Returns 0 if a parse error occurred and sets error appropriately.

[transfer full]

Since: 2.0

modulemd_yaml_parse_string_set ()

GHashTable *
modulemd_yaml_parse_string_set (yaml_parser_t *parser,
                                GError **error);

Parameters

parser	A libyaml parser object positioned at the beginning of a sequence with string scalars.	[inout]
error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

A newly-allocated GHashTable * representing the parsed value. All parsed sequence entries are added as keys in the hashtable. NULL if a parse error occurred and sets error appropriately.

[transfer full]

Since: 2.0

modulemd_yaml_parse_string_set_from_map ()

GHashTable *
modulemd_yaml_parse_string_set_from_map
                               (yaml_parser_t *parser,
                                const gchar *key,
                                gboolean strict,
                                GError **error);

Function for retrieving a string set from a single-key map such as data.artifacts, data.api or data.filter from a module stream document.

Parameters

parser	A libyaml parser object positioned at the beginning of a map containing a single key which is a sequence with string scalars.	[inout]
key	The key in a single-key mapping whose contents should be returned as a string set.	[in]
strict	Whether the parser should return failure if it encounters an unknown mapping key or if it should ignore it.	[in]
error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

A newly-allocated GHashTable * representing the parsed values. All parsed sequence entries are added as keys in the hashtable. NULL if a parse error occurred and sets error appropriately.

[transfer full]

Since: 2.0

modulemd_yaml_parse_string_string_map ()

GHashTable *
modulemd_yaml_parse_string_string_map (yaml_parser_t *parser,
                                       GError **error);

Function for retrieving a hash table from a str/str map such as data.dependencies in ModuleStreamV1.

Parameters

parser	A libyaml parser object positioned at the beginning of a map containing a scalar/scalar key/value pairs.	[inout]
error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

A newly-allocated GHashTable * representing the parsed values. NULL if a parse error occurred and sets error appropriately.

[transfer full]

Since: 2.0

modulemd_yaml_parse_nested_set ()

GHashTable *
modulemd_yaml_parse_nested_set (yaml_parser_t *parser,
                                GError **error);

Function for retrieving a hash table from a str/string-set map such as data.dependencies in ModulemdModuleStreamV2.

Parameters

parser	A libyaml parser object positioned at the beginning of a map containing scalar keys with string set values.	[inout]
error	A GError that will return the reason for a parsing or validation error.	[out]

Returns

A newly-allocated GHashTable * representing the parsed values. NULL if a parse error occurred and sets error appropriately.

[transfer full]

Since: 2.10

modulemd_yaml_emit_nested_set ()

gboolean
modulemd_yaml_emit_nested_set (yaml_emitter_t *emitter,
                               GHashTable *table,
                               GError **error);

Parameters

emitter	A libyaml emitter object that is positioned where a nested set (a map containing scalar keys with string set values) should occur.	[inout]
table	The nested set to emit.	[in]
error	A GError that will return the reason for failing to emit.	[out]

Returns

TRUE if the nested set emitted successfully. FALSE if an error was encountered and sets error appropriately.

Since: 2.10

modulemd_yaml_parse_document_type ()

ModulemdSubdocumentInfo *
modulemd_yaml_parse_document_type (yaml_parser_t *parser);

Reads through a YAML subdocument to retrieve the document type, metadata version and the data section.

Parameters

parser

A libyaml parser object positioned at the beginning of a yaml subdocument immediately prior to a YAML_DOCUMENT_START_EVENT.

[inout]

Returns

A ModulemdSubdocumentInfo with information on the parse results.

[transfer full]

Since: 2.0

modulemd_yaml_emit_document_headers ()

gboolean
modulemd_yaml_emit_document_headers (yaml_emitter_t *emitter,
                                     ModulemdYamlDocumentTypeEnum doctype,
                                     guint64 mdversion,
                                     GError **error);

Creates the YAML header and returns emitter positioned just before the YAML_MAPPING_START for the "data:" section.

Parameters

emitter	A libyaml emitter object that is positioned where the `YAML_DOCUMENT_START_EVENT` should occur (so this must be after either a `YAML_STREAM_START_EVENT` or `YAML_DOCUMENT_END_EVENT`).	[inout]
doctype	The document type (see ModulemdYamlDocumentTypeEnum).	[in]
mdversion	The metadata version for this document.	[in]
error	A GError that will return the reason for failing to emit.	[out]

Returns

TRUE if the document emitted successfully. FALSE if an error was encountered and sets error appropriately.

Since: 2.0

modulemd_yaml_emit_variant ()

gboolean
modulemd_yaml_emit_variant (yaml_emitter_t *emitter,
                            GVariant *variant,
                            GError **error);

Parameters

emitter	A libyaml emitter object that is positioned where the variant should occur.	[inout]
variant	The variant to emit. It must be either a boolean, string, array or dictionary.	[in]
error	A GError that will return the reason for failing to emit.	[out]

Returns

TRUE if the variant emitted successfully. FALSE if an error was encountered and sets error appropriately.

Since: 2.0

mmd_variant_from_scalar ()

GVariant *
mmd_variant_from_scalar (const gchar *scalar);

Parameters

scalar

A string or boolean value to read into a GVariant.

[in]

Returns

A new, floating GVariant representing a string or boolean value matching the scalar passed in.

[transfer full]

Since: 2.0

mmd_variant_from_mapping ()

GVariant *
mmd_variant_from_mapping (yaml_parser_t *parser,
                          GError **error);

Parameters

parser	A YAML parser positioned just after a `MAPPING_START`.	[inout]
error	A GError that will return the reason for failing to parse.	[out]

Returns

A new, floating GVariant representing a hash table with string keys and GVariant values.

[transfer full]

Since: 2.0

mmd_variant_from_sequence ()

GVariant *
mmd_variant_from_sequence (yaml_parser_t *parser,
                           GError **error);

Parameters

parser	A YAML parser positioned just after a `SEQUENCE_START`.	[inout]
error	A GError that will return the reason for failing to parse.	[out]

Returns

A new, floating GVariant representing a list of GVariant values.

[transfer full]

Since: 2.0

mmd_parse_xmd ()

GVariant *
mmd_parse_xmd (yaml_parser_t *parser,
               GError **error);

Parameters

parser	A YAML parser positioned just after an 'xmd' mapping key.	[inout]
error	A GError that will return the reason for failing to parse.	[out]

Returns

A new, floating GVariant representing the parsed XMD (eXtensible MetaData).

[transfer full]

Since: 2.10

skip_unknown_yaml ()

gboolean
skip_unknown_yaml (yaml_parser_t *parser,
                   GError **error);

This function is used to skip a section of YAML that contains unknown keys. The intent here is that it will allow libmodulemd to be forward-compatible with new, backwards-compatible changes in the metadata format. This function will advance parser to just before the next key in the map.

Parameters

parser	A YAML parser positioned just after an unexpected map key.	[inout]
error	A GError that will return the reason for failing to parse.	[out]

Returns

TRUE if the parser was able to skip the unknown values safely. FALSE and sets error appropriately if the document was malformed YAML.

SKIP_UNKNOWN()

#define             SKIP_UNKNOWN(_parser, _returnval, ...)

This convenience macro is a wrapper around skip_unknown_yaml() used to skip a section of YAML that contains unknown keys.

NOTE: Local variables strict and error are expected to be present in the code from which this macro is used.

Parameters

_parser	A YAML parser positioned just after an unexpected map key.	[inout]
_returnval	The error value to return.	[in]
...	Additional argument(s) to pass to `g_set_error()` when setting `error`.	[in]

Returns

If strict is TRUE or skip_unknown_yaml() fails, _returnval is returned and error is set appropriately.

Since: 2.0

NON_EMPTY_TABLE()

#define NON_EMPTY_TABLE(table) (g_hash_table_size (table) != 0)

Parameters

table

A GHashTable.

Returns

FALSE if table is empty, otherwise TRUE.

Since: 2.0

NON_EMPTY_ARRAY()

#define NON_EMPTY_ARRAY(array) (array->len != 0)

Parameters

array

A GPtrArray.

Returns

FALSE if array is empty, otherwise TRUE.

Since: 2.0

EMIT_SCALAR_FULL()

#define             EMIT_SCALAR_FULL(emitter, error, value, style)

Emits scalar value using style style .

Parameters

emitter	A libyaml emitter object positioned where a scalar belongs in the YAML document.	[inout]
error	A GError that will return the reason for an output error.	[out]
value	The scalar (string) to be written.	[in]
style	The YAML scalar style for the output.	[in]

Returns

Continues on if the YAML scalar was written successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.1

EMIT_SCALAR()

#define             EMIT_SCALAR(emitter, error, value)

Emits scalar value using style YAML_PLAIN_SCALAR_STYLE.

Parameters

emitter	A libyaml emitter object positioned where a scalar belongs in the YAML document.	[inout]
error	A GError that will return the reason for an output error.	[out]
value	The scalar (string) to be written.	[in]

Returns

Continues on if the YAML scalar was written successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_SCALAR_STRING()

#define             EMIT_SCALAR_STRING(emitter, error, value)

Emits a string value . Using style YAML_DOUBLE_QUOTED_SCALAR_STYLE style if the value is empty or looks like a number. Otherwise, using YAML_PLAIN_SCALAR_STYLE style. This autoquoting of number-like strings is in place to prevent other YAML applications from trimming trailing null digits and to force them handle the values as a string (e.g. "1.0" will be serialized as "1.0" instead of 1.0 which some applications interpret as 1. We do not always quote to keep the YAML file concise and similar to previous serialization styles.

Parameters

emitter	A libyaml emitter object positioned where a scalar belongs in the YAML document.	[inout]
error	A GError that will return the reason for an output error.	[out]
value	The scalar (string) to be written.	[in]

Returns

Continues on if the YAML scalar was written successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.15

EMIT_KEY_VALUE_FULL()

#define             EMIT_KEY_VALUE_FULL(emitter, error, key, value, style)

Emits key/value pair (key : value ) using style style .

NOTE: This macro outputs both a key and a value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object positioned where a scalar belongs in the YAML document.	[inout]
error	A GError that will return the reason for an output error.	[out]
key	The key (string) to be written.	[in]
value	The scalar (string) to be written.	[in]
style	The YAML scalar style for the output.	[in]

Returns

Continues on if the YAML key/value pair was written successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.1

EMIT_KEY_VALUE()

#define             EMIT_KEY_VALUE(emitter, error, key, value)

Emits key/value pair (key : value ) using style YAML_PLAIN_SCALAR_STYLE.

NOTE: This macro outputs both a key and a value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object positioned where a scalar belongs in the YAML document.	[inout]
error	A GError that will return the reason for an output error.	[out]
key	The key (string) to be written.	[in]
value	The scalar (string) to be written.	[in]

Returns

Continues on if the YAML key/value pair was written successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_KEY_VALUE_STRING()

#define             EMIT_KEY_VALUE_STRING(emitter, error, key, value)

Emits key/value pair (key : value ) using YAML_DOUBLE_QUOTED_SCALAR_STYLE style for number-like keys/values, YAML_PLAIN_SCALAR_STYLE otherwise.

NOTE: This macro outputs both a key and a value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object positioned where a scalar belongs in the YAML document.	[inout]
error	A GError that will return the reason for an output error.	[out]
key	The key (string) to be written.	[in]
value	The scalar (string) to be written.	[in]

Returns

Continues on if the YAML key/value pair was written successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.15

EMIT_KEY_VALUE_IF_SET()

#define             EMIT_KEY_VALUE_IF_SET(emitter, error, key, value)

Emits key/value pair (key : value ) only if value is not NULL. The emission is performed in YAML_PLAIN_SCALAR_STYLE style.

NOTE: This macro outputs both a key and a value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object positioned where a scalar belongs in the YAML document.	[inout]
error	A GError that will return the reason for an output error.	[out]
key	The key (string) to be written.	[in]
value	The scalar (string) to be written.	[in]

Returns

Continues on if value is NULL or the YAML key/value pair was written successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_KEY_VALUE_STRING_IF_SET()

#define             EMIT_KEY_VALUE_STRING_IF_SET(emitter, error, key, value)

Emits key/value pair (key : value ) only if value is not NULL. The emission is performed in YAML_DOUBLE_QUOTED_SCALAR_STYLE style if the key/value looks like a number, otherwise in YAML_PLAIN_SCALAR_STYLE style.

NOTE: This macro outputs both a key and a value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object positioned where a scalar belongs in the YAML document.	[inout]
error	A GError that will return the reason for an output error.	[out]
key	The key (string) to be written.	[in]
value	The scalar (string) to be written.	[in]

Returns

Continues on if value is NULL or the YAML key/value pair was written successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.15

EMIT_MAPPING_START_WITH_STYLE()

#define             EMIT_MAPPING_START_WITH_STYLE(emitter, error, style)

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new mapping will be written.	[inout]
error	A GError that will return the reason for any error.	[out]
style	The YAML mapping style for the output.	[in]

Returns

Continues on if the YAML mapping was started successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_MAPPING_START()

#define             EMIT_MAPPING_START(emitter, error)

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new mapping will be written.	[inout]
error	A GError that will return the reason for any error.	[out]

Returns

Continues on if the YAML mapping was started successfully using style YAML_BLOCK_MAPPING_STYLE. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_MAPPING_END()

#define             EMIT_MAPPING_END(emitter, error)

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a mapping ending will be written.	[inout]
error	A GError that will return the reason for any error.	[out]

Returns

Continues on if the YAML mapping was ended successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_SEQUENCE_START_WITH_STYLE()

#define             EMIT_SEQUENCE_START_WITH_STYLE(emitter, error, style)

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new sequence will be written.	[inout]
error	A GError that will return the reason for any error.	[out]
style	The YAML sequence style for the output.	[in]

Returns

Continues on if the YAML sequence was started successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_SEQUENCE_START()

#define             EMIT_SEQUENCE_START(emitter, error)

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new sequence will be written.	[inout]
error	A GError that will return the reason for any error.	[out]

Returns

Continues on if the YAML sequence was started successfully using style YAML_BLOCK_SEQUENCE_STYLE. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_SEQUENCE_END()

#define             EMIT_SEQUENCE_END(emitter, error)

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a sequence ending will be written.	[inout]
error	A GError that will return the reason for any error.	[out]

Returns

Continues on if the YAML sequence was ended successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_HASHTABLE_VALUES_IF_NON_EMPTY()

#define             EMIT_HASHTABLE_VALUES_IF_NON_EMPTY(                                   \
              emitter, error, key, table, emitfn)

Does nothing if the hash table table is empty. Otherwise, calls emitfn to emit each of the values from table identified as key .

NOTE: This macro outputs both a key and a sub-mapping value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new mapping will be written.	[inout]
error	A GError that will return the reason for any error.	[out]
key	The name to be used as the identifier for the output mapping.	[in]
table	The GHashTable that is to be output.	[in]
emitfn	A function used to emit each of the hash table values.	[in]

Returns

Continues on if the YAML mapping was output successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_HASHTABLE_KEY_VALUES_IF_NON_EMPTY()

#define             EMIT_HASHTABLE_KEY_VALUES_IF_NON_EMPTY(emitter, error, key, table)

Does nothing if the hash table table is empty. Otherwise, outputs a YAML mapping with the key/value pairs from table identified as key .

NOTE: This macro outputs both a key and a sub-mapping value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new mapping will be written.	[inout]
error	A GError that will return the reason for any error.	[out]
key	The name to be used as the identifier for the output mapping.	[in]
table	The GHashTable that is to be output. Both the keys and values must be strings.	[in]

Returns

Continues on if the YAML mapping was output successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_STRING_SET()

#define             EMIT_STRING_SET(emitter, error, key, table)

Raises an error if the hash table table is empty. Otherwise, outputs a YAML sequence using style YAML_BLOCK_SEQUENCE_STYLE with the keys from table identified as key .

NOTE: This macro outputs both a key and an array value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new sequence will be written.	[inout]
error	A GError that will return the reason for any error.	[out]
key	The name to be used as the identifier for the output sequence.	[in]
table	The GHashTable that is to be output. The keys are expected to be a `set()` of strings.	[in]

Returns

Continues on if the YAML sequence was output successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_STRING_SET_IF_NON_EMPTY()

#define             EMIT_STRING_SET_IF_NON_EMPTY(emitter, error, key, table)

Does nothing if the hash table table is empty. Otherwise, outputs a YAML sequence using style YAML_BLOCK_SEQUENCE_STYLE with the keys from table identified as key .

NOTE: This macro outputs both a key and an array value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new sequence will be written.	[inout]
error	A GError that will return the reason for any error.	[out]
key	The name to be used as the identifier for the output sequence.	[in]
table	The GHashTable that is to be output. The keys are expected to be a `set()` of strings.	[in]

Returns

Continues on if the YAML sequence was output successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_STRING_SET_FULL()

#define             EMIT_STRING_SET_FULL(emitter, error, key, table, sequence_style)

Outputs a YAML sequence with the keys from table identified as key .

NOTE: This macro outputs both a key and an array value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new sequence will be written.	[inout]
error	A GError that will return the reason for any error.	[out]
key	The name to be used as the identifier for the output sequence.	[in]
table	The GHashTable that is to be output. The keys are expected to be a `set()` of strings.	[in]
sequence_style	The YAML sequence style for the output.	[in]

Returns

Continues on if the YAML sequence was output successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.1

EMIT_ARRAY_VALUES()

#define             EMIT_ARRAY_VALUES(emitter, error, key, array, emitfn)

Raises an error if the array array is empty. Otherwise, calls emitfn to emit each of the values from array identified as key .

NOTE: This macro outputs both a key and an array value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new sequence will be written.	[inout]
error	A GError that will return the reason for any error.	[out]
key	The name to be used as the identifier for the output sequence.	[in]
array	The GPtrArray that is to be output.	[in]
emitfn	A function used to emit each of the array values.	[in]

Returns

Continues on if the YAML sequence was output successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

EMIT_ARRAY_VALUES_IF_NON_EMPTY()

#define             EMIT_ARRAY_VALUES_IF_NON_EMPTY(emitter, error, key, array, emitfn)

Does nothing if the array array is empty. Otherwise, calls emitfn to emit each of the values from array identified as key .

NOTE: This macro outputs both a key and an array value for that key, thus it must only be used from within a YAML mapping.

Parameters

emitter	A libyaml emitter object that is positioned at the start of where a new sequence will be written.	[inout]
error	A GError that will return the reason for any error.	[out]
key	The name to be used as the identifier for the output sequence.	[in]
array	The GPtrArray that is to be output.	[in]
emitfn	A function used to emit each of the array values.	[in]

Returns

Continues on if the YAML sequence was output successfully. Returns FALSE if an error occurred and sets error appropriately.

Since: 2.0

Types and Values

enum ModulemdYamlDocumentTypeEnum

Members

MODULEMD_YAML_DOC_UNKNOWN	Represents an unknown YAML document type.
MODULEMD_YAML_DOC_MODULESTREAM	Represents a `modulemd` (see ModulemdModuleStream) YAML document type.
MODULEMD_YAML_DOC_DEFAULTS	Represents a `modulemd-defaults` (see ModulemdDefaultsV1) YAML document type.
MODULEMD_YAML_DOC_TRANSLATIONS	Represents a `modulemd-translations` (see ModulemdTranslation) YAML document type.
MODULEMD_YAML_DOC_PACKAGER	Represents a `modulemd-packager` document. V2 is a subset of ModulemdModuleStreamV2 containing only the attributes that a package maintainer should modify. V3 (see ModulemdPackagerV3) is a new YAML document type. Since: 2.9
MODULEMD_YAML_DOC_OBSOLETES	Represents a `modulemd-obsoletes` document (see ModulemdObsoletes) YAML document type. Since: 2.10

Since: 2.0