WIP

source/documentation/modules/map.html.md.erb

@@ -4,21 +4,63 @@ title: sass:map
 
 <%= partial '../snippets/built-in-module-status' %>
 
-<% function 'map.get($map, $key)', 'map-get($map, $key)' do %>
-  Returns the value in `$map` associated with `$key`.
+  <% fun_fact do %>
+    Sass libraries and design systems tend to share and override configurations
+    that are represented as nested maps (maps that contain maps that contain
+    maps).
+
+    To help you work with nested maps, some map functions support deep
+    operations. For example, if you pass multiple keys to `map.get()`, it will
+    follow those keys to find the desired nested map:
+
+    <% example(autogen_css: false) do %>
+      $config: (a: (b: (c: d)));
+      @debug map.get($config, a, b, c)); // d
+    <% end %>
+  <% end %>
 
-  If `$map` doesn't have a value associated with `$key`, returns [`null`][].
+<% function 'map.get($map, $keys...)', 'map-get($map, $keys...)' do %>
+  If `$keys` has one key, returns the value in `$map` associated with the key.
 
-  [`null`]: ../values/null
+  If `$map` doesn't have a value associated with the key, returns [`null`][].
 
   <%= partial 'code-snippets/example-map-get' %>
-<% end %>
 
+  If `$keys` contains more than one key, the map targeted for searching is
+  nested within `$map`. Excluding the last key, the multiple keys in `$keys`
+  form a path of nested maps that leads to the targeted map.
+
+  Returns the value in the targeted map associated with the last key in `$keys`.
+
+  Returns [`null`][] if the map does not have a value associated with the key,
+  or if any key in `$keys` references a value that is not a map.
+
+  <% example(autogen_css: false) do %>
+    $fonts: (
+      "serif": ("Georgia": ("weights": 400)),
+      "monospace": "Monaco"
+    );
+
+    @debug map.get($fonts, "serif", "Georgia", "weights"); // 400
+    @debug map.get($fonts, "serif", "Georgia", "colors"); // null
+    @debug map.get($fonts, "monospace", "Monaco"); // null
+    ===
+    $fonts: ("serif": ("Georgia": ("weights": 400)), "monospace": "Monaco")
+
+    @debug map.get($fonts, "serif", "Georgia", "weights") // 400
+    @debug map.get($fonts, "serif", "Georgia", "colors") // null
+    @debug map.get($fonts, "monospace", "Monaco") // null
+  <% end %>
+
+  [`null`]: ../values/null
 
-<% function 'map.has-key($map, $key)',
-            'map-has-key($map, $key)',
+<% end %>
+
+<% function 'map.has-key($map, $keys...)',
+            'map-has-key($map, $keys...)',
             returns: 'boolean' do %>
-  Returns whether `$map` contains a value associated with `$key`.
+  If `$keys` has one key, returns whether `$map` contains a value associated
+  with the key.
 
   <% example(autogen_css: false) do %>
     $font-weights: ("regular": 400, "medium": 500, "bold": 700);
@@ -31,6 +73,31 @@ title: sass:map
     @debug map.has-key($font-weights, "regular")  // true
     @debug map.has-key($font-weights, "bolder")  // false
   <% end %>
+
+  If `$keys` contains more than one key, the map targeted for searching is
+  nested within `$map`. Excluding the last key, the multiple keys in `$keys`
+  form a path of nested maps that leads to the targeted map.
+
+  Returns true if the targeted map contains a value associated with the last key
+  in `$keys`. Returns false if it does not, or if any key in `$keys` references
+  a value that is not a map.
+
+  <% example(autogen_css: false) do %>
+    $fonts: (
+      "serif": ("Georgia": ("weights": 400)),
+      "monospace": "Monaco"
+    );
+
+    @debug map.has-key($fonts, "serif", "Georgia", "weights"); // true
+    @debug map.has-key($fonts, "serif", "Georgia", "colors"); // false
+    @debug map.has-key($fonts, "monospace", "Monaco"); // false
+    ===
+    $fonts: ("serif": ("Georgia": ("weights": 400)), "monospace": "Monaco")
+
+    @debug map.has-key($fonts, "serif", "Georgia", "weights") // true
+    @debug map.has-key($fonts, "serif", "Georgia", "colors") // false
+    @debug map.has-key($fonts, "monospace", "Monaco") // false
+  <% end %>
 <% end %>
 
 
@@ -49,8 +116,53 @@ title: sass:map
 <% end %>
 
 
+<% function 'map.set($map, $key, $value)',
+            'map.set($map, $keys..., $key, $value)',
+            returns: 'map' do %>
+  If only `$key` is passed, returns a copy of `$map` with the value at `$key`
+  set to `$value`.
+
+  <% example(autogen_css: false) do %>
+    $font-weights: ("regular": 300);
+
+    @debug map.set($font-weights, "regular", 400); // ("regular": 400)
+    ===
+    $font-weights: ("regular": 300)
+
+    @debug map.set($font-weights, "regular", 400) // ("regular": 400)
+  <% end %>
+
+  ---
+
+  If `$keys` are passed in addition to `$key`, the map targeted for updating is
+  nested within `$map`. The multiple keys in `$keys` form a path of nested maps
+  that leads to the targeted map.
+
+  Returns a copy of `$map` with the targeted map's value at `$key` set to
+  `$value`. If any key in `$keys` references a value that is not a map, that
+  value is replaced with a map containing the key.
+
+  <% example(autogen_css: false) do %>
+    $fonts: (
+      "serif": ("Georgia": ("weights": 300)),
+      "monospace": "Monaco"
+    );
+
+    @debug map.set($fonts, "serif", "Georgia", "weights", 400); // ("serif": ("Georgia": ("weights": 400)))
+    @debug map.set($fonts, "monospace", "Monaco", "weights", 400); // ("monospace": ("Monaco": ("weights": 400)))
+    ===
+    $fonts: ("serif": ("Georgia": ("weights": 400)), "monospace": "Monaco")
+
+    @debug map.set($fonts, "serif", "Georgia", "weights", 400) // ("serif": ("Georgia": ("weights": 400)))
+    @debug map.set($fonts, "monospace", "Monaco", "weights", 400) // ("monospace": ("Monaco": ("weights": 400)))
+  <% end %>
+<% end %>
+
+
 <% function 'map.merge($map1, $map2)',
             'map-merge($map1, $map2)',
+            'map.merge($map1, $keys..., $map2)',
+            'map-merge($map1, $keys..., $map2)',
             returns: 'map' do %>
   Returns a new map with all the keys and values from both `$map1` and `$map2`.