From 1de7dce41495a57404cefc6ecf3991c66e30f3ec Mon Sep 17 00:00:00 2001
From: Mathieu Duponchelle <mathieu@centricular.com>
Date: Sun, 20 May 2018 22:35:14 +0200
Subject: dict: Document, add release snippet

---
 docs/markdown/Syntax.md | 64 ++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 58 insertions(+), 6 deletions(-)

(limited to 'docs/markdown/Syntax.md')

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
 --
-- 
cgit v1.2.3


From fe6fc59ee75f44acdaac0abc757c687916d4618a Mon Sep 17 00:00:00 2001
From: Mathieu Duponchelle <mathieu@centricular.com>
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/Syntax.md')

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