vblt.org
forked from
gazagnaire.org/irmin
Persistent store with Git semantics: lazy reads, delayed writes, content-addressing
1(** Tree format abstraction - the ONE functor in Irmin.
2
3 This module type defines how tree nodes are encoded and decoded. Different
4 formats (Git trees, ATProto MST) implement this interface. This is the only
5 functor-based abstraction point in the library. *)
6
7(** {1 Module Type} *)
8
9module type S = sig
10 (** The tree format signature. *)
11
12 type node
13 (** The internal node representation. *)
14
15 type hash
16 (** The hash type used by this format. *)
17
18 val hash_node : node -> hash
19 (** [hash_node n] computes the hash of [n]. *)
20
21 val hash_contents : string -> hash
22 (** [hash_contents data] computes the hash of content [data]. *)
23
24 val node_of_bytes : string -> (node, [> `Msg of string ]) result
25 (** [node_of_bytes data] deserializes a node from bytes. *)
26
27 val bytes_of_node : node -> string
28 (** [bytes_of_node n] serializes a node to bytes. *)
29
30 val empty_node : node
31 (** The empty node with no entries. *)
32
33 val find : node -> string -> [ `Node of hash | `Contents of hash ] option
34 (** [find node name] looks up an entry by name. *)
35
36 val add : node -> string -> [ `Node of hash | `Contents of hash ] -> node
37 (** [add node name entry] adds or replaces an entry. *)
38
39 val remove : node -> string -> node
40 (** [remove node name] removes an entry. *)
41
42 val list : node -> (string * [ `Node of hash | `Contents of hash ]) list
43 (** [list node] returns all entries sorted by name. *)
44
45 val is_empty : node -> bool
46 (** [is_empty node] returns true if the node has no entries. *)
47
48 (** {2 Hash Operations} *)
49
50 val hash_to_bytes : hash -> string
51 (** [hash_to_bytes h] returns the raw bytes of [h]. *)
52
53 val hash_to_hex : hash -> string
54 (** [hash_to_hex h] returns the hexadecimal representation of [h]. *)
55
56 val hash_of_hex : string -> (hash, [> `Msg of string ]) result
57 (** [hash_of_hex s] parses a hexadecimal hash string. *)
58
59 val hash_equal : hash -> hash -> bool
60 (** [hash_equal h1 h2] tests hash equality. *)
61
62 val hash_compare : hash -> hash -> int
63 (** [hash_compare h1 h2] compares hashes. *)
64
65 (** {2 Commit Operations} *)
66
67 type commit
68 (** The commit representation. *)
69
70 val commit_make :
71 tree:hash ->
72 parents:hash list ->
73 author:string ->
74 committer:string ->
75 message:string ->
76 timestamp:int64 ->
77 commit
78 (** Create a commit. *)
79
80 val commit_tree : commit -> hash
81 val commit_parents : commit -> hash list
82 val commit_author : commit -> string
83 val commit_committer : commit -> string
84 val commit_message : commit -> string
85 val commit_timestamp : commit -> int64
86
87 val commit_of_bytes : string -> (commit, [> `Msg of string ]) result
88 (** Parse a commit from bytes. *)
89
90 val commit_to_bytes : commit -> string
91 (** Serialize a commit to bytes. *)
92
93 val commit_hash : commit -> hash
94 (** Compute the hash of a commit. *)
95end
96
97(** {1 Hash-Specific Signatures} *)
98
99module type SHA1 = S with type hash = Hash.sha1
100(** Tree format using SHA-1 (Git compatible). *)
101
102module type SHA256 = S with type hash = Hash.sha256
103(** Tree format using SHA-256 (ATProto compatible). *)
104
105(** {1 Built-in Formats} *)
106
107module Git : SHA1
108(** Git tree object format. Bidirectional compatibility with Git. *)
109
110module Mst : SHA256
111(** ATProto Merkle Search Tree format. *)