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

GQuark	modulemd_yaml_error_quark ()
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 ()
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 ()
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

#define

MODULEMD_YAML_ERROR

Description

Functions

modulemd_yaml_error_quark ()

GQuark
modulemd_yaml_error_quark (void);

write_yaml_string ()

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

modulemd_yaml_string_free ()

void
modulemd_yaml_string_free (modulemd_yaml_string *yaml_string);

mmd_yaml_get_event_name ()

const gchar *
mmd_yaml_get_event_name (yaml_event_type_t type);

MMD_INIT_YAML_PARSER()

#define             MMD_INIT_YAML_PARSER(_parser)

MMD_INIT_YAML_EMITTER()

#define             MMD_INIT_YAML_EMITTER(_emitter)

MMD_INIT_YAML_EVENT()

#define             MMD_INIT_YAML_EVENT(_event)

MMD_INIT_YAML_STRING()

#define             MMD_INIT_YAML_STRING(_emitter, _string)

MMD_REINIT_YAML_STRING()

#define             MMD_REINIT_YAML_STRING(_emitter, _string)

YAML_PARSER_PARSE_WITH_EXIT_FULL()

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

YAML_PARSER_PARSE_WITH_EXIT_BOOL()

#define             YAML_PARSER_PARSE_WITH_EXIT_BOOL(_parser, _event, _error)

YAML_PARSER_PARSE_WITH_EXIT_INT()

#define             YAML_PARSER_PARSE_WITH_EXIT_INT(_parser, _event, _error)

YAML_PARSER_PARSE_WITH_EXIT()

#define             YAML_PARSER_PARSE_WITH_EXIT(_parser, _event, _error)

MMD_EMIT_WITH_EXIT_FULL()

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

MMD_EMIT_WITH_EXIT()

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

MMD_EMIT_WITH_EXIT_PTR()

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

MMD_YAML_ERROR_EVENT_EXIT_FULL()

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

MMD_YAML_ERROR_EVENT_EXIT()

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

MMD_YAML_ERROR_EVENT_EXIT_BOOL()

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

MMD_YAML_ERROR_EVENT_EXIT_INT()

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

MMD_SET_PARSED_YAML_STRING()

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

mmd_emitter_start_stream ()

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

mmd_emitter_end_stream ()

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

mmd_emitter_start_document ()

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

mmd_emitter_end_document ()

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

mmd_emitter_start_mapping ()

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

mmd_emitter_end_mapping ()

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

mmd_emitter_start_sequence ()

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

mmd_emitter_end_sequence ()

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

mmd_emitter_scalar ()

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

mmd_emitter_strv ()

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

Parameters

emitter	A yaml emitter object positioned at the beginning of a value place to emit a sequence.	[in]
seq_style	The YAML sequence style for the output.	[in]
list	A list that will be emitted to the YAML emitter.
error	A GError that will return the reason for an emitting error.	[out]

Returns

A boolean whether emitting the sequence was succesful.

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 occured 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 int64 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 occured 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 occured 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 occured 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 GHashtTable * representing the parsed value. All parsed sequence entries are added as keys in the hashtable. NULL if a parse error occured 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 GHashtTable * representing the parsed values. All parsed sequence entries are added as keys in the hashtable. NULL if a parse error occured 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 GHashtTable * representing the parsed values. NULL if a parse error occured and sets error appropriately.

[transfer full]

Since: 2.0

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 SubdocumentInfo 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,
                                     enum ModulemdYamlDocumentType 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 ModulemdYamlDocumentType).	[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 succesfully. 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

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, ...)

NON_EMPTY_TABLE()

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

NON_EMPTY_ARRAY()

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

EMIT_SCALAR_FULL()

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

EMIT_SCALAR()

#define             EMIT_SCALAR(emitter, error, value)

EMIT_KEY_VALUE_FULL()

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

EMIT_KEY_VALUE()

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

EMIT_KEY_VALUE_IF_SET()

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

EMIT_MAPPING_START_WITH_STYLE()

#define             EMIT_MAPPING_START_WITH_STYLE(emitter, error, style)

EMIT_MAPPING_START()

#define             EMIT_MAPPING_START(emitter, error)

EMIT_MAPPING_END()

#define             EMIT_MAPPING_END(emitter, error)

EMIT_SEQUENCE_START_WITH_STYLE()

#define             EMIT_SEQUENCE_START_WITH_STYLE(emitter, error, style)

EMIT_SEQUENCE_START()

#define             EMIT_SEQUENCE_START(emitter, error)

EMIT_SEQUENCE_END()

#define             EMIT_SEQUENCE_END(emitter, error)

EMIT_HASHTABLE_VALUES_IF_NON_EMPTY()

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

EMIT_HASHTABLE_KEY_VALUES_IF_NON_EMPTY()

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

EMIT_STRING_SET()

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

EMIT_STRING_SET_IF_NON_EMPTY()

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

EMIT_STRING_SET_FULL()

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

EMIT_ARRAY_VALUES()

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

EMIT_ARRAY_VALUES_IF_NON_EMPTY()

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

Types and Values

MODULEMD_YAML_ERROR

#define MODULEMD_YAML_ERROR modulemd_yaml_error_quark ()