(**************************************************************************)
(*                                                                        *)
(*    Copyright 2012-2020 OCamlPro                                        *)
(*    Copyright 2012 INRIA                                                *)
(*                                                                        *)
(*  All rights reserved. This file is distributed under the terms of the  *)
(*  GNU Lesser General Public License version 2.1, with the special       *)
(*  exception on linking described in the file LICENSE.                   *)
(*                                                                        *)
(**************************************************************************)

(** Generic stdlib functions (String, List, Option, Sys submodules...) *)

(** {2 Signatures and functors} *)

(** Sets with extended interface and infix operators *)
module type SET = sig

  include Set.S

  val map: (elt -> elt) -> t -> t

  val is_singleton: t -> bool

  (** Returns one element, assuming the set is a singleton. Raises [Not_found]
      on an empty set, [Failure] on a non-singleton. *)
  val choose_one : t -> elt

  val choose_opt: t -> elt option

  val of_list: elt list -> t
  val to_list_map: (elt -> 'b) -> t -> 'b list
  val to_string: t -> string
  val to_json: t OpamJson.encoder
  val of_json: t OpamJson.decoder
  val find: (elt -> bool) -> t -> elt
  val find_opt: (elt -> bool) -> t -> elt option

  (** Raises Failure in case the element is already present *)
  val safe_add: elt -> t -> t

  (** Accumulates the resulting sets of a function of elements until a fixpoint
      is reached *)
  val fixpoint: (elt -> t) -> t -> t

  (** [map_reduce f op t] applies [f] to every element of [t] and combines the
      results using associative operator [op]. Raises [Invalid_argument] on an
      empty set, or returns [default] if it is defined. *)
  val map_reduce: ?default:'a -> (elt -> 'a) -> ('a -> 'a -> 'a) -> t -> 'a

  module Op : sig
    val (++): t -> t -> t (** Infix set union *)

    val (--): t -> t -> t (** Infix set difference *)

    val (%%): t -> t -> t (** Infix set intersection *)
  end

end

(** Maps with extended interface *)
module type MAP = sig

  include Map.S

  val to_string: ('a -> string) -> 'a t  -> string
  val to_json: 'a OpamJson.encoder -> 'a t OpamJson.encoder
  val of_json: 'a OpamJson.decoder -> 'a t OpamJson.decoder
  val keys: 'a t -> key list
  val values: 'a t -> 'a list
  val find_opt: key -> 'a t -> 'a option
  val choose_opt: 'a t -> (key * 'a) option

  (** A key will be in the union of [m1] and [m2] if it is appears
      either [m1] or [m2], with the corresponding value. If a key
      appears in both [m1] and [m2], then the resulting value is built
      using the function given as argument. *)
  val union: ('a -> 'a -> 'a) -> 'a t -> 'a t -> 'a t

  val is_singleton: 'a t -> bool

  val of_list: (key * 'a) list -> 'a t

  (** Raises Failure in case the element is already present *)
  val safe_add: key -> 'a -> 'a t -> 'a t

  (** [update k f zero map] updates the binding of [k] in [map] using function
      [f], applied to the current value bound to [k] or [zero] if none *)
  val update: key -> ('a -> 'a) -> 'a -> 'a t -> 'a t

  (** [map_reduce f op t] applies [f] to every binding of [t] and combines the
      results using associative operator [op]. Raises [Invalid_argument] on an
      empty map, or returns [default] if it is defined. *)
  val map_reduce:
    ?default:'b -> (key -> 'a -> 'b) -> ('b -> 'b -> 'b) -> 'a t -> 'b

  val filter_map: (key -> 'a -> 'b option) -> 'a t -> 'b t
end

(** A signature for handling abstract keys and collections thereof *)
module type ABSTRACT = sig

  type t

  val compare: t -> t -> int
  val equal: t -> t -> bool
  val of_string: string -> t
  val to_string: t -> string
  val to_json: t OpamJson.encoder
  val of_json: t OpamJson.decoder

  module Set: SET with type elt = t
  module Map: MAP with type key = t
end

(** A basic implementation of ABSTRACT using strings *)
module AbstractString : ABSTRACT with type t = string

(** {3 Generators for set and map modules with printers} *)

module type OrderedType = sig
  include Set.OrderedType
  val to_string: t -> string
  val to_json: t OpamJson.encoder
  val of_json: t OpamJson.decoder
end

module Set: sig
  module Make (S: OrderedType): SET with type elt = S.t
end

module Map: sig
  module Make (S: OrderedType): MAP with type key = S.t
end


(** {2 Integer collections} *)

(** Map of ints *)
module IntMap: MAP with type key = int

(** Set of ints *)
module IntSet: SET with type elt = int


(** {2 Utility modules extending the standard library on base types} *)

module Option: sig
  val map: ('a -> 'b) -> 'a option -> 'b option

  val iter: ('a -> unit) -> 'a option -> unit

  val default: 'a -> 'a option -> 'a

  val default_map: 'a option -> 'a option -> 'a option

  val replace : ('a -> 'b option) -> 'a option -> 'b option

  val map_default: ('a -> 'b) -> 'b -> 'a option -> 'b

  val compare: ('a -> 'a -> int) -> 'a option -> 'a option -> int

  val equal: ('a -> 'a -> bool) -> 'a option -> 'a option -> bool

  val to_string: ?none:string -> ('a -> string) -> 'a option -> string

  val to_list: 'a option -> 'a list

  val some: 'a -> 'a option

  val none: 'a -> 'b option

  (** [of_Not_found f x] calls [f x], catches [Not_found] and returns [None] *)
  val of_Not_found: ('a -> 'b) -> 'a -> 'b option

  module Op: sig
    val (>>=): 'a option -> ('a -> 'b option) -> 'b option
    val (>>|): 'a option -> ('a -> 'b) -> 'b option
    val (>>+): 'a option -> (unit -> 'a option) -> 'a option
    val (+!): 'a option -> 'a -> 'a
    val (++): 'a option -> 'a option -> 'a option
  end
end

module List : sig

  val cons: 'a -> 'a list -> 'a list

  (** Convert list items to string and concat. [sconcat_map sep f x] is equivalent
      to String.concat sep (List.map f x) but tail-rec. *)
  val concat_map:
    ?left:string -> ?right:string -> ?nil:string -> ?last_sep:string ->
    string -> ('a -> string) -> 'a list -> string

  (** Like [List.find], but returning option instead of raising *)
  val find_opt: ('a -> bool) -> 'a list -> 'a option

  val to_string: ('a -> string) -> 'a list -> string

  (** Removes consecutive duplicates in a list *)
  val remove_duplicates: ('a -> 'a -> bool) -> 'a list -> 'a list

  (** Sorts the list, removing duplicates *)
  val sort_nodup: ('a -> 'a -> int) -> 'a list -> 'a list

  (** Filter and map *)
  val filter_map: ('a -> 'b option) -> 'a list -> 'b list

  (** Retrieves [Some] values from a list *)
  val filter_some: 'a option list -> 'a list

  (** Returns the first non-[None] value returned by the passed function on the
      elements of the passed list.
      @raise Not_found if all of them yield [None] *)
  val find_map: ('a -> 'b option) -> 'a list -> 'b

  (** Like [find_map], but returns [Some _] if succeeded and [None] if failed. *)
  val find_map_opt: ('a -> 'b option) -> 'a list -> 'b option

  (** Insert a value in an ordered list *)
  val insert: ('a -> 'a -> int) -> 'a -> 'a list -> 'a list

  (** Inserts a value at the given index (starting from 0) in the list (start or
      end if index < 0 or > length respectively). Not tail-recursive *)
  val insert_at: int -> 'a -> 'a list -> 'a list

  (** Like [List.assoc] with an equality function. *)
  val assoc: ('a -> 'a -> bool) -> 'a -> ('a * 'b) list -> 'b

  (** Like [assoc], but returning option instead of raising [Not_found] *)
  val assoc_opt: ('a -> 'a -> bool) -> 'a -> ('a * 'b) list -> 'b option

  (** Like [assoc], but as an option, and also returns the list with the
      binding removed, e.g. equivalent to [(assoc_opt x l, remove_assoc x l)]
      (but tail-recursive and more efficient) *)
  val pick_assoc:
    ('a -> 'a -> bool) -> 'a -> ('a * 'b) list -> 'b option * ('a * 'b) list

  (** Like [assoc], but returns a boolean instead of associated value *)
  val mem_assoc: ('a -> 'a -> bool) -> 'a -> ('a * 'b) list -> bool

  (** [remove_assoc eq k l] removes first association of [k] from list [l]
      (tail-recursive). *)
  val remove_assoc:
    ('a -> 'a -> bool) -> 'a -> ('a * 'b) list -> ('a * 'b) list

  (** [update_assoc key value list] updates the first value bound to [key] in
      the associative list [list], or appends [(key, value)] if the key is not
      bound. *)
  val update_assoc:
    ('a -> 'a -> bool) -> 'a -> 'b -> ('a * 'b) list -> ('a * 'b) list

  (** Like [pick_assoc], but with a test function that takes a list element *)
  val pick: ('a -> bool) -> 'a list -> 'a option * 'a list

  (** Like [List.fold_left], but also performs [List.map] at the same time *)
  val fold_left_map: ('s -> 'a -> ('s * 'b)) -> 's -> 'a list -> 's * 'b list
end

module String : sig

  (** {3 Collections} *)

  module Map: MAP with type key = string

  module Set: SET with type elt = string

  (** Set of string sets *)
  module SetSet: SET with type elt = Set.t

  (** Map of string sets *)
  module SetMap: MAP with type key = Set.t

  (** {3 Checks} *)

  val starts_with: prefix:string -> string -> bool
  val ends_with: suffix:string -> string -> bool
  val for_all: (char -> bool) -> string -> bool
  val contains_char: string -> char -> bool
  val contains: sub:string -> string -> bool
  val exact_match: Re.re -> string -> bool
  val find_from: (char -> bool) -> string -> int -> int

  (** Like [String.compare], but with lowercase/uppercase variants ordered next
      to each other (still considered not equal though) *)
  val compare_case: string -> string -> int

  (** {3 Manipulation} *)

  val map: (char -> char) -> string -> string
  val strip: string -> string
  val strip_right: string -> string
  val sub_at: int -> string -> string
  val remove_prefix: prefix:string -> string -> string
  val remove_suffix: suffix:string -> string -> string

  (** [is_prefix_of from full str] returns true if [str] if a prefix of [full],
      with at least [from] first characters *)
  val is_prefix_of: from:int -> full:string -> string -> bool

  (** {4 Transformations} *)

  (** Cut a string at the first occurrence of the given char *)
  val cut_at: string -> char -> (string * string) option

  (** Same as [cut_at], but starts from the right *)
  val rcut_at: string -> char -> (string * string) option

  (** Split a string at occurrences of a given characters. Empty strings are
      skipped. *)
  val split: string -> char -> string list

  (** The same as [split], but keep empty strings (leading, trailing or between
      contiguous delimiters) *)
  val split_delim: string -> char -> string list

  (** Splits a variable at the given character, but allowing double-quote
      characters to protect the delimiter.

      [split_quoted "foo\";\"bar;baz" ';' = ["foo;bar"; "baz"]] *)
  val split_quoted: string -> char -> string list

  val fold_left: ('a -> char -> 'a) -> 'a -> string -> 'a

  val is_hex: string -> bool

end

module Format : sig

  (** {4 Querying information} *)

  (** Returns the length of the string in terminal chars, ignoring ANSI color
      sequences from OpamConsole.colorise *)
  val visual_length: string -> int

  (** {4 Text formatting functions} *)

  (** Truncates the string to not visually get over [width] columns *)
  val cut_at_visual: string -> int -> string

  (** left indenting. [~visual] can be used to indent eg. ANSI colored
      strings and should correspond to the visible characters of s *)
  val indent_left: string -> ?visual:string -> int -> string

  val indent_right: string -> ?visual:string -> int -> string

  (** Pads fields in a table with spaces for alignment. *)
  val align_table: string list list -> string list list

  (** Cut long lines in string according to the terminal width *)
  val reformat:
    ?start_column:int -> ?indent:int -> ?width:int -> string -> string

  (** Convert a list of items to string as a dashed list (already reformats
      supposes no additional left margin: don't use within OpamConsole.error or
      similar) *)
  val itemize: ?bullet:string -> ('a -> string) -> 'a list -> string

  (** Display a pretty list: ["x";"y";"z"] -> "x, y and z".
      "and" can be changed by specifying [last] *)
  val pretty_list: ?last:string -> string list -> string

  (** Splits a list of strings so that it can be printed as a table that should
      fit on screen *)
  val as_aligned_table: ?width:int -> string list -> string list list
end

module Exn : sig

  (** To use when catching default exceptions: ensures we don't catch fatal errors
      like C-c. try-with should _always_ (by decreasing order of preference):
      - either catch specific exceptions
      - or re-raise the same exception (preferably with [Exn.finalise])
      - or call this function on the caught exception *)
  val fatal: exn -> unit

  (** Register a backtrace for when you need to process a finalizer (that
      internally uses exceptions) and then re-raise the same exception.
      To be printed by pretty_backtrace. *)
  val register_backtrace: exn -> unit

  (** Return a pretty-printed backtrace *)
  val pretty_backtrace: exn -> string

  (** Runs the given finaliser, then reraises the given exception, while
      preserving backtraces (when the OCaml version permits, e.g. >= 4.05.0) *)
  val finalise: exn -> (unit -> unit) -> 'a

  (** Execute the given continuation, then run the finaliser before returning
      the result. If an exception is raised, call [finalise] with the given
      finaliser. *)
  val finally: (unit -> unit) -> (unit -> 'a) -> 'a

end

(** {2 Manipulation and query of environment variables} *)

module Env : sig

  (** {3 Generic functions} *)

  (** Remove from a c-separated list of string the ones with the given prefix *)
  val reset_value: prefix:string -> char -> string -> string list

  (** split a c-separated list of string in two according to the first
      occurrences of the string with the given [prefix]. The list of
      elements occurring before is returned in reverse order. If there are
      other elements with the same [prefix] they are kept in the second list.
  *)
  val cut_value: prefix:string -> char -> string -> string list * string list

  (** Utility function for shell single-quoted strings. In most shells,
      backslash escapes are not allowed and a single quote needs to be replaced
      by [quote double-quote quote double-quote quote] (close the single-quoted
      literal, put the single quote in a double-quoted literal, and reopen a
      single-quoted literal). fish is the exception and should set
      [using_backslashes] to escape both quotes and backslashes using
      backslashes *)
  val escape_single_quotes: ?using_backslashes:bool -> string -> string

  (** Utility function for PowerShell strings. *)
  val escape_powershell: string -> string

  (** {3 Environment variable handling} *)

  (** Environment variable names. Windows has complicated semantics for
      environment variables. The retrieval functions are case insensitive, but
      it's "legal" for the environment block to contain entries which differ
      only by case. If environment variables are set entirely using CRT or Win32
      API functions, then there isn't usually a problem, the issue arises when
      creating a program where the environment block is instead passed. In this
      model, it's very easy to end up with two bindings in the same block. When
      dealing with Windows programs, this will mostly be transparent, but it's a
      problem with Cygwin which actively allows "duplicate" entries which differ
      by case only and implements Posix semantics on top of this. The problem is
      constantly with us thanks to the use of PATH on Unix, and Path on Windows!
      opam tries to ensure that environment variables are looked up according to
      the OS semantics (so case insensitively on Windows) and OpamEnv goes to
      some trouble to ensure that updates to environment variables are case
      preserving (i.e. PATH+=foo gets transformed to Path+=foo if Path exists
      in the environment block).

      Key to this is not accidentally treating environment variable names as
      strings, without using the appropriate comparison functions. Name.t
      represents environment variable names as private strings, providing
      comparison operators to handle them, and still allowing the possibility
      to coerce them to strings.
      *)
  module Name : sig
    include ABSTRACT with type t = private string

    val equal_string: t -> string -> bool

  end

  val get: string -> string

  val getopt: string -> string option

  val getopt_full: Name.t -> Name.t * string option

  val list: unit -> (Name.t * string) list
  val raw_env: unit -> string array

  (** [cyg_env ~env ~cygbin ~git_location] returns [env] environment with its
      PATH variable updated with [git_location] and [cygbin] at the beginning,
      ie PATH=<git_location>:<cygbin>:$PATH. Usual `env` argument is
      `OpamStd.Env.raw_env`. *)
  val cyg_env:
    env:string array -> cygbin:string -> git_location:string option
    -> string array
end

(** {2 System query and exit handling} *)

module Sys : sig

  (** {3 Querying} *)

  (** true if stdout is bound to a terminal *)
  val tty_out : bool

  (** true if stdin is bound to a terminal *)
  val tty_in : bool

  (** Queried lazily, but may change on SIGWINCH *)
  val terminal_columns : unit -> int

  (** The user's home directory. Queried lazily *)
  val home: unit -> string

  (** The /etc directory *)
  val etc: unit -> string

  (** The system directory (Windows only) *)
  val system: unit -> string

  type os = Darwin
          | Linux
          | FreeBSD
          | OpenBSD
          | NetBSD
          | DragonFly
          | Cygwin
          | Win32
          | Unix
          | Other of string

  (** Queried lazily *)
  val os: unit -> os

  (** The output of the command "uname", with the given argument. Memoised. *)
  val uname: string -> string option

  (** The output of the command "getconf", with the given argument. Memoised. *)
  val getconf: string -> string option

  (** Append .exe (only if missing) to executable filenames on Windows *)
  val executable_name : string -> string

  (** Remove .exe (if present) from an executable filename on Windows *)
  val chop_exe_suffix : string -> string

  (** The different families of shells we know about *)
  type powershell_host = Powershell_pwsh | Powershell
  type shell = SH_sh | SH_bash | SH_zsh | SH_csh | SH_fish
    | SH_pwsh of powershell_host | SH_cmd

  (** List of all supported shells *)
  val all_shells : shell list

  (** Guess the shell compat-mode *)
  val guess_shell_compat: unit -> shell

  (** Guess the location of .profile. Returns None if the shell doesn't
      support the concept of a .profile file. *)
  val guess_dot_profile: shell -> string option

  (** The separator character used in the PATH variable (varies depending on
      OS) *)
  val path_sep: char

  (** [true] if a character may be used in a filename, depending on the OS.
      For example, on Windows, `:` and `?` can't be in the name. *)
  val is_valid_basename_char: char -> bool

  (** Splits a PATH-like variable separated with [path_sep]. More involved than
      it seems, because there may be quoting on Windows. By default, it returns
      the path cleaned (remove trailing, leading, contiguous delimiters).
      Optional argument [clean] permits to keep those empty strings. *)
  val split_path_variable: ?clean:bool -> string -> string list

  (** Test whether a command exists in the environment, and returns it (resolved
      if found in PATH). [~env] defaults to {!Env.raw_env}. *)
  val resolve_command: ?env:string array -> ?dir:string -> string ->
    [ `Cmd of string | `Denied | `Not_found ]

  (** Search for an arbitrary file in PATH. Unlike {!resolve_command}, no
      transformations take place on the name in Windows (i.e. .exe, etc. is
      never appended) and no executable check takes place. The name passed
      must be a basename (no directory component). *)
  val resolve_in_path: ?env:string array -> string -> string option

  (** For native Windows builds, returns [`Cygwin] if the command is a Cygwin-
      compiled executable, [`Msys2] if the command is a MSYS2-compiled
      executable, and [`Tainted of [ `Msys2 | `Cygwin ]] if the command links
      to a library which is itself Cygwin- or MSYS2-compiled, or [`Native]
      otherwise.

      If supplied, [~search_in_first] specifies a directory which should be
      searched for cygcheck prior to searching the current PATH.

      If the command given is not an absolute path, it too is resolved in the
      current PATH.

      If cygcheck cannot be resolved in PATH, or when running the Cygwin build
      of opam, the function returns `Native. *)
  val get_windows_executable_variant: ?search_in_first:string ->
    string -> [ `Native | `Cygwin | `Tainted of [ `Msys2 | `Cygwin] | `Msys2 ]

  (** Behaviour is largely as {!get_windows_executable_variant} but where MSYS2
      and Cygwin are seen as equivalent.

      For native Windows builds, returns [`Cygwin] if the command is a Cygwin-
      or Msys2- compiled executable, and [`CygLinked] if the command links to a
      library which is itself Cygwin/Msys2-compiled, or [`Native] otherwise. *)
  val get_cygwin_variant:
    ?search_in_first:string -> string -> [ `Native | `Cygwin | `CygLinked ]

  (** Returns true if [get_cygwin_variant] is [`Cygwin] *)
  val is_cygwin_variant: ?search_in_first:string -> string -> bool

  (** {3 Exit handling} *)

  (** Like Stdlib.at_exit but with the possibility to call manually
      (eg. before exec()) *)
  val at_exit: (unit -> unit) -> unit

  (** Calls the functions registered in at_exit. Unneeded if exiting normally *)
  val exec_at_exit: unit -> unit

  (** Indicates intention to exit the program with given exit code *)
  exception Exit of int

  (** Indicates intention to exec() the given command (parameters as per
      [Unix.execvpe]), after proper finalisations. It's the responsibility of
      the main function to catch this, call [exec_at_exit], and
      [Unix.execvpe]. *)
  exception Exec of string * string array * string array

  (** Raises [Exit i] *)
  (* val exit: int -> 'a *)

  type exit_reason =
    [ `Success | `False | `Bad_arguments | `Not_found | `Aborted | `Locked
    | `No_solution | `File_error | `Package_operation_error | `Sync_error
    | `Configuration_error | `Solver_failure | `Internal_error
    | `User_interrupt ]

  val exit_codes : (exit_reason * int) list

  val get_exit_code : exit_reason -> int

  (** Raises [Exit], with the code associated to the exit reason *)
  val exit_because: exit_reason -> 'a

  (**/**)

  type warning_printer =
    {mutable warning : 'a . ('a, unit, string, unit) format4 -> 'a}
  val set_warning_printer : warning_printer -> unit
end

(** {2 Windows-specific functions} *)
module Win32 : sig
  (** Win32 Registry Hives and Values *)
  module RegistryHive : sig
    val to_string : OpamStubs.registry_root -> string
    val of_string : string -> OpamStubs.registry_root
  end

  val set_parent_pid : int32 -> unit
  (** Change which the pid written to by {!parent_putenv}. This function cannot
      be called after [parent_putenv]. *)

  val parent_putenv : string -> string -> bool
  (** Update an environment variable in the parent (i.e. shell) process's
      environment. *)

  val persistHomeDirectory : string -> unit
  (** [persistHomeDirectory value] sets the HOME environment variable in this
      and the parent process and also persists the setting to the user's
      registry and broadcasts the change to other processes. *)
end

(** {2 General use infix function combinators} *)

module Op: sig

  (** Function application (with lower priority) (predefined in OCaml 4.01+) *)
  val (@@): ('a -> 'b) -> 'a -> 'b

  (** Pipe operator -- reverse application (predefined in OCaml 4.01+) *)
  val (|>): 'a -> ('a -> 'b) -> 'b

  (** Function composition : (f @* g) x =~ f (g x) *)
  val (@*): ('b -> 'c) -> ('a -> 'b) -> 'a -> 'c

  (** Reverse function composition : (f @> g) x =~ g (f x) *)
  val (@>): ('a -> 'b) -> ('b -> 'c) -> 'a -> 'c

end

(** {2 Helper functions to initialise configuration from the environment} *)

module Config : sig

  type env_var = string

  type when_ = [ `Always | `Never | `Auto ]
  type when_ext = [ `Extended | when_ ]
  type answer = [ `unsafe_yes | `all_yes | `all_no | `ask ]
  type yes_answer = [ `unsafe_yes | `all_yes ]

  (* Parse a envrionement variable boolean value *)
  val bool_of_string: string -> bool option

  val env: (string -> 'a) -> string -> 'a option

  val env_bool: env_var -> bool option

  val env_int: env_var -> int option

  type level = int
  (* Like [env_int], but accept boolean values for 0 and 1 *)
  val env_level: env_var -> level option

  type sections = int option String.Map.t
  val env_sections: env_var -> sections option

  val env_string: env_var -> string option

  val env_string_list : env_var -> string list option

  val env_float: env_var -> float option

  val env_when: env_var -> when_ option

  val env_when_ext: env_var -> when_ext option

  val resolve_when: auto:(bool Lazy.t) -> when_ -> bool

  val env_answer: env_var -> answer option

  module type Sig = sig

    (** Read-only record type containing the lib's configuration options *)
    type t

    (** Type of functions with optional arguments for setting each of [t]'s
        fields, similarly named, and returning ['a] *)
    type 'a options_fun

    (** The default values of the options to use at startup *)
    val default: t

    (** Use to update any option in a [t], using the optional arguments of
        [options_fun]. E.g. [set opts ?option1:1 ?option4:"x" ()] *)
    val set: t -> (unit -> t) options_fun

    (** Same as [set], but passes the result to a continuation, allowing
        argument stacking *)
    val setk: (t -> 'a) -> t -> 'a options_fun

    (** The global reference containing the currently set library options.
        Access using [OpamXxxConfig.(!r.field)]. *)
    val r: t ref

    (** Updates the currently set options in [r] according to the optional
        arguments *)
    val update: ?noop:_ -> (unit -> unit) options_fun

    (** Sets the options, reading the environment to get default values when
        unspecified *)
    val init: ?noop:_ -> (unit -> unit) options_fun

    (** Sets the options like [init], but returns the given value (for arguments
        stacking) *)
    val initk: 'a -> 'a options_fun

  end

  (* Opam environment variables handling *)
  module E : sig
    type t = ..
    type t += REMOVED
    val find: (t -> 'a option) -> 'a
    (* Lazy *)
    val value: (t -> 'a option) -> (unit -> 'a option)
    (* Not lazy *)
    val value_t: (t -> 'a option) -> 'a option
    val update: t -> unit
    val updates: t list -> unit
  end

end

(** {2 Polymorphic comparison functions}
    We use this module in opam codebase to flag polymorphic comparison usage.
*)
module Compare : sig
  val compare: 'a -> 'a -> int
  val equal: 'a -> 'a -> bool
  val (=): 'a -> 'a -> bool
  val (<>): 'a -> 'a -> bool
  val (<): 'a -> 'a -> bool
  val (>): 'a -> 'a -> bool
  val (<=): 'a -> 'a -> bool
  val (>=): 'a -> 'a -> bool
end
