diff options
author | Daniel Mensinger <daniel@mensinger-ka.de> | 2022-01-23 16:03:03 +0100 |
---|---|---|
committer | Eli Schwartz <eschwartz93@gmail.com> | 2022-04-07 17:16:26 -0400 |
commit | 0808ae1b3d32eebd68342329428631e6a9be4248 (patch) | |
tree | 9e35c7697b9f86e99c08e43ca8a573e56d8571ca /docs/markdown/Syntax.md | |
parent | 8e13e63fcab24f0276e5b67ee1f4cd107be06824 (diff) | |
download | meson-0808ae1b3d32eebd68342329428631e6a9be4248.zip meson-0808ae1b3d32eebd68342329428631e6a9be4248.tar.gz meson-0808ae1b3d32eebd68342329428631e6a9be4248.tar.bz2 |
docs: Document argument flattening
Diffstat (limited to 'docs/markdown/Syntax.md')
-rw-r--r-- | docs/markdown/Syntax.md | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md index 5bcbdb5..8c6ac24 100644 --- a/docs/markdown/Syntax.md +++ b/docs/markdown/Syntax.md @@ -527,6 +527,54 @@ executable('progname', 'prog.c', Attempting to do this causes Meson to immediately exit with an error. +### Argument flattening + +Argument flattening is a Meson feature that aims to simplify using +methods and functions. For functions where this feature is active, +Meson takes the list of arguments and flattens all nested lists into +one big list. + +For instance the following function calls to [[executable]] are +identical in Meson: + +```meson +# A normal example: +executable('exe1', ['foo.c', 'bar.c', 'foobar.c']) + +# A more contrived example that also works but certainly +# isn't good Meson code: +l1 = ['bar.c'] +executable('exe1', [[['foo.c', l1]], ['foobar.c']]) + +# How meson will treat all the previous calls internally: +executable('exe1', 'foo.c', 'bar.c', 'foobar.c') +``` + +Because of an internal implementation detail, the following syntax +is currently also supported, even though the first argument of +[[executable]] is a single [[@str]] and not a [[@list]]: + +```meson +# WARNING: This example is only valid because of an internal +# implementation detail and not because it is intended +# +# PLEASE DO NOT DO SOMETHING LIKE THIS! +# +executable(['exe1', 'foo.c'], 'bar.c', 'foobar.c') +``` + +This code is currently accepted because argument flattening *currently* +happens before the parameters are evaluated. "Support" for +such constructs will likely be removed in future Meson releases! + +Argument flattening is supported by *most* but not *all* Meson +functions and methods. As a general rule, it can be assumed that a +function or method supports argument flattening if the exact list +structure is irrelevant to a function. + +Whether a function supports argument flattening is documented in the +[Reference Manual](Reference-manual.md). + ## Method calls Objects can have methods, which are called with the dot operator. The |