environment(): Allow stacking append() and prepend() (#8547)

* environment(): Allow stacking append() and prepend()

* Update docs/markdown/Reference-manual.md

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

2 files changed, 29 insertions, 2 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 6e18e68..74f3324 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -2752,8 +2752,19 @@ tests and other functions. It has the following methods.
   joined by the separator, e.g.  `env.set('FOO', 'BAR'),` sets envvar
   `FOO` to value `BAR`. See `append()` above for how separators work.
 
-**Note:** All these methods overwrite the previously-defined value(s)
-if called twice with the same `varname`.
+*Since 0.58.0* `append()` and `prepend()` methods can be called multiple times
+on the same `varname`. Earlier Meson versions would warn and only the last
+operation took effect.
+
+```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')
+```
 
 ### `external library` object
 
diff --git a/docs/markdown/snippets/environment.md b/docs/markdown/snippets/environment.md
new file mode 100644
index 0000000..1ed102d
--- /dev/null
+++ b/docs/markdown/snippets/environment.md
@@ -0,0 +1,16 @@
+## Multiple append() and prepend() in `environment()` object
+
+`append()` and `prepend()` methods can now be called multiple times
+on the same `varname`. Earlier Meson versions would warn and only the last
+opperation was taking effect.
+
+```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')
+```
+