Optionally, `overlay/insert` via function

[mamachanko]

The insert overlay action has an optional 'via' kwarg, which receives the left and right node and produces the new right node, similar to the replace overlay action.

For example, this allows to add a ConfigMap into every matched Kubernetes Namespace without knowing their names in advance:

#@ load("@ytt:overlay", "overlay")

#@ for i in range(3):
---
apiVersion: v1
kind: Namespace
metadata:
  name: #@ i
#@ end

#@ def cm(ns):
apiVersion: v1
kind: ConfigMap
metadata:
  name: insert
  namespace: #@ ns["metadata"]["name"]
#@ end

#@overlay/match by=overlay.subset({"kind": "Namespace"}), expects="0+"
#@overlay/insert after=True, via=lamda ns,_: cm(ns)
---

produces:

apiVersion: v1
kind: Namespace
metadata:
  name: 0
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: insert
  namespace: 0
---
apiVersion: v1
kind: Namespace
metadata:
  name: 1
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: insert
  namespace: 1
---
apiVersion: v1
kind: Namespace
metadata:
  name: 2
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: insert
  namespace: 2

---

Addresses #738

Qs for the maintainers:

• What do you think about the suggested API?
• @jtigger mentioned that: "the solution to this is likely to also resolve #718". However, I don't see how.
• InsertAnnotation.Value is mostly a reproduction of ReplaceAnnotation.Value sans comments and todos. It felt not right to copy over those unless that is preferred.
• If via=lambda ... expects more than one arg it does not produce a great error message, much like overlay/replace's via. For example: overlay.apply: Document on line stdin:16: function lambda missing 2 arguments (... Would you consider improving that part of this PR?

Companion PR for docs: https://github.com/vmware-tanzu/carvel/pull/553

[pivotaljohn]

Companion PR for docs: https://github.com/vmware-tanzu/carvel/pull/553

Wow! This is wonderful! 🙏🏻

[mamachanko]

@pivotaljohn As per your very reasonable suggestion, the via kwarg now receives both the left and the right node. 🙇🏻‍♂️

[mamachanko]

@pivotaljohn wonderful! 🥹

You closed #718, but is it possible you meant to close #738 instead?

[pivotaljohn]

Oh wow... I think it was this comment that triggered the workflow: https://github.com/vmware-tanzu/carvel-ytt/issues/738#issuecomment-1239662734

I'll be choosing my words more wisely, going forward.