From 1de7dce41495a57404cefc6ecf3991c66e30f3ec Mon Sep 17 00:00:00 2001 From: Mathieu Duponchelle Date: Sun, 20 May 2018 22:35:14 +0200 Subject: dict: Document, add release snippet --- docs/markdown/Reference-manual.md | 15 ++++++++ docs/markdown/Syntax.md | 64 ++++++++++++++++++++++++++++++---- docs/markdown/snippets/dict_builtin.md | 19 ++++++++++ 3 files changed, 92 insertions(+), 6 deletions(-) create mode 100644 docs/markdown/snippets/dict_builtin.md (limited to 'docs/markdown') diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 2498b9899..277353b75 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -1730,6 +1730,21 @@ The following methods are defined for all [arrays](Syntax.md#arrays): You can also iterate over arrays with the [`foreach` statement](Syntax.md#foreach-statements). +### `dictionary` object + +The following methods are defined for all [dictionaries](Syntax.md#dictionaries): + +- `has_key(key)` returns `true` if the dictionary contains the key + given as argument, `false` otherwise + +- `get(key, fallback)`, returns the value for the key given as first argument + if it is present in the dictionary, or the optional fallback value given + as the second argument. If a single argument was given and the key was not + found, causes a fatal error + +You can also iterate over dictionaries with the [`foreach` +statement](Syntax.md#foreach-statements). + ## Returned objects These are objects returned by the [functions listed above](#functions). diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md index 30eedf814..69b3f526f 100644 --- a/docs/markdown/Syntax.md +++ b/docs/markdown/Syntax.md @@ -284,6 +284,29 @@ The following methods are defined for all arrays: - `contains`, returns `true` if the array contains the object given as argument, `false` otherwise - `get`, returns the object at the given index, negative indices count from the back of the array, indexing out of bounds is a fatal error. Provided for backwards-compatibility, it is identical to array indexing. +Dictionaries +-- + +Dictionaries are delimited by curly braces. A dictionary can contain an +arbitrary number of key value pairs. Keys are required to be literal +strings, values can be objects of any type. + +```meson +my_dict = {'foo': 42, 'bar': 'baz'} +``` + +Keys must be unique: + +```meson +# This will fail +my_dict = {'foo': 42, 'foo': 43} +``` + +Dictionaries are immutable. + +Visit the [Reference Manual](Reference-manual.md#dictionary-object) to read +about the methods exposed by dictionaries. + Function calls -- @@ -329,9 +352,17 @@ endif ## Foreach statements -To do an operation on all elements of an array, use the `foreach` -command. As an example, here's how you would define two executables -with corresponding tests. +To do an operation on all elements of an iterable, use the `foreach` +command. + +> Note that Meson variables are immutable. Trying to assign a new value +> to the iterated object inside a foreach loop will not affect foreach's +> control flow. + +### Foreach with an array + +Here's an example of how you could define two executables +with corresponding tests using arrays and foreach. ```meson progs = [['prog1', ['prog1.c', 'foo.c']], @@ -343,9 +374,30 @@ foreach p : progs endforeach ``` -Note that Meson variables are immutable. Trying to assign a new value -to `progs` inside a foreach loop will not affect foreach's control -flow. +### Foreach with a dictionary + +Here's an example of you could iterate a set of components that +should be compiled in according to some configuration. + +```meson +components = { + 'foo': ['foo.c'], + 'bar': ['bar.c'], + 'baz:' ['baz.c'], +} + +# compute a configuration based on system dependencies, custom logic +conf = configuration_data() +conf.set('USE_FOO', 1) + +# Determine the sources to compile +sources_to_compile = [] +foreach name, sources : components + if conf.get('USE_@0@'.format(name.to_upper()), 0) == 1 + sources_to_compile += sources + endif +endforeach +``` Logical operations -- diff --git a/docs/markdown/snippets/dict_builtin.md b/docs/markdown/snippets/dict_builtin.md new file mode 100644 index 000000000..b60fd0a38 --- /dev/null +++ b/docs/markdown/snippets/dict_builtin.md @@ -0,0 +1,19 @@ +## New built-in object dictionary + +Meson dictionaries use a syntax similar to python's dictionaries, +but have a narrower scope: they are immutable, keys can only +be string literals, and initializing a dictionary with duplicate +keys causes a fatal error. + +Example usage: + +```meson +dict = {'foo': 42, 'bar': 'baz'} + +foo = dict.get('foo') +foobar = dict.get('foobar', 'fallback-value') + +foreach key, value : dict + # Do something with key and value +#endforeach +``` -- cgit v1.2.3 From 10e7566ed84251dcec6ee4ff3cc721e38fb90457 Mon Sep 17 00:00:00 2001 From: Mathieu Duponchelle Date: Mon, 21 May 2018 00:19:31 +0200 Subject: dict: fix CI issues --- docs/markdown/snippets/dict_builtin.md | 4 ++-- mesonbuild/interpreterbase.py | 2 +- mesonbuild/mparser.py | 2 +- run_unittests.py | 7 +++---- 4 files changed, 7 insertions(+), 8 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/snippets/dict_builtin.md b/docs/markdown/snippets/dict_builtin.md index b60fd0a38..1bd24cef9 100644 --- a/docs/markdown/snippets/dict_builtin.md +++ b/docs/markdown/snippets/dict_builtin.md @@ -14,6 +14,6 @@ foo = dict.get('foo') foobar = dict.get('foobar', 'fallback-value') foreach key, value : dict - # Do something with key and value -#endforeach + Do something with key and value +endforeach ``` diff --git a/mesonbuild/interpreterbase.py b/mesonbuild/interpreterbase.py index 6a979d180..9f323d113 100644 --- a/mesonbuild/interpreterbase.py +++ b/mesonbuild/interpreterbase.py @@ -300,7 +300,7 @@ class InterpreterBase: def evaluate_dictstatement(self, cur): (arguments, kwargs) = self.reduce_arguments(cur.args) - assert (not arguments, 'parser bug, arguments should be empty') + assert (not arguments) return kwargs def evaluate_notstatement(self, cur): diff --git a/mesonbuild/mparser.py b/mesonbuild/mparser.py index 18ee701e4..78683be51 100644 --- a/mesonbuild/mparser.py +++ b/mesonbuild/mparser.py @@ -657,7 +657,7 @@ class Parser: a.commas.append(potential) else: raise ParseException('Only key:value pairs are valid in dict construction.', - self.getline(), s.lineno, s.colno) + self.getline(), s.lineno, s.colno) s = self.statement() return a diff --git a/run_unittests.py b/run_unittests.py index 162bfcf9d..f93415baf 100755 --- a/run_unittests.py +++ b/run_unittests.py @@ -582,7 +582,6 @@ class BasePlatformTests(unittest.TestCase): if inprocess: try: (returncode, out, err) = run_configure(self.meson_mainfile, self.meson_args + args + extra_args) - print (out) if 'MESON_SKIP_TEST' in out: raise unittest.SkipTest('Project requested skipping.') if returncode != 0: @@ -2331,13 +2330,13 @@ class FailureTests(BasePlatformTests): def test_dict_requires_key_value_pairs(self): self.assertMesonRaises("dict = {3, 'foo': 'bar'}", - 'Only key:value pairs are valid in dict construction.') + 'Only key:value pairs are valid in dict construction.') self.assertMesonRaises("{'foo': 'bar', 3}", - 'Only key:value pairs are valid in dict construction.') + 'Only key:value pairs are valid in dict construction.') def test_dict_forbids_duplicate_keys(self): self.assertMesonRaises("dict = {'a': 41, 'a': 42}", - 'Duplicate dictionary key: a.*') + 'Duplicate dictionary key: a.*') class WindowsTests(BasePlatformTests): -- cgit v1.2.3 From fe6fc59ee75f44acdaac0abc757c687916d4618a Mon Sep 17 00:00:00 2001 From: Mathieu Duponchelle Date: Tue, 22 May 2018 00:17:42 +0200 Subject: dict: add since annotations --- docs/markdown/Reference-manual.md | 2 ++ docs/markdown/Syntax.md | 5 ++++- 2 files changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 277353b75..f9efe5338 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -1745,6 +1745,8 @@ The following methods are defined for all [dictionaries](Syntax.md#dictionaries) You can also iterate over dictionaries with the [`foreach` statement](Syntax.md#foreach-statements). +Dictionaries are available since 0.47.0. + ## Returned objects These are objects returned by the [functions listed above](#functions). diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md index 69b3f526f..42002f4ee 100644 --- a/docs/markdown/Syntax.md +++ b/docs/markdown/Syntax.md @@ -304,6 +304,8 @@ my_dict = {'foo': 42, 'foo': 43} Dictionaries are immutable. +Dictionaries are available since 0.47.0. + Visit the [Reference Manual](Reference-manual.md#dictionary-object) to read about the methods exposed by dictionaries. @@ -377,7 +379,8 @@ endforeach ### Foreach with a dictionary Here's an example of you could iterate a set of components that -should be compiled in according to some configuration. +should be compiled in according to some configuration. This uses +a [dictionary][dictionaries], which is available since 0.47.0. ```meson components = { -- cgit v1.2.3