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 (** Tree hash of the commit. *)
82
83 val commit_parents : commit -> hash list
84 (** Parent commit hashes. *)
85
86 val commit_author : commit -> string
87 (** Author name. *)
88
89 val commit_committer : commit -> string
90 (** Committer name. *)
91
92 val commit_message : commit -> string
93 (** Commit message. *)
94
95 val commit_timestamp : commit -> int64
96 (** Commit timestamp. *)
97
98 val commit_of_bytes : string -> (commit, [> `Msg of string ]) result
99 (** Parse a commit from bytes. *)
100
101 val commit_to_bytes : commit -> string
102 (** Serialize a commit to bytes. *)
103
104 val commit_hash : commit -> hash
105 (** Compute the hash of a commit. *)
106end
107
108(** {1 Hash-Specific Signatures} *)
109
110module type SHA1 = S with type hash = Hash.sha1
111(** Tree format using SHA-1 (Git compatible). *)
112
113module type SHA256 = S with type hash = Hash.sha256
114(** Tree format using SHA-256 (ATProto compatible). *)
115
116(** {1 Built-in Formats} *)
117
118module Git : SHA1
119(** Git tree object format. Bidirectional compatibility with Git. *)
120
121module Mst : SHA256
122(** ATProto Merkle Search Tree format. *)