Merge remote-tracking branch 'origin/main' into bigarray2

Makefile

@@ -3,5 +3,8 @@ all: build
 build:
 	@dune build
 
+doc:
+	@dune build @doc
+
 clean:
 	@dune clean

README.md

@@ -15,31 +15,23 @@ Basic usage is
 
 ```ocaml
 let () =
-  let filename = "test.mp3" in
-  let metadata = Metadata.parse_file filename in
+  let metadata = Metadata.parse_file "test.mp3" in
   List.iter (fun (k,v) -> Printf.printf "- %s: %s\n" k v) metadata
 ```
 
-In the above example, the function `Metadata.Any.parse_file` takes a file name
-as argument and returns an association list describing its metadata. It consists
-of pairs of strings being the name of the metadata and its value.
+In the above example, the function `Metadata.parse_file` takes a file name as
+argument and returns an association list describing its metadata. It consists of
+pairs of strings being the name of the metadata and its value.
 
 Installing
 ----------
 
 The preferred way is via opam:
 
 ```bash
-opam pin add .
 opam install metadata
 ```
 
-It can also be installed via dune:
-
-```
-dune install
-```
-
 Other libraries
 ---------------
 

examples/basic.ml

@@ -1,6 +1,5 @@
 (** Basic usage of the library. *)
 
 let () =
-  let filename = "test.mp3" in
-  let metadata = Metadata.parse_file filename in
-  List.iter (fun (k,v) -> Printf.printf "- %s: %s\n" k v) metadata
+  let metadata = Metadata.parse_file "test.mp3" in
+  List.iter (fun (k, v) -> Printf.printf "- %s: %s\n" k v) metadata

examples/meta.ml

@@ -49,7 +49,7 @@ let () =
       Printf.printf "\n# Metadata for %s\n\n%!" fname;
       (* Store "APIC" as custom tag. *)
       let apic_tag = ref None in
-      let custom_parser ?read_ba ~read:_ ~length:_ ~label () =
+      let custom_parser { Metadata.read_ba; label; _ } =
         match (label, read_ba) with
           | "APIC", Some r -> apic_tag := Some (r ())
           | _ -> ()

src/metadata.ml

@@ -11,6 +11,7 @@ module Make (E : CharEncoding.T) = struct
   module AVI = MetadataAVI
   module MP4 = MetadataMP4
 
+  (** Charset conversion function. *)
   let recode = E.convert
 
   module ID3 = struct
@@ -65,10 +66,16 @@ module Make (E : CharEncoding.T) = struct
 
   module Any = struct
     let parsers = Audio.parsers @ Image.parsers @ Video.parsers
+
+    (** Genering parsing of metadata. *)
     let parse = first_valid parsers
 
     let parse_file ?custom_parser file =
       Reader.with_file ?custom_parser parse file
+
+    (** Parse the metadatas of a string. *)
+    let parse_string ?custom_parser file =
+      Reader.with_string ?custom_parser parse file
   end
 
   include Any

src/metadata.mli

@@ -18,13 +18,15 @@ module Make : functor (_ : CharEncoding.T) -> sig
 
       Currently only supported for: ID3v2, MP4 and [metadata_block_picture] in
       FLAC metadata. *)
-  type custom_parser =
-    ?read_ba:(unit -> bigarray) ->
-    read:(unit -> string) ->
-    length:int ->
-    label:string ->
-    unit ->
-    unit
+  type parser_handler = MetadataBase.parser_handler = {
+    label : string;
+    length : int;
+    read : unit -> string;
+    read_ba : (unit -> bigarray) option;
+    skip : unit -> unit;
+  }
+
+  type custom_parser = parser_handler -> unit
 
   module Reader : sig
     (** A function to read taking the buffer to fill the offset and the length and
@@ -68,30 +70,30 @@ module Make : functor (_ : CharEncoding.T) -> sig
     val zero : int
     val one : int
     val minus_one : int
-    external neg : int -> int = "%negint"
-    external add : int -> int -> int = "%addint"
-    external sub : int -> int -> int = "%subint"
-    external mul : int -> int -> int = "%mulint"
-    external div : int -> int -> int = "%divint"
-    external rem : int -> int -> int = "%modint"
-    external succ : int -> int = "%succint"
-    external pred : int -> int = "%predint"
+    val neg : int -> int
+    val add : int -> int -> int
+    val sub : int -> int -> int
+    val mul : int -> int -> int
+    val div : int -> int -> int
+    val rem : int -> int -> int
+    val succ : int -> int
+    val pred : int -> int
     val abs : int -> int
     val max_int : int
     val min_int : int
-    external logand : int -> int -> int = "%andint"
-    external logor : int -> int -> int = "%orint"
-    external logxor : int -> int -> int = "%xorint"
+    val logand : int -> int -> int
+    val logor : int -> int -> int
+    val logxor : int -> int -> int
     val lognot : int -> int
-    external shift_left : int -> int -> int = "%lslint"
-    external shift_right : int -> int -> int = "%asrint"
-    external shift_right_logical : int -> int -> int = "%lsrint"
+    val shift_left : int -> int -> int
+    val shift_right : int -> int -> int
+    val shift_right_logical : int -> int -> int
     val equal : int -> int -> bool
     val compare : int -> int -> int
     val min : int -> int -> int
     val max : int -> int -> int
-    external to_float : int -> float = "%floatofint"
-    external of_float : float -> int = "%intoffloat"
+    val to_float : int -> float
+    val of_float : float -> int
     val to_string : int -> string
     val find : (int -> bool) -> int
   end
@@ -151,6 +153,9 @@ module Make : functor (_ : CharEncoding.T) -> sig
 
     val parse_file :
       ?custom_parser:custom_parser -> string -> MetadataBase.metadata
+
+    val parse_string :
+      ?custom_parser:custom_parser -> string -> MetadataBase.metadata
   end
 
   val parsers : (Reader.t -> MetadataBase.metadata) list

src/metadataBase.ml

@@ -7,15 +7,19 @@ type bigarray =
 type metadata = (string * string) list
 type endianness = Big_endian | Little_endian
 
-type custom_parser =
-  ?read_ba:(unit -> bigarray) ->
-  read:(unit -> string) ->
-  length:int ->
-  label:string ->
-  unit ->
-  unit
+type parser_handler = {
+  label : string;
+  length : int;
+  read : unit -> string;
+  read_ba : (unit -> bigarray) option;
+  skip : unit -> unit;
+}
+
+type custom_parser = parser_handler -> unit
 
 module Reader = struct
+  (** A function to read taking the buffer to fill the offset and the length and
+      returning the number of bytes actually read. *)
   type t = {
     read : bytes -> int -> int -> int;
     read_ba : (int -> bigarray) option;
@@ -49,6 +53,10 @@ module Reader = struct
         | None -> false
         | Some custom_parser ->
             let is_custom = ref false in
+            let skip () =
+              is_custom := true;
+              f.seek length
+            in
             let read () =
               is_custom := true;
               read f length
@@ -60,7 +68,7 @@ module Reader = struct
                   read_ba length)
                 f.read_ba
             in
-            custom_parser ?read_ba ~read ~length ~label ();
+            custom_parser { read_ba; read; skip; length; label };
             !is_custom
     in
     if is_custom then None else Some (read f length)

test/test.ml

@@ -64,7 +64,7 @@ let () =
         ]
   in
   let custom_parser_labels = ref [] in
-  let custom_parser ?read_ba:_ ~read ~length ~label () =
+  let custom_parser { Metadata.read; length; label; _ } =
     custom_parser_labels := label :: !custom_parser_labels;
     match label with
       | "TIT2" ->