How to combine the branches generated when several foci are eligible for modification in the same skeleton. See modifyTweak.

The set of parameters piloting the modification tweak

A standard ModifyTweakParams without the index filtering

A standard ModifyTweakParams without any index filtering or type changing inner optic

A standard ModifyTweakParams without any index filtering or type changing inner optic, modifying all foci in the same transaction.

A standard ModifyTweakParams without any index filtering or type changing inner optic, branching on each focus.

A standard ModifyTweakParams without any index filtering or type changing inner optic, branching on each subset of foci.

When constructing a tweak from an optic and a modification of foci, there are in principle two options for optics with many foci: (a) apply the modification to all foci and return one modified transaction (b) generate a number of transactions that contain different combinations of modified and un-modified foci.

This function is the most general building block for both strategies: its first argument selects, per transaction, which foci are modified together, so it can realise strategy (a), strategy (b), or anything in between. The overMods... helpers defined below specialise it to common cases. The meaning of each argument and of the return value is documented on the parameters themselves below.

Shared setup for the examples

Assume the optic has three foci, which we denote by a, b, c :: x, with indices 1, 2, 3 :: Integer respectively.

Example 1: modify every focus in a single transaction

Choosing (: []) for the [is] -> [[is]] argument yields the single grouping [[1, 2, 3]], so all foci are modified together. Assuming the modification does not itself branch (changes returns exactly one result per focus), this produces exactly one modified transaction, in which a, b, and c are all modified. This is the grouping used by the OneBranchForAllFoci Branching of modifyTweak.

Example 2: one modification per transaction

Now additionally assume that changes, of type is -> x -> Sem effs (x, l), branches into 2, 3, and 5 results on a, b, and c respectively; call those a1, a2 and b1, b2, b3 and c1, c2, c3, c4, c5. Choosing map (: []) for the [is] -> [[is]] argument tries every modification on a separate transaction, since

map (: []) [1, 2, 3] = [[1], [2], [3]]  .

Thus there will be 2 + 3 + 5 = 10 modified transactions: for each element of

[a1, a2, b1, b2, b3, c1, c2, c3, c4, c5]

you get one modified transaction that includes that value in place of the original focus. This is the grouping used by the OneBranchPerFoci Branching of modifyTweak.

Example 3: all combinations of modifications

In the same setting, if you want to combine all possible modifications of one focus with all possible modifications of the other foci, choose tail . subsequences for the [is] -> [[is]] argument. This is the grouping used by the OneBranchPerSubset Branching of modifyTweak. We have

tail (subsequences [1, 2, 3])
  == [ [1], [2], [3],
       [1, 2], [1, 3], [2, 3],
       [1, 2, 3]
     ]

This corresponds to the following 71 modified transactions, represented by the list of modified foci they contain:

[ -- one modified focus (the 10 cases from Example 2)
  [a1],
  [a2],
  ...
  [c4],
  [c5],

  -- two modifications of different foci (2*3 + 2*5 + 3*5 = 31 cases)
  [a1, b1],
  [a1, b2],
  ...
  [b3, c4],
  [b3, c5],

  -- three modified foci, one from each focus (2*3*5 = 30 cases)
  [a1, b1, c1],
  [a1, b1, c2],
  ...
  [a1, b3, c4],
  [a1, b3, c5]
]

So you see that tweaks constructed like this can branch quite wildly. Use with caution!

Note that if changes branches to no result for a targeted focus (one whose index occurs in a grouping), that entire grouping branch is dropped, since there is no possible value to put in place of that focus.

The most convenient and expressive way to build a focusing-and-modifying Tweak. It targets foci in a TxSkel through two optics and applies a (possibly type-changing, possibly failing) modification to them, branching over the eligible foci according to the requested Branching strategy.

Why two optics?

The underlying engine (modifyTweak) can only apply type-preserving modifications: each modified focus is written back into the TxSkel in place, so the skeleton's overall shape is fixed and the outer optic must be an Optic' ... TxSkel a. That optic can therefore only decide where in the skeleton to act; it cannot express a change of type.

The modification we actually want to perform is finer-grained and type-changing: within each selected element a, an inner part of type b is replaced by a value of type c. This type change cannot ride on the outer, type-preserving optic, which is exactly why a second optic is needed. opticIn localises and carries the type change inside each selected element, and traverseOf folds it back into a type-preserving operation a -> f a, so that the outer traversal stays type-preserving while the inner focus still changes from b to c.

The second optic serves a second purpose: being an AffineTraversal (zero or one focus), it doubles as an extra selection layer. We guard on matching, so an element is only eligible when its inner focus actually exists there. Together with the failure allowed by f in change and the index predicate select, this gives several independent layers of selection: outer optic, inner-optic existence, modification success, and index.

A modification that can fail is sometimes best expressed by explicitly stating which property the foci should satisfy to be eligible for a modification that cannot fail. selectP provides a prism to make such a selection. The intended use case is overTweak (optic % selectP prop) mod where optic gives the candidate foci, prop is the predicate to be satisfied by the foci, and mod is the modification to be applied to the selected foci.

Note that selectP is not a lawful prism: its build side is id, so reviewing a value that does not satisfy prop breaks the preview o (review o b) ≡ Just b law. We nevertheless keep it as a Prism' (rather than the lawful but read-only filtered, which is an AffineFold) because we need the write capability: composing a traversal with a prism stays a traversal, whereas composing it with an AffineFold collapses to a read-only fold. This is safe in the intended overTweak (optic % selectP prop) mod pattern, where the unlawful build side is never exercised: we only ever reach foci that already satisfy prop.