name: env
long_name: Environment
description: |
  This object is returned by [[environment]] and stores
  detailed information about how environment variables should be set
  during tests. It should be passed as the `env` keyword argument to
  tests and other functions.

  *Since 0.58.0* [[env.append]] and [[env.prepend]] can be called multiple times
  on the same `varname`. Earlier Meson versions would warn and only the last
  operation took effect.

example: |
  ```meson
  env = environment()

  # MY_PATH will be '0:1:2:3'
  env.set('MY_PATH', '1')
  env.append('MY_PATH', '2')
  env.append('MY_PATH', '3')
  env.prepend('MY_PATH', '0')
  ```

methods:
- name: append
  returns: void
  description: |
    appends the given values to
    the old value of the environment variable, e.g.  `env.append('FOO',
    'BAR', 'BAZ', separator : ';')` produces `BOB;BAR;BAZ` if `FOO` had
    the value `BOB` and plain `BAR;BAZ` if the value was not defined.

  posargs:
    variable:
      type: str
      description: The variable to modify

  varargs:
    type: str
    name: Value
    description: The values to append

  kwargs:
    separator:
      type: str
      description: |
        The separator to use. If not explicitly specified, the default path
        separator for the host operating system will be used, i.e. ';' for
        Windows and ':' for UNIX/POSIX systems.

- name: prepend
  returns: void
  description: Same as `append` except that it writes to the beginning of the variable.

  posargs:
    variable:
      type: str
      description: The variable to modify

  varargs:
    type: str
    name: Value
    description: The values to prepend

  kwargs_inherit: env.append

- name: set
  returns: void
  description: |
    Sets the environment variable
    specified in the first argument to the values in the varargs
    joined by the separator. For instance, `env.set('FOO', 'BAR'),` sets envvar
    `FOO` to value `BAR`.

  posargs:
    variable:
      type: str
      description: The variable to modify

  varargs:
    type: str
    name: Value
    description: The values to set

  kwargs_inherit: env.append