combine(tree1, tree2, combineFn)

This returns the result of applying the function combineFn to the values in the two map-based trees. This can be used to combine or compare values in the trees.

The function will be called for each pairwise combination of values at a given path in the trees. If one tree has a value for a key but the other does not, the passed value will be undefined. The result of Tree.combine will be the combined results of calling combineFn. If combineFn itself returns undefined, no value will be included in the result.

The Dev.changes command uses this Tree.combine function to compare a new tree with an old one.

Example #

As a demonstration, suppose you want to concatenate the corresponding values in two trees that are both defined in YAML files.

# 1.yaml
a: A
b: B
sub:
  c: C

# 2.yaml
a: a
sub:
  c: c
  d: d
e: e

A sample function takes two values and combines them:

// combine.ori
// Concatenate the two values; use an underscore if a value is missing
(value1, value2) => `${ value1 ?? "_" }${ value2 ?? "_" }`

Call Tree.combine combines the values in the two files:

$ ori Tree.combine 1.yaml, 2.yaml, combine.ori
a: Aa
b: B_
sub:
  c: Cc
  d: _d
e: _e