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_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_KEY_VALUE_FULL()
#define | EMIT_KEY_VALUE()
#define | EMIT_KEY_VALUE_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_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_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_IF_SET()

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

Emits key/value pair (`key` : `value` ) only if `value` is not NULL.

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_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