mask(tree, mask)

This returns the tree that results from applying the mask tree to the source tree, preserving only keys that exist in mask and have a truthy value.

See also tree:filter.

Example

Suppose mask.ori contains:

// mask.ori

mask(
  // Source tree
  {
    a: 1
    b: 2
    c: {
      d: 3
      e: 4
    }
  }
  // Mask tree
  {
    a: true
    c: {
      d: true
    }
  }
)

Invoking this returns the masked result:

$ ori mask.ori/
a: 1
c:
  d: 3

If the mask tree does not specify a value for a given key, the result of asking for that value will be undefined, which is a falsy value. This means it is not normally necessary to specify false values in the mask tree.

Above, b and c/e have been masked from the source tree because those do paths do not lead to truthy values in the mask tree.

Default value

You can influence the result of a mask operation by defining a default value for the mask tree using a shorthand function or tree:constant.

// maskDefault.ori
mask(
  {
    a: 1
    b: 2
    c: 3
    d: 4
  }
  {
    ...constant(true) // Default is to let values through the mask
    b: false
  }
)

The above defines a mask where the default value is true, so all keys and values in the source tree will come through the mask unless specifically overridden with a falsy value.

$ ori maskDefault.ori/
a: 1
c: 3
d: 4

This flips the logic of mask: instead of only allowing truthy values in, this mask excludes falsy values.

Mask with globs and regular expressions

You can use mask in conjunction with tree:globKeys and tree:regExpKeys.