Add two examples: imports and foreach pattern (#1387)

* add install info using homebrew on macos

* Update README.md

Fix markdownlint-cli not being happy

* add two examples: imports and foreach pattern

* changes according to review suggestions

* Format new Nickel examples

* Add missing test annotations to examples

* Fix failing example annotations

* Make sure the test TOML parser doesn't choke

---------

Co-authored-by: Yann Hamdaoui <yann.hamdaoui@gmail.com>
Co-authored-by: Yann Hamdaoui <yann.hamdaoui@tweag.io>
Co-authored-by: Viktor Kleen <vkleen+github@17220103.de>

examples/foreach-pattern/README.md

@@ -0,0 +1,16 @@
+# Foreach Pattern
+
+This example shows how a _foreach pattern_ works in Nickel using
+`std.array.map`. A second example combines a yaml-import with the map function.
+
+## Run
+
+```console
+nickel -f foreach-pattern.ncl export
+```
+
+Second example:
+
+```console
+nickel -f foreach-pattern-on-import.ncl export
+```

examples/foreach-pattern/data_users.yml

@@ -0,0 +1,6 @@
+---
+users:
+  - jane
+  - pete
+  - richie
+  - ellen

examples/foreach-pattern/foreach-pattern-on-import.ncl

@@ -0,0 +1,16 @@
+# test = 'ignore'
+let users =
+  (import "data_users.yml").users
+  |> std.array.map
+    (
+      fun name =>
+        {
+          username = name,
+          email = "%{name}@nickel-lang.org"
+        }
+    )
+in
+
+{
+  posix_users = users
+}

examples/foreach-pattern/foreach-pattern.ncl

@@ -0,0 +1,16 @@
+# test = 'pass'
+let users =
+  ["jane", "pete", "richie"]
+  |> std.array.map
+    (
+      fun name =>
+        {
+          username = name,
+          email = "%{name}@nickel-lang.org"
+        }
+    )
+in
+
+{
+  usernames = users
+}

examples/imports/README.md

@@ -0,0 +1,9 @@
+# Various Imports
+
+This example shows how Nickel can transparently import common serialization formats.
+
+## Run
+
+```console
+nickel -f imports.ncl export
+```

examples/imports/data_groups.json

@@ -0,0 +1,7 @@
+{
+  "groups": [
+    "desktop-users",
+    "administrators",
+    "terminal-users"
+  ]
+}

examples/imports/data_machines.toml

@@ -0,0 +1,5 @@
+machines = [
+  "VAX-11",
+  "PDP-1",
+  "Bomba"
+]

examples/imports/data_nickel_properties.ncl

@@ -0,0 +1,22 @@
+# test = 'pass'
+let kelvin_to_celcius = fun kelvin => kelvin - 273.15 in
+let kelvin_to_fahrenheit = fun kelvin => (kelvin - 273.15) * 1.8000 + 32.00 in
+
+let melting_celcius = std.string.from_number (kelvin_to_celcius 1728) in
+let melting_fahrenheit = std.string.from_number (kelvin_to_fahrenheit 1728) in
+
+let boiling_celcius = std.string.from_number (kelvin_to_celcius 3003) in
+let boiling_fahrenheit = std.string.from_number (kelvin_to_fahrenheit 3003) in
+
+{
+  physical = {
+    phase_at_STP = "solid",
+    melting_point = "1728 K (%{melting_celcius} °C, %{melting_fahrenheit} °F)",
+    boiling_point = "3003 K (%{boiling_celcius} °C, %{boiling_fahrenheit} °F)",
+    density = "8.908 g/cm3",
+    when_liquid = "7.81 g/cm3",
+    heat_of_fusion = "17.48 kJ/mol",
+    heat_of_vaporization = "379 kJ/mol",
+    molar_heat_capacity = "26.07 J/(mol·K)"
+  }
+}

examples/imports/data_users.yml

@@ -0,0 +1,6 @@
+---
+users:
+  - jane
+  - pete
+  - richie
+  - ellen

examples/imports/imports.ncl

@@ -0,0 +1,21 @@
+# test = 'ignore'
+
+# Nickel can import plain yaml, or json files
+let _users = (import "data_users.yml") in
+let _groups = (import "data_groups.json") in
+
+# It even imports toml
+let _machines = (import "data_machines.toml") in
+
+# And of course other nickel files
+let _nickel_properties = (import "data_nickel_properties.ncl") in
+
+# This is the output object
+{
+  users = _users.users,
+  groups = _groups.groups,
+  machines = _machines.machines,
+  off_topic = {
+    nickel_properties = _nickel_properties
+  }
+}