(* Copyright (c) 2015 Daniel C. Bünzli
   Copyright (c) 2020-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 references (branches, tags, HEAD). *)

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

val head : t
(** The HEAD reference. *)

val master : t
(** The refs/heads/master reference. *)

val main : t
(** The refs/heads/main reference. *)

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

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

val v : string -> t
(** [v s] is an alias for {!of_string_exn}. *)

val to_string : t -> string
(** Convert a reference to a string. *)

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

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

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

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

val segs : t -> string list
(** Split a reference into path segments. *)

val ( / ) : t -> string -> t
(** [t / seg] appends a segment to a reference.
    @raise Invalid_argument if segment contains null or slash. *)

val ( // ) : t -> t -> t
(** [t1 // t2] appends two references. *)

(** {1 Reference contents} *)

type contents =
  | Hash of Hash.t
  | Ref of t
      (** Reference contents: either a direct hash or a symbolic reference. *)

val contents_equal : contents -> contents -> bool
(** Equality on reference contents. *)

val contents_compare : contents -> contents -> int
(** Total ordering on reference contents. *)

val pp_contents : contents Fmt.t
(** Pretty-print reference contents. *)

val contents_of_string : string -> (contents, [ `Msg of string ]) result
(** Parse reference file contents. *)

val contents_of_string_exn : string -> contents
(** [contents_of_string_exn s] is like {!contents_of_string} but raises on
    error. *)

val contents_to_string : contents -> string
(** Encode reference contents for writing to file. *)

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