interpreter: Add a flatten() method to arrays

This allows users to do two things, flatten potentially nested arrays
themselves, and, to safely convert types that may be an array to not an
array.

```meson
x = [meson.get_external_property('may_be_array)].flatten()
```
```meson
x = ['a', ['b', 'c']]
assert(x.flatten() == ['a', 'b', 'c'])
```

2 files changed, 10 insertions, 0 deletions

diff --git a/docs/markdown/snippets/array-flatten.md b/docs/markdown/snippets/array-flatten.md
new file mode 100644
index 000000000..eaab19c5b
--- /dev/null
+++ b/docs/markdown/snippets/array-flatten.md
@@ -0,0 +1,5 @@
+## Array `.flatten()` method
+
+Arrays now have a `.flatten()` method, which turns nested arrays into a single
+flat array. This provides the same effect that Meson often does to arrays
+internally, such as when passed to most function arguments.
diff --git a/docs/yaml/elementary/list.yml b/docs/yaml/elementary/list.yml
index 1ffb6d2d3..430f871f9 100644
--- a/docs/yaml/elementary/list.yml
+++ b/docs/yaml/elementary/list.yml
@@ -40,3 +40,8 @@ methods:
 - name: length
   returns: int
   description: Returns the current size of the array / list.
+
+- name: flatten
+  returns: list[any]
+  since: 1.9.0
+  description: Returns a flattened copy of the array, with all nested arrays removed.