You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|**Behavior in Maps**| Merges nested key‑value pairs directly into the parent map | Resolves to a single value | Resolves to a single value |
41
41
|**Behavior in Lists**| Splices items directly into the parent list | Returns a single list element (branch may itself be a list) | Returns a single list element (branch may itself be a list) |
|**Unmatched Fallback**| Inactive branches are omitted entirely | Resolves to `null`| Resolves to `null`|
44
44
|**Primary Use Case**| Conditionally merging groups of properties or inserting multiple inline list items | Simple ternary scalar/container assignment | Multi‑branch ternary scalar/container assignment |
45
45
46
46
## Key‑Level Form
47
47
48
48
The key‑level form applies conditional tags directly as map keys.
49
-
The tags `!if`, `!elseif` (and its aliases `!elsif`, `!elif`), and `!else` allow multi‑branch logic using separate map entries.
50
-
Each tag evaluates its expression (except `!else`, which has no expression).
49
+
The tags `!if`, `!elseif` (and its aliases `!elsif`, `!elif`), and `!else ~` allow multi‑branch logic using separate map entries.
50
+
Each tag evaluates its expression (except `!else ~`, which has no expression).
51
51
The nested map underneath the selected tag is merged into the parent map.
52
52
53
53
Use this form when you want to conditionally merge map content into a parent structure.
@@ -100,7 +100,7 @@ mode:
100
100
value: "staging"
101
101
!elif "env == 'dev'": # !elseif, !elif, and !elsif can be used interchangeably
102
102
value: "development"
103
-
!else:
103
+
!else ~:
104
104
value: "unknown"
105
105
```
106
106
@@ -275,6 +275,6 @@ network_settings: !if
275
275
1. **Invalid YAML**: Even inactive branches must be syntactically valid YAML.
276
276
1. **Branch Ordering**: In the key‑level form, branches are evaluated in map order.
277
277
The first truthy `!if` or `!elseif` wins.
278
-
The `!else` branch applies only when no earlier branch matches.
278
+
The `!else ~` branch applies only when no earlier branch matches.
279
279
280
280
See [Expression Syntax](variables.md#expression-syntax) for more details.
Copy file name to clipboardExpand all lines: bundles/org.openhab.io.yamlcomposer/doc/variables.md
+42-40Lines changed: 42 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -35,22 +35,35 @@ variables:
35
35
36
36
### Inline `!var` Directives
37
37
38
-
The `!var` directive allows you to declare or reassign variables **locally within a mapping node**, with visibility extending to all child nodes.
39
-
Directives process sequentially and leave no output keys in the final composed data structure.
38
+
The `!var` directive declares or reassigns variables **inline at the key level** within a mapping.
39
+
Each directive updates the local variable scope immediately and produces **no output key** in the final composed structure.
40
40
41
-
::: tip Scope & Propagation Overview
41
+
Variables defined this way are **local to the current mapping node** and automatically propagate to all of its descendants.
42
42
43
-
1. **Sequential Propagation:** A `!var` directive takes effect immediately for all subsequent entries—including keys, values, and nested child/descendant nodes—within the current mapping context.
44
-
1. **Sub-Block Isolation:** Variables declared inside a nested child mapping remain confined to that specific branch. They propagate down to its descendants, but never leak upward to the parent or outward to adjacent sub-mappings.
43
+
::: tip Scope & Propagation
44
+
45
+
1. **Immediate Effect:**
46
+
Each `!var` directive is evaluated in order. Once declared, the variable is available to all subsequent keys, values, and nested mappings **within the same mapping node**.
47
+
48
+
1. **Mapping‑Node Boundaries:**
49
+
Entering a nested mapping creates a new scope.
50
+
Variables declared in the parent mapping remain visible to the child, but variables declared inside the child mapping do **not** propagate back to the parent.
51
+
52
+
1. **Sequential Evaluation:**
53
+
Variables only apply to entries that appear **after** their declaration.
54
+
Earlier entries in the same mapping cannot see variables declared later.
45
55
46
56
:::
47
57
48
-
`!var`supports single-property declarations (key-form), chained declarations, and block (map) declarations.
58
+
#### `!var` Syntax
59
+
60
+
Declare a variable using the key‑level form:
49
61
50
-
#### Single-Form (Key-Form) Syntax
62
+
```yaml
63
+
!var name: value
64
+
```
51
65
52
-
Use `!var name: value` to declare a single local variable.
Block-form `!var` declarations support YAML merge keys (`<<:`). Merge keys are expanded first, populating default variables into scope before explicit map entries are evaluated. This allows explicit variable declarations to reference or override merged defaults:
102
+
`!var` is valid **only inside mapping nodes**.
86
103
87
-
```yaml
88
-
defaults: &defaults
89
-
base_url: "[http://10.0.0.1](http://10.0.0.1)"
90
-
timeout: 3000
91
-
92
-
service:
93
-
!var:
94
-
<<: *defaults
95
-
timeout: 5000
96
-
endpoint: "${base_url}:${timeout}"
97
-
url: "${endpoint}"
98
-
# Service URL resolves to: "[http://10.0.0.1:5000](http://10.0.0.1:5000)"
99
-
```
104
+
If used inside a list item (e.g., `- !var foo: bar`), the list element becomes a mapping containing the directive.
105
+
If your list item must remain a scalar, declare the variable in the parent mapping instead.
100
106
101
-
::: tip List Context Restriction
102
-
`!var`directives are supported only inside mapping contexts.
103
-
Using `!var` inside a YAML list context (e.g., `- !var foo: bar`) logs a warning and is ignored.
1. **Unquoted Operators**: Expressions containing YAML‑significant characters such as `:` or `?` must be quoted; otherwise YAML interprets those characters as structural syntax and rejects the value.
576
-
1. **Sub-Block Scope Boundaries**: `!var`declarations inside child mapping blocks, templates, or `!for` loops remain confined to that branch and never leak upward or outward to adjacent sub-mappings.
577
579
1. **Reserved Names & System Variables**: System variables (`OPENHAB_CONF`, `__FILE__`, etc.) and Jinja keywords (`true`, `false`, `null`, `in`, `if`) cannot be overwritten.
578
580
1. **`+` vs `~`**: Use `~` for strings to avoid type mismatch errors and use `+` for numbers or lists.
579
581
1. **Jinja Blocks**: Block‑level Jinja constructs (e.g., `{% for %}`) are not supported. Use YAMLComposer’s own control‑flow tags, such as `!if`/`!elseif`/`!else` and `!for`.
Copy file name to clipboardExpand all lines: bundles/org.openhab.io.yamlcomposer/src/main/java/org/openhab/io/yamlcomposer/internal/core/DirectiveProcessor.java
+7-15Lines changed: 7 additions & 15 deletions
Original file line number
Diff line number
Diff line change
@@ -238,22 +238,14 @@ public DirectiveProcessor(BufferedLogger logger) {
Copy file name to clipboardExpand all lines: bundles/org.openhab.io.yamlcomposer/src/main/java/org/openhab/io/yamlcomposer/internal/directives/VarDirective.java
+6-23Lines changed: 6 additions & 23 deletions
Original file line number
Diff line number
Diff line change
@@ -21,33 +21,16 @@
21
21
* in the current evaluation context (such as maps or list-control items) and produce no direct
22
22
* data entries in the final output.
23
23
* <p>
24
-
* Supported syntaxes:
24
+
* Supported syntax:
25
25
* <ul>
26
-
* <li><b>{@link SingleForm}:</b> {@code !var name: value} — assigns a single variable where the
27
-
* name is defined in the tag scalar argument and the value is provided by the entry value.</li>
Copy file name to clipboardExpand all lines: bundles/org.openhab.io.yamlcomposer/src/main/java/org/openhab/io/yamlcomposer/internal/processors/VarProcessor.java
0 commit comments