package irmin

  1. Overview
  2. Docs
package irmin
Legend:
Library
Module
Module type
Parameter
Class
Class type

Merge provides functions to build custom 3-way merge operators for various user-defined contents.

Merge operators.

type conflict = [
  1. | `Conflict of string
]

The type for merge errors.

val ok : 'a -> ('a, conflict) result Lwt.t

Return Ok x.

val conflict : ('a, unit, string, ('b, conflict) result Lwt.t) format4 -> 'a

Return Error (Conflict str).

val bind : ('a, 'b) result Lwt.t -> ('a -> ('c, 'b) result Lwt.t) -> ('c, 'b) result Lwt.t

bind r f is the merge result which behaves as of the application of the function f to the return value of r. If r fails, bind r f also fails, with the same conflict.

val map : ('a -> 'c) -> ('a, 'b) result Lwt.t -> ('c, 'b) result Lwt.t

map f m maps the result of a merge. This is the same as bind m (fun x -> ok (f x)).

Merge Combinators

type 'a promise = unit -> ('a option, conflict) result Lwt.t

An 'a promise is a function which, when called, will eventually return a value type of 'a. A promise is an optional, lazy and non-blocking value.

val promise : 'a -> 'a promise

promise a is the promise containing a.

val map_promise : ('a -> 'b) -> 'a promise -> 'b promise

map_promise f a is the promise containing f applied to what is promised by a.

val bind_promise : 'a promise -> ('a -> 'b promise) -> 'b promise

bind_promise a f is the promise returned by f applied to what is promised by a.

type 'a f = old:'a promise -> 'a -> 'a -> ('a, conflict) result Lwt.t

Signature of a merge function. old is the value of the least-common ancestor.

            /----> t1 ----\
    ----> old              |--> result
            \----> t2 ----/
type 'a t

The type for merge combinators.

val v : 'a Type.t -> 'a f -> 'a t

v dt f create a merge combinator.

val f : 'a t -> 'a f

f m is m's merge function.

val seq : 'a t list -> 'a t

Call the merge functions in sequence. Stop as soon as one is not returning a conflict.

val like : 'a Type.t -> 'b t -> ('a -> 'b) -> ('b -> 'a) -> 'a t

Use the merge function defined in another domain. If the converting functions raise any exception the merge is a conflict.

val with_conflict : (string -> string) -> 'a t -> 'a t

with_conflict f m is m with the conflict error message modified by f.

val like_lwt : 'a Type.t -> 'b t -> ('a -> 'b Lwt.t) -> ('b -> 'a Lwt.t) -> 'a t

Same as biject but with blocking domain converting functions.

Basic Merges

val default : 'a Type.t -> 'a t

default t is the default merge function for values of type t. This is a simple merge function which supports changes in one branch at a time:

  • if t1=old then the result of the merge is OK t2;
  • if t2=old then return OK t1;
  • otherwise the result is Conflict.
val idempotent : 'a Type.t -> 'a t

idempotent t is the default merge function for values of type t using idempotent operations. It follows the same rules as the default merge function but also adds:

  • if t1=t2 then the result of the merge is OK t1.
val unit : unit t

unit is the default merge function for unit values.

val bool : bool t

bool is the default merge function for booleans.

val char : char t

char is the default merge function for characters.

val int32 : int32 t

int32 is the default merge function for 32-bits integers.

val int64 : int64 t

int64 the default merge function for 64-bit integers.

val float : float t

float is the default merge function for floating point numbers.

val string : string t

The default string merge function. Do not do anything clever, just compare the strings using the default merge function.

val option : 'a t -> 'a option t

Lift a merge function to optional values of the same type. If all the provided values are inhabited, then call the provided merge function, otherwise use the same behavior as default.

val pair : 'a t -> 'b t -> ('a * 'b) t

Lift merge functions to pairs of elements.

val triple : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t

Lift merge functions to triples of elements.

Counters and Multisets

type counter = int64

The type for counter values. It is expected that the only valid operations on counters are increment and decrement. The following merge functions ensure that the counter semantics are preserved: i.e. it ensures that the number of increments and decrements is preserved.

val counter : counter t

The merge function for mergeable counters.

module MultiSet (K : sig ... end) : sig ... end

Multi-sets.

Maps and Association Lists

We consider the only valid operations for maps and association lists to be:

  • Adding a new bindings to the map.
  • Removing a binding from the map.
  • Replacing an existing binding with a different value.
  • Trying to add an already existing binding is a no-op.

We thus assume that no operation on maps is modifying the key names. So the following merge functions ensures that (i) new bindings are preserved (ii) removed bindings stay removed and (iii) modified bindings are merged using the merge function of values.

Note: We only consider sets of bindings, instead of multisets. Application developers should take care of concurrent addition and removal of similar bindings themselves, by using the appropriate multi-sets.

module Set (E : sig ... end) : sig ... end

Lift merge functions to sets.

val alist : 'a Type.t -> 'b Type.t -> ('a -> 'b option t) -> ('a * 'b) list t

Lift the merge functions to association lists.

Lift the merge functions to maps.

module Map (K : sig ... end) : sig ... end
module Infix : sig ... end

Infix operators for manipulating merge results and promises.

Value Types

val conflict_t : conflict Type.t

conflict_t is the value type for conflict.

val result_t : 'a Type.t -> ('a, conflict) result Type.t

result_t is the value type for merge results.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct