# std/envvars

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

The `std/envvars` module implements environment variable handling.

# Imports

oserrors, win_setenv, winlean

# Types

    ReadEnvEffect = object of ReadIOEffect

  Effect that denotes a read from an environment variable. Source Edit

    WriteEnvEffect = object of WriteIOEffect

  Effect that denotes a write to an environment variable. Source Edit

# Procs

    proc delEnv(key: string) {....tags: [WriteEnvEffect], raises: [OSError],
                               forbids: [].}

  Deletes the environment variable named `key`. If an error occurs, `OSError` is raised.

  See also:ven

  - getEnv proc
  - existsEnv proc
  - putEnv proc
  - envPairs iterator
  Source Edit

    proc existsEnv(key: string): bool {....tags: [ReadEnvEffect], raises: [],
                                        forbids: [].}

  Checks whether the environment variable named `key` exists. Returns true if it exists, false otherwise.

  See also:

  - getEnv proc
  - putEnv proc
  - delEnv proc
  - envPairs iterator

  Example:

      assert not existsEnv("unknownEnv")

  Source Edit

    proc getEnv(key: string; default = ""): string {....tags: [ReadEnvEffect],
        raises: [], forbids: [].}

  Returns the value of the environment variable named `key`.

  If the variable does not exist, `""` is returned. To distinguish whether a variable exists or it's value is just `""`, call existsEnv(key) proc.

  See also:

  - existsEnv proc
  - putEnv proc
  - delEnv proc
  - envPairs iterator

  Example:

      assert getEnv("unknownEnv") == ""
      assert getEnv("unknownEnv", "doesn't exist") == "doesn't exist"

  Source Edit

    proc putEnv(key, val: string) {....tags: [WriteEnvEffect], raises: [OSError],
                                    forbids: [].}

  Sets the value of the environment variable named `key` to `val`. If an error occurs, `OSError` is raised.

  See also:

  - getEnv proc
  - existsEnv proc
  - delEnv proc
  - envPairs iterator
  Source Edit

# Iterators

    iterator envPairs(): tuple[key, value: string] {....tags: [ReadEnvEffect],
        raises: [], forbids: [].}

  Iterate over all environments variables.

  In the first component of the tuple is the name of the current variable stored, in the second its value.

  Works in native backends, nodejs and vm, like the following APIs:

  - getEnv proc
  - existsEnv proc
  - putEnv proc
  - delEnv proc
  Source Edit