Module OS.Env

Environment variables.

Process environment

type t = string Astring.String.map

The type for process environments.

val current : unit -> (t, 'e) result

current () is the current process environment.

Variables

val var : string -> string option

var name is the value of the environment variable name, if defined.

val set_var : string -> string option -> (unit, 'e) result

set_var name v sets the environment variable name to v.

BUG. The Unix module doesn't bind to unsetenv(3), hence for now using None will not unset the variable, it will set it to "". This behaviour may change in future versions of the library.

val opt_var : string -> absent:string -> string

opt_var name absent is the value of the optionally defined environment variable name if defined and absent if undefined.

val req_var : string -> (string, 'e) result

req_var name is the value of the environment variable name or an error if name is undefined in the environment.

Typed lookup

See the examples.

type 'a parser = string -> ('a, Rresult.R.msg) result

The type for environment variable value parsers.

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

parser kind k_of_string is an environment variable value from the k_of_string function. kind is used for error reports (e.g. could be "int" for an int parser).

val bool : bool parser

bool s is a boolean parser. The string is lowercased and the result is:

  • Ok false if it is one of "", "false", "no", "n" or "0".
  • Ok true if it is one of "true", "yes", "y" or "1".
  • An Error otherwise.
val string : string parser

string s is a string parser, it always succeeds.

val path : Fpath.t parser

path s is a path parser using Fpath.of_string.

val cmd : Cmd.t parser

cmd s is a non-empty command parser using Cmd.of_string.

val some : 'a parser -> 'a option parser

some p is wraps p's parse result in Some.

val parse : string -> 'a parser -> absent:'a -> ('a, 'e) result

parse name p ~absent is:

  • Ok absent if Env.var name = None
  • Ok v if Env.var name = Some s and p s = Ok v
  • Error (`Msg m) otherwise with m an error message that mentions name and the parse error of p.
val value : ?log:Logs.level -> string -> 'a parser -> absent:'a -> 'a

value ~log name p ~absent is like parse but in case of error the message is logged with level log (defaults to Logs.Error) and ~absent is returned.

Examples

let debug : bool = OS.Env.(value "DEBUG" bool ~absent:false)
let msg : string = OS.Env.(value "MSG" string ~absent:"no message")

let timeout : int option =
  let int = OS.Env.(some @@ parser "int" String.to_int) in
  OS.Env.value "TIMEOUT" int ~absent:None