yaml

Provides YAML file handling functionality for the Zephyr build system.

This module offers support for reading, writing, and manipulating YAML files within the Zephyr build system. It supports basic key-value pairs, nested objects, lists, and lists of maps.

Supported YAML Features

The module supports the following YAML constructs:

Basic key-value pairs

foo: bar

Nested objects

foo:
  bar: baz

Simple lists

foos:
  - foo1
  - foo2
  - foo3

Lists of maps

foo:
  - bar: val1
    baz: val1
  - bar: val2
    baz: val2

Example Usage

include(yaml)

# Create a new YAML context
yaml_create(NAME my_yaml FILE my_file.yaml)

# Set some values
yaml_set(NAME my_yaml KEY foo VALUE bar)
yaml_set(NAME my_yaml KEY list LIST item1 item2 item3)

# Append a map to a list
yaml_set(NAME my_yaml KEY list APPEND LIST MAP "name: test, value: 42")

# Save the context to file
yaml_save(NAME my_yaml)

# my_file.yaml now contains:
#
# foo: bar
# list:
#   - item1
#   - item2
#   - item3
#   - name: test
#     value: 42

Commands

yaml_context

Query the status of a YAML context.

yaml_context(EXISTS NAME <name> <result>)

EXISTS: Check if the YAML context exists in the current scope. If the context exists, then TRUE is returned in <result>.
NAME <name>: Name of the YAML context.
<result>: Variable to store the result of the query.

yaml_create

Create a new empty YAML context.

yaml_create(NAME <name> [FILE <file>])

NAME <name>: Name of the YAML context.
FILE <file>: Path to file to be used together with this YAML context. This file will be used when yaml_save() is called.

yaml_load

Load an existing YAML file into a YAML context.

yaml_load(FILE <file> NAME <name>)

FILE <file>: Path to file to load.
NAME <name>: Name of the YAML context.

yaml_get

Get the value of a key from a YAML context.

yaml_get(<out-var> NAME <name> KEY <key>...)

NAME <name>: Name of the YAML context.
KEY <key>...: Name of key(s) to retrieve. Multiple keys can be specified for nested access.
<out-var>: Variable to store the retrieved value.

If the key represents a list, the list is returned. Behavior is undefined if the key points to a complex object.

yaml_length

Get the length of an array defined by a key.

yaml_length(<out-var> NAME <name> KEY <key>...)

NAME <name>: Name of the YAML context.
KEY <key>...: Name of key defining the list.
<out-var>: Variable to store the length.

Returns -1 if the key does not define an array.

yaml_set

Set a value or list of values in a YAML context.

yaml_set(NAME <name> KEY <key>... [GENEX] VALUE <value>)
yaml_set(NAME <name> KEY <key>... [APPEND] [GENEX] LIST <value>...)
yaml_set(NAME <name> KEY <key>... [APPEND] LIST MAP <map1> MAP <map2> MAP ...)

NAME <name>: Name of the YAML context.
KEY <key>...: Name of key(s) to set.
VALUE <value>: New value for the key.
LIST <values>: New list of values for the key.
APPEND: Append the list of values to the existing list.
GENEX: The value(s) contain generator expressions.
MAP <map>: Map with key-value pairs where pairs are separated by ‘,’ and key-value by ‘:’. Format: "<key1>: <value1>, <key2>: <value2>, ...". Multiple MAP arguments can be given to separate maps when adding to a list. Cannot be used with GENEX.

Note: If a map value contains commas, the value must be quoted in single quotes and commas must be double escaped: 'A \\,string'

yaml_remove

Remove a key from a YAML context.

yaml_remove(NAME <name> KEY <key>...)

NAME <name>: Name of the YAML context.
KEY <key>...: Name of key(s) to remove. Multiple keys can be specified for nested access.

yaml_save

Write a YAML context to a file.

yaml_save(NAME <name> [FILE <file>])

NAME <name>: Name of the YAML context.
FILE <file>: Path to file to write the context. If not given, uses the FILE property of the YAML context.

If the context uses generator expressions, keys containing them will initially be written as comments. The full contents will be available at build time. Build steps depending on the file being complete must depend on the name_yaml_saved target.