| 1 |
(**************************************************************************) |
| 2 |
(* *) |
| 3 |
(* Copyright 2012-2020 OCamlPro *) |
| 4 |
(* Copyright 2012 INRIA *) |
| 5 |
(* *) |
| 6 |
(* All rights reserved. This file is distributed under the terms of the *) |
| 7 |
(* GNU Lesser General Public License version 2.1, with the special *) |
| 8 |
(* exception on linking described in the file LICENSE. *) |
| 9 |
(* *) |
| 10 |
(**************************************************************************) |
| 11 |
|
| 12 |
(** Generic stdlib functions (String, List, Option, Sys submodules...) *) |
| 13 |
|
| 14 |
(** {2 Signatures and functors} *) |
| 15 |
|
| 16 |
(** Sets with extended interface and infix operators *) |
| 17 |
module type SET = sig |
| 18 |
|
| 19 |
include Set.S |
| 20 |
|
| 21 |
val map: (elt -> elt) -> t -> t |
| 22 |
|
| 23 |
val is_singleton: t -> bool |
| 24 |
|
| 25 |
(** Returns one element, assuming the set is a singleton. Raises [Not_found] |
| 26 |
on an empty set, [Failure] on a non-singleton. *) |
| 27 |
val choose_one : t -> elt |
| 28 |
|
| 29 |
val choose_opt: t -> elt option |
| 30 |
|
| 31 |
val of_list: elt list -> t |
| 32 |
val to_list_map: (elt -> 'b) -> t -> 'b list |
| 33 |
val to_string: t -> string |
| 34 |
val to_json: t OpamJson.encoder |
| 35 |
val of_json: t OpamJson.decoder |
| 36 |
val find: (elt -> bool) -> t -> elt |
| 37 |
val find_opt: (elt -> bool) -> t -> elt option |
| 38 |
|
| 39 |
(** Raises Failure in case the element is already present *) |
| 40 |
val safe_add: elt -> t -> t |
| 41 |
|
| 42 |
(** Accumulates the resulting sets of a function of elements until a fixpoint |
| 43 |
is reached *) |
| 44 |
val fixpoint: (elt -> t) -> t -> t |
| 45 |
|
| 46 |
(** [map_reduce f op t] applies [f] to every element of [t] and combines the |
| 47 |
results using associative operator [op]. Raises [Invalid_argument] on an |
| 48 |
empty set, or returns [default] if it is defined. *) |
| 49 |
val map_reduce: ?default:'a -> (elt -> 'a) -> ('a -> 'a -> 'a) -> t -> 'a |
| 50 |
|
| 51 |
module Op : sig |
| 52 |
val (++): t -> t -> t (** Infix set union *) |
| 53 |
|
| 54 |
val (--): t -> t -> t (** Infix set difference *) |
| 55 |
|
| 56 |
val (%%): t -> t -> t (** Infix set intersection *) |
| 57 |
end |
| 58 |
|
| 59 |
end |
| 60 |
|
| 61 |
(** Maps with extended interface *) |
| 62 |
module type MAP = sig |
| 63 |
|
| 64 |
include Map.S |
| 65 |
|
| 66 |
val to_string: ('a -> string) -> 'a t -> string |
| 67 |
val to_json: 'a OpamJson.encoder -> 'a t OpamJson.encoder |
| 68 |
val of_json: 'a OpamJson.decoder -> 'a t OpamJson.decoder |
| 69 |
val keys: 'a t -> key list |
| 70 |
val values: 'a t -> 'a list |
| 71 |
val find_opt: key -> 'a t -> 'a option |
| 72 |
val choose_opt: 'a t -> (key * 'a) option |
| 73 |
|
| 74 |
(** A key will be in the union of [m1] and [m2] if it is appears |
| 75 |
either [m1] or [m2], with the corresponding value. If a key |
| 76 |
appears in both [m1] and [m2], then the resulting value is built |
| 77 |
using the function given as argument. *) |
| 78 |
val union: ('a -> 'a -> 'a) -> 'a t -> 'a t -> 'a t |
| 79 |
|
| 80 |
val is_singleton: 'a t -> bool |
| 81 |
|
| 82 |
val of_list: (key * 'a) list -> 'a t |
| 83 |
|
| 84 |
(** Raises Failure in case the element is already present *) |
| 85 |
val safe_add: key -> 'a -> 'a t -> 'a t |
| 86 |
|
| 87 |
(** [update k f zero map] updates the binding of [k] in [map] using function |
| 88 |
[f], applied to the current value bound to [k] or [zero] if none *) |
| 89 |
val update: key -> ('a -> 'a) -> 'a -> 'a t -> 'a t |
| 90 |
|
| 91 |
(** [map_reduce f op t] applies [f] to every binding of [t] and combines the |
| 92 |
results using associative operator [op]. Raises [Invalid_argument] on an |
| 93 |
empty map, or returns [default] if it is defined. *) |
| 94 |
val map_reduce: |
| 95 |
?default:'b -> (key -> 'a -> 'b) -> ('b -> 'b -> 'b) -> 'a t -> 'b |
| 96 |
|
| 97 |
val filter_map: (key -> 'a -> 'b option) -> 'a t -> 'b t |
| 98 |
end |
| 99 |
|
| 100 |
(** A signature for handling abstract keys and collections thereof *) |
| 101 |
module type ABSTRACT = sig |
| 102 |
|
| 103 |
type t |
| 104 |
|
| 105 |
val compare: t -> t -> int |
| 106 |
val equal: t -> t -> bool |
| 107 |
val of_string: string -> t |
| 108 |
val to_string: t -> string |
| 109 |
val to_json: t OpamJson.encoder |
| 110 |
val of_json: t OpamJson.decoder |
| 111 |
|
| 112 |
module Set: SET with type elt = t |
| 113 |
module Map: MAP with type key = t |
| 114 |
end |
| 115 |
|
| 116 |
(** A basic implementation of ABSTRACT using strings *) |
| 117 |
module AbstractString : ABSTRACT with type t = string |
| 118 |
|
| 119 |
(** {3 Generators for set and map modules with printers} *) |
| 120 |
|
| 121 |
module type OrderedType = sig |
| 122 |
include Set.OrderedType |
| 123 |
val to_string: t -> string |
| 124 |
val to_json: t OpamJson.encoder |
| 125 |
val of_json: t OpamJson.decoder |
| 126 |
end |
| 127 |
|
| 128 |
module Set: sig |
| 129 |
module Make (S: OrderedType): SET with type elt = S.t |
| 130 |
end |
| 131 |
|
| 132 |
module Map: sig |
| 133 |
module Make (S: OrderedType): MAP with type key = S.t |
| 134 |
end |
| 135 |
|
| 136 |
|
| 137 |
(** {2 Integer collections} *) |
| 138 |
|
| 139 |
(** Map of ints *) |
| 140 |
module IntMap: MAP with type key = int |
| 141 |
|
| 142 |
(** Set of ints *) |
| 143 |
module IntSet: SET with type elt = int |
| 144 |
|
| 145 |
|
| 146 |
(** {2 Utility modules extending the standard library on base types} *) |
| 147 |
|
| 148 |
module Option: sig |
| 149 |
val map: ('a -> 'b) -> 'a option -> 'b option |
| 150 |
|
| 151 |
val iter: ('a -> unit) -> 'a option -> unit |
| 152 |
|
| 153 |
val default: 'a -> 'a option -> 'a |
| 154 |
|
| 155 |
val default_map: 'a option -> 'a option -> 'a option |
| 156 |
|
| 157 |
val replace : ('a -> 'b option) -> 'a option -> 'b option |
| 158 |
|
| 159 |
val map_default: ('a -> 'b) -> 'b -> 'a option -> 'b |
| 160 |
|
| 161 |
val compare: ('a -> 'a -> int) -> 'a option -> 'a option -> int |
| 162 |
|
| 163 |
val equal: ('a -> 'a -> bool) -> 'a option -> 'a option -> bool |
| 164 |
|
| 165 |
val to_string: ?none:string -> ('a -> string) -> 'a option -> string |
| 166 |
|
| 167 |
val to_list: 'a option -> 'a list |
| 168 |
|
| 169 |
val some: 'a -> 'a option |
| 170 |
|
| 171 |
val none: 'a -> 'b option |
| 172 |
|
| 173 |
(** [of_Not_found f x] calls [f x], catches [Not_found] and returns [None] *) |
| 174 |
val of_Not_found: ('a -> 'b) -> 'a -> 'b option |
| 175 |
|
| 176 |
module Op: sig |
| 177 |
val (>>=): 'a option -> ('a -> 'b option) -> 'b option |
| 178 |
val (>>|): 'a option -> ('a -> 'b) -> 'b option |
| 179 |
val (>>+): 'a option -> (unit -> 'a option) -> 'a option |
| 180 |
val (+!): 'a option -> 'a -> 'a |
| 181 |
val (++): 'a option -> 'a option -> 'a option |
| 182 |
end |
| 183 |
end |
| 184 |
|
| 185 |
module List : sig |
| 186 |
|
| 187 |
val cons: 'a -> 'a list -> 'a list |
| 188 |
|
| 189 |
(** Convert list items to string and concat. [sconcat_map sep f x] is equivalent |
| 190 |
to String.concat sep (List.map f x) but tail-rec. *) |
| 191 |
val concat_map: |
| 192 |
?left:string -> ?right:string -> ?nil:string -> ?last_sep:string -> |
| 193 |
string -> ('a -> string) -> 'a list -> string |
| 194 |
|
| 195 |
(** Like [List.find], but returning option instead of raising *) |
| 196 |
val find_opt: ('a -> bool) -> 'a list -> 'a option |
| 197 |
|
| 198 |
val to_string: ('a -> string) -> 'a list -> string |
| 199 |
|
| 200 |
(** Removes consecutive duplicates in a list *) |
| 201 |
val remove_duplicates: ('a -> 'a -> bool) -> 'a list -> 'a list |
| 202 |
|
| 203 |
(** Sorts the list, removing duplicates *) |
| 204 |
val sort_nodup: ('a -> 'a -> int) -> 'a list -> 'a list |
| 205 |
|
| 206 |
(** Filter and map *) |
| 207 |
val filter_map: ('a -> 'b option) -> 'a list -> 'b list |
| 208 |
|
| 209 |
(** Retrieves [Some] values from a list *) |
| 210 |
val filter_some: 'a option list -> 'a list |
| 211 |
|
| 212 |
(** Returns the first non-[None] value returned by the passed function on the |
| 213 |
elements of the passed list. |
| 214 |
@raise Not_found if all of them yield [None] *) |
| 215 |
val find_map: ('a -> 'b option) -> 'a list -> 'b |
| 216 |
|
| 217 |
(** Like [find_map], but returns [Some _] if succeeded and [None] if failed. *) |
| 218 |
val find_map_opt: ('a -> 'b option) -> 'a list -> 'b option |
| 219 |
|
| 220 |
(** Insert a value in an ordered list *) |
| 221 |
val insert: ('a -> 'a -> int) -> 'a -> 'a list -> 'a list |
| 222 |
|
| 223 |
(** Inserts a value at the given index (starting from 0) in the list (start or |
| 224 |
end if index < 0 or > length respectively). Not tail-recursive *) |
| 225 |
val insert_at: int -> 'a -> 'a list -> 'a list |
| 226 |
|
| 227 |
(** Like [List.assoc] with an equality function. *) |
| 228 |
val assoc: ('a -> 'a -> bool) -> 'a -> ('a * 'b) list -> 'b |
| 229 |
|
| 230 |
(** Like [assoc], but returning option instead of raising [Not_found] *) |
| 231 |
val assoc_opt: ('a -> 'a -> bool) -> 'a -> ('a * 'b) list -> 'b option |
| 232 |
|
| 233 |
(** Like [assoc], but as an option, and also returns the list with the |
| 234 |
binding removed, e.g. equivalent to [(assoc_opt x l, remove_assoc x l)] |
| 235 |
(but tail-recursive and more efficient) *) |
| 236 |
val pick_assoc: |
| 237 |
('a -> 'a -> bool) -> 'a -> ('a * 'b) list -> 'b option * ('a * 'b) list |
| 238 |
|
| 239 |
(** Like [assoc], but returns a boolean instead of associated value *) |
| 240 |
val mem_assoc: ('a -> 'a -> bool) -> 'a -> ('a * 'b) list -> bool |
| 241 |
|
| 242 |
(** [remove_assoc eq k l] removes first association of [k] from list [l] |
| 243 |
(tail-recursive). *) |
| 244 |
val remove_assoc: |
| 245 |
('a -> 'a -> bool) -> 'a -> ('a * 'b) list -> ('a * 'b) list |
| 246 |
|
| 247 |
(** [update_assoc key value list] updates the first value bound to [key] in |
| 248 |
the associative list [list], or appends [(key, value)] if the key is not |
| 249 |
bound. *) |
| 250 |
val update_assoc: |
| 251 |
('a -> 'a -> bool) -> 'a -> 'b -> ('a * 'b) list -> ('a * 'b) list |
| 252 |
|
| 253 |
(** Like [pick_assoc], but with a test function that takes a list element *) |
| 254 |
val pick: ('a -> bool) -> 'a list -> 'a option * 'a list |
| 255 |
|
| 256 |
(** Like [List.fold_left], but also performs [List.map] at the same time *) |
| 257 |
val fold_left_map: ('s -> 'a -> ('s * 'b)) -> 's -> 'a list -> 's * 'b list |
| 258 |
end |
| 259 |
|
| 260 |
module String : sig |
| 261 |
|
| 262 |
(** {3 Collections} *) |
| 263 |
|
| 264 |
module Map: MAP with type key = string |
| 265 |
|
| 266 |
module Set: SET with type elt = string |
| 267 |
|
| 268 |
(** Set of string sets *) |
| 269 |
module SetSet: SET with type elt = Set.t |
| 270 |
|
| 271 |
(** Map of string sets *) |
| 272 |
module SetMap: MAP with type key = Set.t |
| 273 |
|
| 274 |
(** {3 Checks} *) |
| 275 |
|
| 276 |
val starts_with: prefix:string -> string -> bool |
| 277 |
val ends_with: suffix:string -> string -> bool |
| 278 |
val for_all: (char -> bool) -> string -> bool |
| 279 |
val contains_char: string -> char -> bool |
| 280 |
val contains: sub:string -> string -> bool |
| 281 |
val exact_match: Re.re -> string -> bool |
| 282 |
val find_from: (char -> bool) -> string -> int -> int |
| 283 |
|
| 284 |
(** Like [String.compare], but with lowercase/uppercase variants ordered next |
| 285 |
to each other (still considered not equal though) *) |
| 286 |
val compare_case: string -> string -> int |
| 287 |
|
| 288 |
(** {3 Manipulation} *) |
| 289 |
|
| 290 |
val map: (char -> char) -> string -> string |
| 291 |
val strip: string -> string |
| 292 |
val strip_right: string -> string |
| 293 |
val sub_at: int -> string -> string |
| 294 |
val remove_prefix: prefix:string -> string -> string |
| 295 |
val remove_suffix: suffix:string -> string -> string |
| 296 |
|
| 297 |
(** [is_prefix_of from full str] returns true if [str] if a prefix of [full], |
| 298 |
with at least [from] first characters *) |
| 299 |
val is_prefix_of: from:int -> full:string -> string -> bool |
| 300 |
|
| 301 |
(** {4 Transformations} *) |
| 302 |
|
| 303 |
(** Cut a string at the first occurrence of the given char *) |
| 304 |
val cut_at: string -> char -> (string * string) option |
| 305 |
|
| 306 |
(** Same as [cut_at], but starts from the right *) |
| 307 |
val rcut_at: string -> char -> (string * string) option |
| 308 |
|
| 309 |
(** Split a string at occurrences of a given characters. Empty strings are |
| 310 |
skipped. *) |
| 311 |
val split: string -> char -> string list |
| 312 |
|
| 313 |
(** The same as [split], but keep empty strings (leading, trailing or between |
| 314 |
contiguous delimiters) *) |
| 315 |
val split_delim: string -> char -> string list |
| 316 |
|
| 317 |
val fold_left: ('a -> char -> 'a) -> 'a -> string -> 'a |
| 318 |
|
| 319 |
val is_hex: string -> bool |
| 320 |
|
| 321 |
end |
| 322 |
|
| 323 |
module Format : sig |
| 324 |
|
| 325 |
(** {4 Querying information} *) |
| 326 |
|
| 327 |
(** Returns the length of the string in terminal chars, ignoring ANSI color |
| 328 |
sequences from OpamConsole.colorise *) |
| 329 |
val visual_length: string -> int |
| 330 |
|
| 331 |
(** {4 Text formatting functions} *) |
| 332 |
|
| 333 |
(** Truncates the string to not visually get over [width] columns *) |
| 334 |
val cut_at_visual: string -> int -> string |
| 335 |
|
| 336 |
(** left indenting. [~visual] can be used to indent eg. ANSI colored |
| 337 |
strings and should correspond to the visible characters of s *) |
| 338 |
val indent_left: string -> ?visual:string -> int -> string |
| 339 |
|
| 340 |
val indent_right: string -> ?visual:string -> int -> string |
| 341 |
|
| 342 |
(** Pads fields in a table with spaces for alignment. *) |
| 343 |
val align_table: string list list -> string list list |
| 344 |
|
| 345 |
(** Cut long lines in string according to the terminal width *) |
| 346 |
val reformat: |
| 347 |
?start_column:int -> ?indent:int -> ?width:int -> string -> string |
| 348 |
|
| 349 |
(** Convert a list of items to string as a dashed list (already reformats |
| 350 |
supposes no additional left margin: don't use within OpamConsole.error or |
| 351 |
similar) *) |
| 352 |
val itemize: ?bullet:string -> ('a -> string) -> 'a list -> string |
| 353 |
|
| 354 |
(** Display a pretty list: ["x";"y";"z"] -> "x, y and z". |
| 355 |
"and" can be changed by specifying [last] *) |
| 356 |
val pretty_list: ?last:string -> string list -> string |
| 357 |
|
| 358 |
(** Splits a list of strings so that it can be printed as a table that should |
| 359 |
fit on screen *) |
| 360 |
val as_aligned_table: ?width:int -> string list -> string list list |
| 361 |
end |
| 362 |
|
| 363 |
module Exn : sig |
| 364 |
|
| 365 |
(** To use when catching default exceptions: ensures we don't catch fatal errors |
| 366 |
like C-c. try-with should _always_ (by decreasing order of preference): |
| 367 |
- either catch specific exceptions |
| 368 |
- or re-raise the same exception (preferably with [Exn.finalise]) |
| 369 |
- or call this function on the caught exception *) |
| 370 |
val fatal: exn -> unit |
| 371 |
|
| 372 |
(** Register a backtrace for when you need to process a finalizer (that |
| 373 |
internally uses exceptions) and then re-raise the same exception. |
| 374 |
To be printed by pretty_backtrace. *) |
| 375 |
val register_backtrace: exn -> unit |
| 376 |
|
| 377 |
(** Return a pretty-printed backtrace *) |
| 378 |
val pretty_backtrace: exn -> string |
| 379 |
|
| 380 |
(** Runs the given finaliser, then reraises the given exception, while |
| 381 |
preserving backtraces (when the OCaml version permits, e.g. >= 4.05.0) *) |
| 382 |
val finalise: exn -> (unit -> unit) -> 'a |
| 383 |
|
| 384 |
(** Execute the given continuation, then run the finaliser before returning |
| 385 |
the result. If an exception is raised, call [finalise] with the given |
| 386 |
finaliser. *) |
| 387 |
val finally: (unit -> unit) -> (unit -> 'a) -> 'a |
| 388 |
|
| 389 |
end |
| 390 |
|
| 391 |
(** {2 Manipulation and query of environment variables} *) |
| 392 |
|
| 393 |
module Env : sig |
| 394 |
|
| 395 |
(** {3 Generic functions} *) |
| 396 |
|
| 397 |
(** Remove from a c-separated list of string the ones with the given prefix *) |
| 398 |
val reset_value: prefix:string -> char -> string -> string list |
| 399 |
|
| 400 |
(** split a c-separated list of string in two according to the first |
| 401 |
occurrences of the string with the given [prefix]. The list of |
| 402 |
elements occurring before is returned in reverse order. If there are |
| 403 |
other elements with the same [prefix] they are kept in the second list. |
| 404 |
*) |
| 405 |
val cut_value: prefix:string -> char -> string -> string list * string list |
| 406 |
|
| 407 |
(** Utility function for shell single-quoted strings. In most shells, |
| 408 |
backslash escapes are not allowed and a single quote needs to be replaced |
| 409 |
by [quote double-quote quote double-quote quote] (close the single-quoted |
| 410 |
literal, put the single quote in a double-quoted literal, and reopen a |
| 411 |
single-quoted literal). fish is the exception and should set |
| 412 |
[using_backslashes] to escape both quotes and backslashes using |
| 413 |
backslashes *) |
| 414 |
val escape_single_quotes: ?using_backslashes:bool -> string -> string |
| 415 |
|
| 416 |
(** Utility function for PowerShell strings. *) |
| 417 |
val escape_powershell: string -> string |
| 418 |
|
| 419 |
(** {3 Environment variable handling} *) |
| 420 |
|
| 421 |
(** Environment variable names. Windows has complicated semantics for |
| 422 |
environment variables. The retrieval functions are case insensitive, but |
| 423 |
it's "legal" for the environment block to contain entries which differ |
| 424 |
only by case. If environment variables are set entirely using CRT or Win32 |
| 425 |
API functions, then there isn't usually a problem, the issue arises when |
| 426 |
creating a program where the environment block is instead passed. In this |
| 427 |
model, it's very easy to end up with two bindings in the same block. When |
| 428 |
dealing with Windows programs, this will mostly be transparent, but it's a |
| 429 |
problem with Cygwin which actively allows "duplicate" entries which differ |
| 430 |
by case only and implements Posix semantics on top of this. The problem is |
| 431 |
constantly with us thanks to the use of PATH on Unix, and Path on Windows! |
| 432 |
opam tries to ensure that environment variables are looked up according to |
| 433 |
the OS semantics (so case insensitively on Windows) and OpamEnv goes to |
| 434 |
some trouble to ensure that updates to environment variables are case |
| 435 |
preserving (i.e. PATH+=foo gets transformed to Path+=foo if Path exists |
| 436 |
in the environment block). |
| 437 |
|
| 438 |
Key to this is not accidentally treating environment variable names as |
| 439 |
strings, without using the appropriate comparison functions. Name.t |
| 440 |
represents environment variable names as private strings, providing |
| 441 |
comparison operators to handle them, and still allowing the possibility |
| 442 |
to coerce them to strings. |
| 443 |
*) |
| 444 |
module Name : sig |
| 445 |
include ABSTRACT with type t = private string |
| 446 |
|
| 447 |
val equal_string: t -> string -> bool |
| 448 |
|
| 449 |
end |
| 450 |
|
| 451 |
val get: string -> string |
| 452 |
|
| 453 |
val getopt: string -> string option |
| 454 |
|
| 455 |
val getopt_full: Name.t -> Name.t * string option |
| 456 |
|
| 457 |
val list: unit -> (Name.t * string) list |
| 458 |
val raw_env: unit -> string Array.t |
| 459 |
val cyg_env: string -> string Array.t |
| 460 |
end |
| 461 |
|
| 462 |
(** {2 System query and exit handling} *) |
| 463 |
|
| 464 |
module Sys : sig |
| 465 |
|
| 466 |
(** {3 Querying} *) |
| 467 |
|
| 468 |
(** true if stdout is bound to a terminal *) |
| 469 |
val tty_out : bool |
| 470 |
|
| 471 |
(** true if stdin is bound to a terminal *) |
| 472 |
val tty_in : bool |
| 473 |
|
| 474 |
(** Queried lazily, but may change on SIGWINCH *) |
| 475 |
val terminal_columns : unit -> int |
| 476 |
|
| 477 |
(** The user's home directory. Queried lazily *) |
| 478 |
val home: unit -> string |
| 479 |
|
| 480 |
(** The /etc directory *) |
| 481 |
val etc: unit -> string |
| 482 |
|
| 483 |
(** The system directory (Windows only) *) |
| 484 |
val system: unit -> string |
| 485 |
|
| 486 |
type os = Darwin |
| 487 |
| Linux |
| 488 |
| FreeBSD |
| 489 |
| OpenBSD |
| 490 |
| NetBSD |
| 491 |
| DragonFly |
| 492 |
| Cygwin |
| 493 |
| Win32 |
| 494 |
| Unix |
| 495 |
| Other of string |
| 496 |
|
| 497 |
(** Queried lazily *) |
| 498 |
val os: unit -> os |
| 499 |
|
| 500 |
(** The output of the command "uname", with the given argument. Memoised. *) |
| 501 |
val uname: string -> string option |
| 502 |
|
| 503 |
(** Append .exe (only if missing) to executable filenames on Windows *) |
| 504 |
val executable_name : string -> string |
| 505 |
|
| 506 |
(** The different families of shells we know about *) |
| 507 |
type powershell_host = Powershell_pwsh | Powershell |
| 508 |
type shell = SH_sh | SH_bash | SH_zsh | SH_csh | SH_fish |
| 509 |
| SH_pwsh of powershell_host | SH_cmd |
| 510 |
|
| 511 |
(** List of all supported shells *) |
| 512 |
val all_shells : shell list |
| 513 |
|
| 514 |
(** Guess the shell compat-mode *) |
| 515 |
val guess_shell_compat: unit -> shell |
| 516 |
|
| 517 |
(** Guess the location of .profile. Returns None if the shell doesn't |
| 518 |
support the concept of a .profile file. *) |
| 519 |
val guess_dot_profile: shell -> string option |
| 520 |
|
| 521 |
(** The separator character used in the PATH variable (varies depending on |
| 522 |
OS) *) |
| 523 |
val path_sep: char |
| 524 |
|
| 525 |
(** Splits a PATH-like variable separated with [path_sep]. More involved than |
| 526 |
it seems, because there may be quoting on Windows. By default, it returns |
| 527 |
the path cleaned (remove trailing, leading, contiguous delimiters). |
| 528 |
Optional argument [clean] permits to keep those empty strings. *) |
| 529 |
val split_path_variable: ?clean:bool -> string -> string list |
| 530 |
|
| 531 |
(** For native Windows builds, returns [`Cygwin] if the command is a Cygwin- |
| 532 |
compiled executable, [`Msys2] if the command is a MSYS2-compiled |
| 533 |
executable, and [`Tainted of [ `Msys2 | `Cygwin ]] if the command links |
| 534 |
to a library which is itself Cygwin- or MSYS2-compiled, or [`Native] |
| 535 |
otherwise. |
| 536 |
|
| 537 |
Note that this returns [`Native] on a Cygwin-build of opam! |
| 538 |
|
| 539 |
Both cygcheck and an unqualified command will be resolved if necessary |
| 540 |
using the current PATH. *) |
| 541 |
val get_windows_executable_variant: cygbin:string option -> |
| 542 |
string -> [ `Native | `Cygwin | `Tainted of [ `Msys2 | `Cygwin] | `Msys2 ] |
| 543 |
|
| 544 |
(** Determines if cygcheck in given cygwin binary directory comes from a |
| 545 |
Cygwin or MSYS2 installation. Determined by analysing the cygpath command |
| 546 |
found with it. *) |
| 547 |
val is_cygwin_cygcheck : cygbin:string option -> bool |
| 548 |
|
| 549 |
(** For native Windows builds, returns [`Cygwin] if the command is a Cygwin- |
| 550 |
or Msys2- compiled executable, and [`CygLinked] if the command links to a |
| 551 |
library which is itself Cygwin/Msys2-compiled, or [`Native] otherwise. |
| 552 |
|
| 553 |
Note that this returns [`Native] on a Cygwin-build of opam! |
| 554 |
|
| 555 |
Both cygcheck and an unqualified command will be resolved using the |
| 556 |
current PATH. *) |
| 557 |
val get_cygwin_variant: cygbin:string option -> string -> [ `Native | `Cygwin | `CygLinked ] |
| 558 |
|
| 559 |
(** Returns true if [get_cygwin_variant] is [`Cygwin] *) |
| 560 |
val is_cygwin_variant: cygbin:string option -> string -> bool |
| 561 |
|
| 562 |
(** {3 Exit handling} *) |
| 563 |
|
| 564 |
(** Like Stdlib.at_exit but with the possibility to call manually |
| 565 |
(eg. before exec()) *) |
| 566 |
val at_exit: (unit -> unit) -> unit |
| 567 |
|
| 568 |
(** Calls the functions registered in at_exit. Unneeded if exiting normally *) |
| 569 |
val exec_at_exit: unit -> unit |
| 570 |
|
| 571 |
(** Indicates intention to exit the program with given exit code *) |
| 572 |
exception Exit of int |
| 573 |
|
| 574 |
(** Indicates intention to exec() the given command (parameters as per |
| 575 |
[Unix.execvpe]), after proper finalisations. It's the responsibility of |
| 576 |
the main function to catch this, call [exec_at_exit], and |
| 577 |
[Unix.execvpe]. *) |
| 578 |
exception Exec of string * string array * string array |
| 579 |
|
| 580 |
(** Raises [Exit i] *) |
| 581 |
(* val exit: int -> 'a *) |
| 582 |
|
| 583 |
type exit_reason = |
| 584 |
[ `Success | `False | `Bad_arguments | `Not_found | `Aborted | `Locked |
| 585 |
| `No_solution | `File_error | `Package_operation_error | `Sync_error |
| 586 |
| `Configuration_error | `Solver_failure | `Internal_error |
| 587 |
| `User_interrupt ] |
| 588 |
|
| 589 |
val exit_codes : (exit_reason * int) list |
| 590 |
|
| 591 |
val get_exit_code : exit_reason -> int |
| 592 |
|
| 593 |
(** Raises [Exit], with the code associated to the exit reason *) |
| 594 |
val exit_because: exit_reason -> 'a |
| 595 |
|
| 596 |
(**/**) |
| 597 |
|
| 598 |
type warning_printer = |
| 599 |
{mutable warning : 'a . ('a, unit, string, unit) format4 -> 'a} |
| 600 |
val set_warning_printer : warning_printer -> unit |
| 601 |
end |
| 602 |
|
| 603 |
(** {2 Windows-specific functions} *) |
| 604 |
module Win32 : sig |
| 605 |
(** Win32 Registry Hives and Values *) |
| 606 |
module RegistryHive : sig |
| 607 |
val to_string : OpamStubs.registry_root -> string |
| 608 |
val of_string : string -> OpamStubs.registry_root |
| 609 |
end |
| 610 |
|
| 611 |
val set_parent_pid : int32 -> unit |
| 612 |
(** Change which the pid written to by {!parent_putenv}. This function cannot |
| 613 |
be called after [parent_putenv]. *) |
| 614 |
|
| 615 |
val parent_putenv : string -> string -> bool |
| 616 |
(** Update an environment variable in the parent (i.e. shell) process's |
| 617 |
environment. *) |
| 618 |
|
| 619 |
val persistHomeDirectory : string -> unit |
| 620 |
(** [persistHomeDirectory value] sets the HOME environment variable in this |
| 621 |
and the parent process and also persists the setting to the user's |
| 622 |
registry and broadcasts the change to other processes. *) |
| 623 |
end |
| 624 |
|
| 625 |
(** {2 General use infix function combinators} *) |
| 626 |
|
| 627 |
module Op: sig |
| 628 |
|
| 629 |
(** Function application (with lower priority) (predefined in OCaml 4.01+) *) |
| 630 |
val (@@): ('a -> 'b) -> 'a -> 'b |
| 631 |
|
| 632 |
(** Pipe operator -- reverse application (predefined in OCaml 4.01+) *) |
| 633 |
val (|>): 'a -> ('a -> 'b) -> 'b |
| 634 |
|
| 635 |
(** Function composition : (f @* g) x =~ f (g x) *) |
| 636 |
val (@*): ('b -> 'c) -> ('a -> 'b) -> 'a -> 'c |
| 637 |
|
| 638 |
(** Reverse function composition : (f @> g) x =~ g (f x) *) |
| 639 |
val (@>): ('a -> 'b) -> ('b -> 'c) -> 'a -> 'c |
| 640 |
|
| 641 |
end |
| 642 |
|
| 643 |
(** {2 Helper functions to initialise configuration from the environment} *) |
| 644 |
|
| 645 |
module Config : sig |
| 646 |
|
| 647 |
type env_var = string |
| 648 |
|
| 649 |
type when_ = [ `Always | `Never | `Auto ] |
| 650 |
type when_ext = [ `Extended | when_ ] |
| 651 |
type answer = [ `unsafe_yes | `all_yes | `all_no | `ask ] |
| 652 |
type yes_answer = [ `unsafe_yes | `all_yes ] |
| 653 |
|
| 654 |
(* Parse a envrionement variable boolean value *) |
| 655 |
val bool_of_string: string -> bool option |
| 656 |
|
| 657 |
val env: (string -> 'a) -> string -> 'a option |
| 658 |
|
| 659 |
val env_bool: env_var -> bool option |
| 660 |
|
| 661 |
val env_int: env_var -> int option |
| 662 |
|
| 663 |
type level = int |
| 664 |
(* Like [env_int], but accept boolean values for 0 and 1 *) |
| 665 |
val env_level: env_var -> level option |
| 666 |
|
| 667 |
type sections = int option String.Map.t |
| 668 |
val env_sections: env_var -> sections option |
| 669 |
|
| 670 |
val env_string: env_var -> string option |
| 671 |
|
| 672 |
val env_float: env_var -> float option |
| 673 |
|
| 674 |
val env_when: env_var -> when_ option |
| 675 |
|
| 676 |
val env_when_ext: env_var -> when_ext option |
| 677 |
|
| 678 |
val resolve_when: auto:(bool Lazy.t) -> when_ -> bool |
| 679 |
|
| 680 |
val env_answer: env_var -> answer option |
| 681 |
|
| 682 |
module type Sig = sig |
| 683 |
|
| 684 |
(** Read-only record type containing the lib's configuration options *) |
| 685 |
type t |
| 686 |
|
| 687 |
(** Type of functions with optional arguments for setting each of [t]'s |
| 688 |
fields, similarly named, and returning ['a] *) |
| 689 |
type 'a options_fun |
| 690 |
|
| 691 |
(** The default values of the options to use at startup *) |
| 692 |
val default: t |
| 693 |
|
| 694 |
(** Use to update any option in a [t], using the optional arguments of |
| 695 |
[options_fun]. E.g. [set opts ?option1:1 ?option4:"x" ()] *) |
| 696 |
val set: t -> (unit -> t) options_fun |
| 697 |
|
| 698 |
(** Same as [set], but passes the result to a continuation, allowing |
| 699 |
argument stacking *) |
| 700 |
val setk: (t -> 'a) -> t -> 'a options_fun |
| 701 |
|
| 702 |
(** The global reference containing the currently set library options. |
| 703 |
Access using [OpamXxxConfig.(!r.field)]. *) |
| 704 |
val r: t ref |
| 705 |
|
| 706 |
(** Updates the currently set options in [r] according to the optional |
| 707 |
arguments *) |
| 708 |
val update: ?noop:_ -> (unit -> unit) options_fun |
| 709 |
|
| 710 |
(** Sets the options, reading the environment to get default values when |
| 711 |
unspecified *) |
| 712 |
val init: ?noop:_ -> (unit -> unit) options_fun |
| 713 |
|
| 714 |
(** Sets the options like [init], but returns the given value (for arguments |
| 715 |
stacking) *) |
| 716 |
val initk: 'a -> 'a options_fun |
| 717 |
|
| 718 |
end |
| 719 |
|
| 720 |
(* Opam environment variables handling *) |
| 721 |
module E : sig |
| 722 |
type t = .. |
| 723 |
type t += REMOVED |
| 724 |
val find: (t -> 'a option) -> 'a |
| 725 |
(* Lazy *) |
| 726 |
val value: (t -> 'a option) -> (unit -> 'a option) |
| 727 |
(* Not lazy *) |
| 728 |
val value_t: (t -> 'a option) -> 'a option |
| 729 |
val update: t -> unit |
| 730 |
val updates: t list -> unit |
| 731 |
end |
| 732 |
|
| 733 |
end |
| 734 |
|
| 735 |
(** {2 Polymorphic comparison functions} |
| 736 |
We use this module in opam codebase to flag polymorphic comparison usage. |
| 737 |
*) |
| 738 |
module Compare : sig |
| 739 |
val compare: 'a -> 'a -> int |
| 740 |
val equal: 'a -> 'a -> bool |
| 741 |
val (=): 'a -> 'a -> bool |
| 742 |
val (<>): 'a -> 'a -> bool |
| 743 |
val (<): 'a -> 'a -> bool |
| 744 |
val (>): 'a -> 'a -> bool |
| 745 |
val (<=): 'a -> 'a -> bool |
| 746 |
val (>=): 'a -> 'a -> bool |
| 747 |
end |