From 1360948a41b64c1491b90dcc9860dcbd561a6b93 Mon Sep 17 00:00:00 2001
From: Martin Atkins <mart@degeneration.co.uk>
Date: Fri, 1 Jun 2018 18:56:34 -0700
Subject: [PATCH] website: document the functions "keys", "lookup", and
 "values"

I missed these on the first pass because in the legacy function table they
are, for some reason, added in a different place than the others.
---
 .../configuration/functions/element.html.md   |  1 +
 .../docs/configuration/functions/keys.html.md | 29 ++++++++++++++++
 .../configuration/functions/lookup.html.md    | 33 +++++++++++++++++++
 .../configuration/functions/values.html.md    | 31 +++++++++++++++++
 website/layouts/functions.erb                 | 12 +++++++
 5 files changed, 106 insertions(+)
 create mode 100644 website/docs/configuration/functions/keys.html.md
 create mode 100644 website/docs/configuration/functions/lookup.html.md
 create mode 100644 website/docs/configuration/functions/values.html.md

diff --git a/website/docs/configuration/functions/element.html.md b/website/docs/configuration/functions/element.html.md
index f1b799137..63ac16e26 100644
--- a/website/docs/configuration/functions/element.html.md
+++ b/website/docs/configuration/functions/element.html.md
@@ -38,3 +38,4 @@ a
 ## Related Functions
 
 * [`index`](./index.html) finds the index for a particular element value.
+* [`lookup`](./lookup.html) retrieves a value from a _map_ given its _key_.
diff --git a/website/docs/configuration/functions/keys.html.md b/website/docs/configuration/functions/keys.html.md
new file mode 100644
index 000000000..1d95e1ee3
--- /dev/null
+++ b/website/docs/configuration/functions/keys.html.md
@@ -0,0 +1,29 @@
+---
+layout: "functions"
+page_title: "keys function"
+sidebar_current: "docs-funcs-collection-keys"
+description: |-
+  The keys function returns a list of the keys in a given map.
+---
+
+# `keys` Function
+
+`keys` takes a map and returns a list containing the keys from that map.
+
+The keys are returned in lexicographical order, ensuring that the result will
+be identical as long as the keys in the map don't change.
+
+## Examples
+
+```
+> keys({a=1, c=2, d=3})
+[
+  "a",
+  "c",
+  "d",
+]
+```
+
+## Related Functions
+
+* [`values`](./values.html) returns a list of the _values_ from a map.
diff --git a/website/docs/configuration/functions/lookup.html.md b/website/docs/configuration/functions/lookup.html.md
new file mode 100644
index 000000000..5c2488303
--- /dev/null
+++ b/website/docs/configuration/functions/lookup.html.md
@@ -0,0 +1,33 @@
+---
+layout: "functions"
+page_title: "lookup function"
+sidebar_current: "docs-funcs-collection-lookup"
+description: |-
+  The lookup function retrieves an element value from a map given its key.
+---
+
+# `lookup` Function
+
+`lookup` retrieves the value of a single element from a map, given its key.
+If the given key does not exist, a the given default value is returned instead.
+
+```
+lookup(map, key, default)
+```
+
+-> For historical reasons, the `default` parameter is actually optional. However,
+omitting `default` is deprecated since v0.7 because that would then be
+equivalent to the native index syntax, `map[key]`.
+
+## Examples
+
+```
+> lookup({a="ay", b="bee"}, "a", "what?")
+ay
+> lookup({a="ay", b="bee"}, "c", "what?")
+what?
+```
+
+## Related Functions
+
+* [`element`](./element.html) retrieves a value from a _list_ given its _index_.
diff --git a/website/docs/configuration/functions/values.html.md b/website/docs/configuration/functions/values.html.md
new file mode 100644
index 000000000..6c8c837a0
--- /dev/null
+++ b/website/docs/configuration/functions/values.html.md
@@ -0,0 +1,31 @@
+---
+layout: "functions"
+page_title: "values function"
+sidebar_current: "docs-funcs-collection-values"
+description: |-
+  The values function returns a list of the element values in a given map.
+---
+
+# `values` Function
+
+`values` takes a map and returns a list containing the values of the elements
+in that map.
+
+The values are returned in lexicographical order by their corresponding _keys_,
+so the values will be returned in the same order as their keys would be
+returned from [`keys`](./keys.html).
+
+## Examples
+
+```
+> values({a=3, c=2, d=1})
+[
+  3,
+  2,
+  1,
+]
+```
+
+## Related Functions
+
+* [`keys`](./keys.html) returns a list of the _keys_ from a map.
diff --git a/website/layouts/functions.erb b/website/layouts/functions.erb
index 13470416d..b137b5542 100644
--- a/website/layouts/functions.erb
+++ b/website/layouts/functions.erb
@@ -143,6 +143,10 @@
                 <a href="/docs/configuration/functions/index.html">index</a>
               </li>
 
+              <li<%= sidebar_current("docs-funcs-collection-keys") %>>
+                <a href="/docs/configuration/functions/keys.html">keys</a>
+              </li>
+
               <li<%= sidebar_current("docs-funcs-collection-length") %>>
                 <a href="/docs/configuration/functions/length.html">length</a>
               </li>
@@ -151,6 +155,10 @@
                 <a href="/docs/configuration/functions/list.html">list</a>
               </li>
 
+              <li<%= sidebar_current("docs-funcs-collection-lookup") %>>
+                <a href="/docs/configuration/functions/lookup.html">lookup</a>
+              </li>
+
               <li<%= sidebar_current("docs-funcs-collection-map") %>>
                 <a href="/docs/configuration/functions/map.html">map</a>
               </li>
@@ -175,6 +183,10 @@
                 <a href="/docs/configuration/functions/transpose.html">transpose</a>
               </li>
 
+              <li<%= sidebar_current("docs-funcs-collection-values") %>>
+                <a href="/docs/configuration/functions/values.html">values</a>
+              </li>
+
               <li<%= sidebar_current("docs-funcs-collection-zipmap") %>>
                 <a href="/docs/configuration/functions/zipmap.html">zipmap</a>
               </li>