From d24ba4cf2fd02dbdde7c953f5975bcce01005581 Mon Sep 17 00:00:00 2001
From: Hannes Mehnert <hannes@mehnert.org>
Date: Sat, 3 Feb 2024 16:52:42 +0100
Subject: [PATCH] proposed API

---
 unix/tar_unix.mli | 48 ++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 37 insertions(+), 11 deletions(-)

diff --git a/unix/tar_unix.mli b/unix/tar_unix.mli
index 086dd24..a6f61b5 100644
--- a/unix/tar_unix.mli
+++ b/unix/tar_unix.mli
@@ -16,18 +16,44 @@
 
 (** Unix I/O for tar-formatted data. *)
 
-(** Return the header needed for a particular file on disk. *)
-val header_of_file : ?level:Tar.Header.compatibility -> string -> Tar.Header.t
-
-(** Fold over a tar archive. *)
-val fold_tar :
-  ((Tar.Header.t * Tar.Header.Extended.t option,
+(** [fold f filename acc] folds over the tar archive. The function [f] is called
+    for each [hdr : Tar.Header.t]. It should forward the position in the file
+    descriptor by [hdr.Tar.Header.file_size]. *)
+val fold :
+  ((Unix.file_descr * Tar.Header.t * Tar.Header.Extended.t option,
     [
-      | `Eof
       | `Fatal of [ `Checksum_mismatch | `Corrupt_pax_header | `Unmarshal of string ]
-      | `Unix of Unix.error
+      | `Unix of Unix.error * string * string
+      | `End_of_file
     ]) result -> 'a -> 'a) ->
-  Unix.file_descr ->
-  'a -> 'a
+  string -> 'a -> 'a
+
+(** [extract ~src ~dst] extracts the tar archive [src] into the directory [dst].
+    If [dst] does not exist, it is created. *)
+val extract : src:string -> dst:string ->
+  (unit, [ `Fatal of [ `Checksum_mismatch | `Corrupt_pax_header | `Unmarshal of string ]
+         | `Unix of Unix.error ]) result
+
+(** [create ~level ~src ~dst] creates a tar archive at [dst]. It uses [src], a
+    filename or directory name, as input. *)
+val create : ?level:Tar.Header.compatibility -> src:string -> dst:string ->
+  (unit, [ `Msg of string | `Unix of Unix.error ]) result
+
+(** [header_of_file ~level filename] returns the tar header of [filename]. *)
+val header_of_file : ?level:Tar.Header.compatibility -> string -> Tar.Header.t
+
+(** [append_file ~level ~header filename fd] appends the contents of [filename]
+    to the tar archive [fd]. If [header] is not provided, {header_of_file} is
+    used for constructing a header. *)
+val append_file : ?level:Tar.Header.compatibility -> ?header:Tar.Header.t ->
+  string -> Unix.file_descr ->
+  (unit, [ `Msg of string | `Unix of Unix.error ]) result
+
+(** [write_extended_header ~level hdr fd] writes the extended header [hdr] to
+    [fd]. *)
+val write_extended_header : ?level:Tar.Header.compatibility ->
+  Tar.Header.Extended.t -> Unix.file_descr ->
+  (unit, [ `Msg of string | `Unix of Unix.error ]) result
 
-val append_file : ?header:Tar.Header.t -> string ->
+(** [write_end fd] writes the tar end marker to [fd]. *)
+val write_end : Unix.file_descr -> (unit, Unix.error) result