Evaluate contained overlay directives when target fragment is missing from "left"
- Dominant language
- Go
- Stars
- 1.9k
- Forks
- 167
- PR merge metrics
- No merged PRs in 30d
Description
**As a** Configuration Author
**I want** the overlay directives I include within an optional fragment (i.e. `missing_ok=True`) to be evaluated (when the parent of the fragment is not present in the target on the "left", the directives are not being evalutated.
**so that** overlays behave the way I expect, rather than insert a chunk of plain YAML.
---
## 🟢 Main Flow
**Given** an overlay that contains a fragment that optionally matches
**And** that fragment _itself_ contains overlay directives
`config1.yml`
```yaml
---
foo: 42
```
`config2.yml`
```yaml
---
foo: 42
bar:
qux: deadbeef
quuz: prefix
list:
- zeroth
```
`overlay.yml`
```yaml
#@ load("@ytt:overlay", "overlay")
#@overlay/match by=overlay.all, expects="1+"
---
#@overlay/match missing_ok=True
bar:
#@overlay/match missing_ok=True
#@overlay/remove
qux: toasty
#@overlay/match missing_ok=True
baz: added from overlay
#@overlay/match when=1
#@overlay/replace via=lambda left,right: left + "-" + right
quuz: suffix
#@overlay/match missing_ok=True
list:
- first
#@overlay/insert after=True
- second
```
**When** I run this through ytt
```console
$ ytt -f config1.yml -f config2.yml -f overlay.yml
```
**Then** I should see that those overlay directives (e.g. the `@overlay/remove` on `ree:`) contained within the inserted parent (i.e. `bar:`) are executed:
`config1.yml`
```yaml
---
foo: 42
bar:
baz: added from overlay
list:
- first
- second
```
`config2.yml`
```yaml
---
foo: 42
bar:
baz: added from overlay
quuz: prefix-suffix
list:
- zeroth
- first
- second
```
... instead of https://carvel.dev/ytt/#gist:https://gist.github.com/pivotaljohn/281e6c3d1d77c7e2b1e4763a0f400add
Explicitly:
- `bar.qux:` does not appear in either result given that it's `@overlay/remove`d
- `bar.quuz:`
- appears only in `config2.yml` given that it's `@overlay/match when=1`
- that the value is calculated based on the expression given to `@overlay/replace`
- `list:`
- appears in both `config1.yml` and `config2.yml`
- "second" is the 3rd item in the list in `config2.yml` given that it's `@overlay/insert`ed there.
## 📖 Documentation
**Given** I am looking to understand how overlay directives behave when their parent matched via `missing_ok=True` (or `expects="0+"` or similar)
**When** I skim through the docs
**Then** I see this behavior explicitly described
---
Note:
- for directives that present the "left side" to the author (i.e. `@overlay/match`, `@overlay/replace`, `@overlay/assert`), the value for `left` should be `None`.
---
To Do:
- [ ] when complete, resolve/close #308.
Contributor guide
Research direction
Start by running the ytt command with the config1.yml, config2.yml, and overlay.yml examples from the issue, then inspect the overlay directive evaluation path. Done means contained directives run when a missing_ok=True parent is inserted, producing the shown YAML results, handling left as None where specified, and documenting the behavior; resolve #308 when complete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- cli, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100