Env (opam-core.OpamStd.Env)

Raw array functions

type raw = string array

val raw_env : unit -> raw

Same as Unix.environment

val get_from_array : raw -> string -> string option

get_from_array array key returns the value of the first element of array associated with key. Returns None if nothing was found.

val add_and_replace : raw -> (string * string) -> raw

add_and_replace array (key, value) returns a fresh array containing at least key=value and array where all the elements matching key will be replaced by key=value as well.

This makes sure any applications will always associate key with value as per POSIX.1-2024: > If more than one string in an environment of a process has the same name, > the consequences are undefined. https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html

Generic functions

val reset_value : prefix:string -> char -> string -> string list

Remove from a c-separated list of string the ones with the given prefix

val cut_value : prefix:string -> char -> string -> string list * 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 escape_single_quotes : ?using_backslashes:bool -> string -> string

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_powershell : string -> string

Utility function for PowerShell strings.

Environment variable handling

module Name : sig ... end

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).

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 cyg_env : 
  env:string array ->
  cygbin:string ->
  git_location:string option ->
  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`.