git.iko.soy/patch
on v0.0.3.1 help sign in
patch/README.md
50 lines 2.3 kB history raw
1## Patch
3Infrastructure for writing patches which act on other types.
5A `Patch` type represents a kind of change made to a datastructure.
7```haskell
8class Patch p where
9 type PatchTarget p :: *
10 -- | Apply the patch p a to the value a. If no change is needed, return
11 -- 'Nothing'.
12 apply :: p -> PatchTarget p -> Maybe (PatchTarget p)
13```
15### Patching Maps
16For example, `Data.Patch.Map` defines the `PatchMap` type which can be used to patch `Map`s. A `PatchMap` represents updates to a `Map` that can insert, remove, or replace items in the `Map`. In this example, the `Map` is the `PatchTarget` and the `PatchMap` is the `Patch`. Keep in mind that there are many other possible `Patch`es that can be applied to a `Map` (i.e., `Map` can be the `PatchTarget` for many different `Patch` instances).
18`PatchMap` is defined as:
20```haskell
21newtype PatchMap k v = PatchMap { unPatchMap :: Map k (Maybe v) }
22```
24The `Maybe` around the value is used to represent insertion/updates or deletion of the element at a given key.
26Its `Patch` instance begins with:
28```haskell
29instance Ord k => Patch (PatchMap k v) where
30 type PatchTarget (PatchMap k v) = Map k v
31 ...
32```
34When a `PatchMap` is applied to its `PatchTarget`, the following changes can occur:
36- If the key is present in the `Patch` and the `PatchTarget`...
38 - And the `Patch` value at that key is `Nothing`: delete that key from the `PatchTarget`.
40 - And the `Patch` value at that key is `Just x`: update the value at that key in the `PatchTarget` to `x`.
42- If the key is present in the `Patch` and not present in the `PatchTarget`...
44 - And the `Patch` value at that key is `Nothing`: do nothing because we're trying to delete a key that doesn't exist in the target in the first place.
46 - And the `Patch` value at that key is `Just x`: insert the key and the value `x` into the `PatchTarget`
48- If the key is *not* present in the `Patch` but present in the `PatchTarget`: do nothing.
50There are, of course, more complicated ways of patching maps involving, for example, moving values from one key to another. You can find the code for that in `Data.Patch.PatchMapWithMove`. Note that the `PatchTarget` type associated with the `PatchMapWithMove` patch instance is still `Map k v`!