[yamlcomposer] Add !for loops, scoped local variables (!var), and enhance conditionals (!elseif, !else)

[jimtng]

Summary

This PR introduces several significant enhancements to the YAML Composer, focusing on dynamic content generation, improved conditional logic, and expanded expression support.

Key Features

• Loop Support (!for): Add a new directive that allows for dynamic sequence iteration and templating within YAML definitions.
• Key-Level !if: Introduce a shorthand form for the !if tag to streamline conditional blocks and improve readability.
• Range Expressions: Add support for Jinjava range() functions and Ruby-style range syntax ([1..5] for inclusive and [1...5] for exclusive ranges).
• Enumerate Support: Add enumerate as both a filter and a function, supporting list and map iteration with .key and .value accessors.
• Local Variables (!var): Introduce the !var directive to declare scoped variables within maps or list contexts, improving modularity and local configuration reuse.

Internal Changes

• Directive Processing Phase: Introduce a dedicated directive processing phase to the composer's transformation pipeline. This provides a more robust framework for handling structural tags like !for and !if.
• Test Suite Reorganization: The existing test suite has been split into multiple specialized files. This reorganization improves maintainability and makes it easier to navigate the growing number of test cases.

Examples:

variables:
  environment: prod
  dev_ip: 192.168.1.50
  prod_ip: 10.0.0.20
  local_ip: 127.0.0.1

  things:
    - livingroom
    - bedroom

  channels:
    temperature:
      type: number
      label: Room Temperature
    humidity:
      type: number
      label: Humidity
    battery:
      type: number
      label: Battery Level
      stateDescription:
        pattern: "%.1f %%"

things:
  mqtt:broker:main:
    label: Main MQTT Broker
    config:
      # Key-Level if/elseif/else conditional
      !if environment == 'dev':
        host: ${dev_ip}
      !elseif environment == 'prod':
        host: ${prod_ip}
      !else ~: # Note the extra ~ is required for yaml compliance
        host: ${local_ip}

      # That can also be done with VARS (existing feature)
      host_with_vars: ${VARS[environment + '_ip']}


  # Looping through a list
  !for thing_id in things:
    mqtt:topic:${thing_id}:
      label: ${thing_id | label} MQTT Topic
      bridge: mqtt:broker:main
      channels:
        # Looping through a map
        !for id, channel in channels:
          ${id}:
            type: ${channel.type}
            label: ${channel.label}
            # Another Key-Level if conditional
            !if channel.stateDescription:
              stateDescription: ${channel.stateDescription}

  # Looping through a fixed range
  !for i in [1..4]:
    !var room_name: Room ${i} # Define a local variable here
    mqtt:topic:room${i}:
      label: ${room_name} MQTT Topic
      bridge: mqtt:broker:main
      channels:
        temperature:
          type: number
          label: ${room_name} Temperature

Output:

things:
  mqtt:broker:main:
    label: Main MQTT Broker
    config:
      host: 10.0.0.20
      host_with_vars: 10.0.0.20

  mqtt:topic:livingroom:
    label: Livingroom MQTT Topic
    bridge: mqtt:broker:main
    channels:
      temperature:
        type: number
        label: Room Temperature
      humidity:
        type: number
        label: Humidity
      battery:
        type: number
        label: Battery Level
        stateDescription:
          pattern: '%.1f %%'

  mqtt:topic:bedroom:
    label: Bedroom MQTT Topic
    bridge: mqtt:broker:main
    channels:
      temperature:
        type: number
        label: Room Temperature
      humidity:
        type: number
        label: Humidity
      battery:
        type: number
        label: Battery Level
        stateDescription:
          pattern: '%.1f %%'

  mqtt:topic:room1:
    label: Room 1 MQTT Topic
    bridge: mqtt:broker:main
    channels:
      temperature:
        type: number
        label: Room 1 Temperature

  mqtt:topic:room2:
    label: Room 2 MQTT Topic
    bridge: mqtt:broker:main
    channels:
      temperature:
        type: number
        label: Room 2 Temperature

  mqtt:topic:room3:
    label: Room 3 MQTT Topic
    bridge: mqtt:broker:main
    channels:
      temperature:
        type: number
        label: Room 3 Temperature

  mqtt:topic:room4:
    label: Room 4 MQTT Topic
    bridge: mqtt:broker:main
    channels:
      temperature:
        type: number
        label: Room 4 Temperature

[openhab-bot]

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/kudo-for-yamlcomposer-indicator-and-zigbee-lights-creation-of-items-groups-etc/170091/5

[jimtng]

rebased

[lsiepel]

My codex friend looked at it and found these three comments.

This is an initial AI-assisted review.

[jimtng]

rebased

[lsiepel]

Thanks, LGTM