yaml merge Set Options

1. Introduction
2. Accept Only Unique Values
3. Block RHS Values
4. Accept Only RHS Values
5. Configuration File Options
   1. Configuration File Section: defaults
   2. Configuration File Section: rules

This document is part of the body of knowledge about yaml-merge, one of the reference command-line tools provided by the YAML Path project.

Introduction

The yaml-merge command-line tool enables users to control how it merges unordered Sets. By default, only the unique values from both LHS and RHS Sets at the same path within their respective documents are merged together. The available Set merge options include:

1. unique (the default) ignores RHS Set values which already exist within the LHS Set, appending the rest.
2. left causes RHS Sets to be ignored when a Set already exists at the same path within the LHS document. RHS Sets are retained only where there is no LHS Set at the same path.
3. right causes LHS Sets to be entirely replaced by the RHS Set when a Set exists at the same path within both documents. LHS Sets are retained only where there is no RHS Set at the same path.

Each of these options will be explored in the following sections. All sections will use these two documents for their discussions:

File: LHS.yaml

---
strings:
  ? one
  ? two
integers:
  ? 1
  ? 2
lhs_exclusive:
  ? true

File: RHS.yaml

---
strings:
  ? two
  ? three
integers:
  ? 2
  ? 3
rhs_exclusive:
  ? true

Accept Only Unique Values

This is the default merge mode for Sets. When you need to merge only Set values which do not already exist within the LHS Sets, use --sets=unique or -E unique. Merging the example documents with this option yields:

---
strings:
  ? one
  ? two
  ? three
integers:
  ? 1
  ? 2
  ? 3
lhs_exclusive:
  ? true
rhs_exclusive:
  ? true

Notice that all duplicate Set values from the RHS document were discarded during the merge.

Block RHS Values

Should you need to retain only LHS values, blocking all RHS values from Sets at the same path within the YAML documents, use --sets=left or -E left. Doing so produces this result from the example documents:

---
strings:
  ? one
  ? two
integers:
  ? 1
  ? 2
lhs_exclusive:
  ? true
rhs_exclusive:
  ? true

Notice that only the rhs_exclusive Set in RHS.yaml was retained from the RHS document.

Accept Only RHS Values

Should you need to completely overwrite preexisting Set values in the LHS document, retaining only LHS Sets with no Sets in the RHS document at the same paths, use --sets=right or -E right. Doing so produces this result from the example documents:

---
strings:
  ? two
  ? three
integers:
  ? 2
  ? 3
lhs_exclusive:
  ? true
rhs_exclusive:
  ? true

Notice that the only Set from LHS.yaml to survive the merge was that in lhs_exclusive.

Configuration File Options

The yaml-merge tool can read per YAML Path merging options from an INI-Style configuration file via its --config (-c) argument. Whereas the --sets (-E) argument supplies an overarching mode for merging Sets, using a configuration file permits far more precise control whenever you need a different mode for specific parts of the merge documents.

Configuration File Section: defaults

The [defaults] section permits a key named, sets, which behaves identically to the --sets (-E) command-line argument to the yaml-merge tool. The [defaults]sets setting is overridden by the same-named command-line argument, when supplied. In practice, this file may look like:

File merge-options.ini

[defaults]
sets = unique

Note the spaces around the = sign are optional but only an = sign may be used to separate each key from its value.

Configuration File Section: rules

The [rules] section takes any YAML Paths as keys and any of the Set merge modes that are available to the --sets (-E) command-line argument. This enables extremely fine precision for applying the available modes.

Using the same two documents as all prior examples, adding a configuration file with these contents:

[rules]
/strings = left
/integers = right

... would produce this merged document:

---
strings:
  ? one
  ? two
integers:
  ? 2
  ? 3
lhs_exclusive:
  ? true
rhs_exclusive:
  ? true

Notice the following:

1. The Set at /strings retained only values from LHS.yaml due to the INI-defined rule which applied to it: left.
2. The Set at /integers was wholly overwritten by the values from RHS.yaml due to the INI-defined rule which applied to it: right.