(* Copyright (c) 2013-2017 Thomas Gazagnaire <thomas@gazagnaire.org>
   Copyright (c) 2017-2024 Romain Calascibetta <romain.calascibetta@gmail.com>
   Copyright (c) 2024-2026 Thomas Gazagnaire <thomas@gazagnaire.org>

   Permission to use, copy, modify, and distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
   copyright notice and this permission notice appear in all copies.

   THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
   ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
   WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
   OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. *)

(** Git tree objects (directory listings). *)

type perm = [ `Normal | `Everybody | `Exec | `Link | `Dir | `Commit ]
(** File permissions in a tree entry. *)

val perm_to_string : perm -> string
(** Convert permission to git octal format. *)

val perm_of_string : string -> (perm, [ `Msg of string ]) result
(** Parse permission from git octal format. *)

val perm_of_string_exn : string -> perm
(** [perm_of_string_exn s] is like {!perm_of_string} but raises on error. *)

type entry = { perm : perm; name : string; hash : Hash.t }
(** A tree entry: permission, name, and hash of the object. *)

val entry : perm:perm -> name:string -> Hash.t -> entry
(** Create a tree entry.
    @raise Invalid_argument if name contains null byte. *)

val pp_entry : entry Fmt.t
(** Pretty-print a tree entry. *)

type t
(** The type of trees. *)

val empty : t
(** The empty tree. *)

val is_empty : t -> bool
(** Test if a tree is empty. *)

val v : entry list -> t
(** Create a tree from a list of entries (sorted automatically). *)

val add : entry -> t -> t
(** Add an entry to a tree. *)

val remove : name:string -> t -> t
(** Remove an entry by name. *)

val find : name:string -> t -> entry option
(** Find an entry by name. *)

val to_list : t -> entry list
(** Get the list of entries. *)

val of_list : entry list -> t
(** Create a tree from a list of entries. *)

val hashes : t -> Hash.t list
(** Get all hashes in the tree. *)

val iter : (entry -> unit) -> t -> unit
(** Iterate over entries. *)

val pp : t Fmt.t
(** Pretty-print a tree. *)

val equal : t -> t -> bool
(** Equality on trees. *)

val compare : t -> t -> int
(** Total ordering on trees. *)

val hash : t -> int
(** Hash function for use with Hashtbl. *)

val to_string : t -> string
(** Encode to git binary format. *)

val of_string : string -> (t, [ `Msg of string ]) result
(** Parse from git binary format. *)

val of_string_exn : string -> t
(** [of_string_exn s] is like {!of_string} but raises on error. *)

val of_reader : Bytesrw.Bytes.Reader.t -> (t, [ `Msg of string ]) result
(** Parse a tree directly from a {!Bytesrw.Bytes.Reader.t} without materialising
    the full object into a string. The reader must be positioned at the start of
    the tree body (after the loose-object header, if any). *)

val digest : t -> Hash.t
(** Compute the git hash of a tree. *)

module Set : Set.S with type elt = t
module Map : Map.S with type key = t