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'])
```

Author: dcbaker

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.

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: array[any]
+  since: 1.9.0
+  description: Returns a flattened copy of the array, with all nested arrays removed.

mesonbuild/interpreter/primitives/array.py

@@ -33,6 +33,7 @@ def __init__(self, obj: T.List[TYPE_var], interpreter: 'Interpreter') -> None:
             'contains': self.contains_method,
             'length': self.length_method,
             'get': self.get_method,
+            'flatten': self.flatten_method,
         })
 
         self.trivial_operators.update({
@@ -106,3 +107,16 @@ def op_index(self, other: int) -> TYPE_var:
             return self.held_object[other]
         except IndexError:
             raise InvalidArguments(f'Index {other} out of bounds of array of size {len(self.held_object)}.')
+
+    @noPosargs
+    @noKwargs
+    @FeatureNew('array.flatten', '1.9.0')
+    def flatten_method(self, args: T.List[TYPE_var], kwargs: TYPE_kwargs) -> TYPE_var:
+        def flatten(obj: TYPE_var) -> T.Iterable[TYPE_var]:
+            if isinstance(obj, list):
+                for o in obj:
+                    yield from flatten(o)
+            else:
+                yield obj
+
+        return list(flatten(self.held_object))

test cases/common/56 array methods/meson.build

@@ -1,4 +1,4 @@
-project('array methods')
+project('array methods', meson_version : '>= 1.9')
 
 empty = []
 one = ['abc']
@@ -68,3 +68,10 @@ endif
 if not combined.contains('ghi')
   error('Combined claims not to contain ghi.')
 endif
+
+# test array flattening
+x = ['a', ['b'], [[[[[[['c'], 'd']]], 'e']]]]
+assert(x.length() == 3)
+assert(x.flatten().length() == 5)
+assert(x.flatten() == ['a', 'b', 'c', 'd', 'e'])
+assert(['a', ['b', 'c']].flatten() == ['a', 'b', 'c'])