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