Allow setting method/separator in environment() and meson.add_devenv()

3 files changed, 64 insertions, 3 deletions

diff --git a/docs/markdown/snippets/devenv.md b/docs/markdown/snippets/devenv.md
index 505f971..104cfd9 100644
--- a/docs/markdown/snippets/devenv.md
+++ b/docs/markdown/snippets/devenv.md
@@ -21,3 +21,23 @@ directory, that file is loaded by gdb automatically.
 With `--dump` option, all envorinment variables that have been modified are
 printed instead of starting an interactive shell. It can be used by shell
 scripts that wish to setup their environment themself.
+
+## New `method` and `separator` kwargs on `environment()` and `meson.add_devenv()`
+
+It simplifies this common pattern:
+```meson
+env = environment()
+env.prepend('FOO', ['a', 'b'], separator: ',')
+meson.add_devenv(env)
+```
+
+becomes one line:
+```meson
+meson.add_devenv({'FOO': ['a', 'b']}, method: 'prepend', separator: ',')
+```
+
+or two lines:
+```meson
+env = environment({'FOO': ['a', 'b']}, method: 'prepend', separator: ',')
+meson.add_devenv(env)
+```
diff --git a/docs/yaml/builtins/meson.yaml b/docs/yaml/builtins/meson.yaml
index 92fc90e..09e5dbb 100644
--- a/docs/yaml/builtins/meson.yaml
+++ b/docs/yaml/builtins/meson.yaml
@@ -444,5 +444,25 @@ methods:
 
     posargs:
       env:
-        type: env
-        description: The [[@env]] object to add.
+        type: env | str | list[str] | dict[str] | dict[list[str]]
+        description: |
+          The [[@env]] object to add.
+          Since *0.62.0* list of strings is allowed in dictionnary values. In that
+          case values are joined using the separator.
+    kwargs:
+      separator:
+        type: str
+        since: 0.62.0
+        description: |
+          The separator to use for the initial values defined in
+          the first positional argument. 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.
+      method:
+        type: str
+        since: 0.62.0
+        description: |
+          Must be one of 'set', 'prepend', or 'append'
+          (defaults to 'set'). Controls if initial values defined in the first
+          positional argument are prepended, appended or repace the current value
+          of the environment variable.
diff --git a/docs/yaml/functions/environment.yaml b/docs/yaml/functions/environment.yaml
index 99c8a45..5fb81e3 100644
--- a/docs/yaml/functions/environment.yaml
+++ b/docs/yaml/functions/environment.yaml
@@ -5,8 +5,29 @@ description: Returns an empty [[@env]] object.
 
 optargs:
   env:
-    type: dict[str]
+    type: str | list[str] | dict[str] | dict[list[str]]
     since: 0.52.0
     description: |
       If provided, each key/value pair is added into the [[@env]] object
       as if [[env.set]] method was called for each of them.
+      Since *0.62.0* list of strings is allowed in dictionnary values. In that
+      case values are joined using the separator.
+
+kwargs:
+  separator:
+    type: str
+    since: 0.62.0
+    description: |
+      The separator to use for the initial values defined in
+      the first positional argument. 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.
+
+  method:
+    type: str
+    since: 0.62.0
+    description: |
+      Must be one of 'set', 'prepend', or 'append'
+      (defaults to 'set'). Controls if initial values defined in the first
+      positional argument are prepended, appended or repace the current value
+      of the environment variable.