From 34e20d507fcac4219e1316de5c34d9be356f2a51 Mon Sep 17 00:00:00 2001 From: awjin Date: Tue, 6 Oct 2020 20:41:54 -0500 Subject: [PATCH 1/5] Update docs. --- source/documentation/modules/map.html.md.erb | 396 ++++++++++++++++--- source/documentation/values/maps.html.md.erb | 71 ++-- 2 files changed, 382 insertions(+), 85 deletions(-) diff --git a/source/documentation/modules/map.html.md.erb b/source/documentation/modules/map.html.md.erb index d40c921bd..0c4215942 100644 --- a/source/documentation/modules/map.html.md.erb +++ b/source/documentation/modules/map.html.md.erb @@ -4,21 +4,57 @@ 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`][]. - [`null`]: ../values/null +<% function 'map.keys($map)', 'map-keys($map)', returns: 'list' do %> + Returns a comma-separated list of all the keys in `$map`. - <%= partial 'code-snippets/example-map-get' %> + <% example(autogen_css: false) do %> + $font-weights: ("regular": 400, "medium": 500, "bold": 700); + + @debug map.keys($font-weights); // "regular", "medium", "bold" + === + $font-weights: ("regular": 400, "medium": 500, "bold": 700) + + @debug map.keys($font-weights) // "regular", "medium", "bold" + <% end %> <% end %> -<% function 'map.has-key($map, $key)', - 'map-has-key($map, $key)', +<% function 'map.values($map)', 'map-values($map)', returns: 'list' do %> + Returns a comma-separated list of all the values in `$map`. + + <% example(autogen_css: false) do %> + $font-weights: ("regular": 400, "medium": 500, "bold": 700); + + @debug map.values($font-weights); // 400, 500, 700 + === + $font-weights: ("regular": 400, "medium": 500, "bold": 700) + + @debug map.values($font-weights) // 400, 500, 700 + <% end %> +<% end %> + + +<% function 'map.has-key($map, $key, $keys...)', + 'map-has-key($map, $key, $keys...)', returns: 'boolean' do %> - Returns whether `$map` contains a value associated with `$key`. + If `$keys` is empty, returns whether `$map` contains a value associated with + `$key`. <% example(autogen_css: false) do %> $font-weights: ("regular": 400, "medium": 500, "bold": 700); @@ -28,78 +64,297 @@ title: sass:map === $font-weights: ("regular": 400, "medium": 500, "bold": 700) - @debug map.has-key($font-weights, "regular") // true - @debug map.has-key($font-weights, "bolder") // false + @debug map.has-key($font-weights, "regular") // true + @debug map.has-key($font-weights, "bolder") // false + <% end %> + + If `$keys` is not empty, the map targeted for searching is nested within + `$map`. From left to right, including `$key` and excluding the last key in + `$keys`, these 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: ( + "Helvetica": ( + "weights": ( + "regular": 400, + "medium": 500, + "bold": 700 + ) + ) + ); + + @debug map.has-key($fonts, "Helvetica", "weights", "regular"); // true + @debug map.has-key($fonts, "Helvetica", "colors"); // false + === + $fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700))) + + @debug map.has-key($fonts, "Helvetica", "weights", "regular") // true + @debug map.has-key($fonts, "Helvetica", "colors") // false <% end %> <% end %> -<% function 'map.keys($map)', 'map-keys($map)', returns: 'list' do %> - Returns a comma-separated list of all the keys in `$map`. +<% function 'map.get($map, $key, $keys...)', + 'map-get($map, $key, $keys...)' do %> + If `$keys` is empty, returns the value in `$map` associated with `$key`. + + If `$map` doesn't have a value associated with `$key`, returns [`null`][]. + + <%= partial 'code-snippets/example-map-get' %> + + If `$keys` is not empty, the map targeted for searching is nested within + `$map`. From left to right, including `$key` and excluding the last key in + `$keys`, these 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: ( + "Helvetica": ( + "weights": ( + "regular": 400, + "medium": 500, + "bold": 700 + ) + ) + ); + + @debug map.get($fonts, "Helvetica", "weights", "regular"); // 400 + @debug map.get($fonts, "Helvetica", "colors"); // null + === + $fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700))) + + @debug map.get($fonts, "Helvetica", "weights", "regular") // 400 + @debug map.get($fonts, "Helvetica", "colors") // null + <% end %> + + [`null`]: ../values/null +<% end %> + + +<% function 'map.set($map, $key, $value)', + 'map.set($map, $keys..., $key, $value)', + returns: 'map' do %> + <% heads_up do %> + In practice, the actual arguments to `map.set($map, $keys..., $key, $value)` + are passed as `map.set($map, $args). They are described here as `$map, + $keys..., $key, $value` for explanation purposes only. + <% end %> + + If `$keys` are not passed, returns a copy of `$map` with the value at `$key` + set to `$value`. <% example(autogen_css: false) do %> $font-weights: ("regular": 400, "medium": 500, "bold": 700); - @debug map.keys($font-weights); // "regular", "medium", "bold" + @debug map.set($font-weights, "regular", 300); + // ("regular": 300, "medium": 500, "bold": 700) === $font-weights: ("regular": 400, "medium": 500, "bold": 700) - @debug map.keys($font-weights) // "regular", "medium", "bold" + @debug map.set($font-weights, "regular", 300) + // ("regular": 300, "medium": 500, "bold": 700) + <% 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: ( + "Helvetica": ( + "weights": ( + "regular": 400, + "medium": 500, + "bold": 700 + ) + ) + ); + + @debug map.set($fonts, "Helvetica", "weights", "regular", 300); + // ( + // "Helvetica": ( + // "weights": ( + // "regular": 300, + // "medium": 500, + // "bold": 700 + // ) + // ) + // ) + === + $fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700))) + + @debug map.set($fonts, "Helvetica", "weights", "regular", 300) + // ( + // "Helvetica": ( + // "weights": ( + // "regular": 300, + // "medium": 500, + // "bold": 700 + // ) + // ) + // ) <% 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`. + <% heads_up do %> + In practice, the actual arguments to `map.merge($map1, $keys..., $map2)` + are passed as `map.set($map1, $args). They are described here as `$map1, + $keys..., $map2` for explanation purposes only. + <% end %> - This can also be used to add a new value or overrwrite a value in `$map1`, by - passing a single key/value pair as `$map2`. + If no `$keys` are passed, returns a new map with all the keys and values from + both `$map1` and `$map2`. - If both `$map1` and `$map2` have the same key, `$map2`'s value takes precedence. + If both `$map1` and `$map2` have the same key, `$map2`'s value takes + precedence. - All keys in the returned map that also appear in `$map1` have the same order as - in `$map1`. New keys from `$map2` appear at the end of the map. + All keys in the returned map that also appear in `$map1` have the same order + as in `$map1`. New keys from `$map2` appear at the end of the map. <% example(autogen_css: false) do %> $light-weights: ("lightest": 100, "light": 300); $heavy-weights: ("medium": 500, "bold": 700); @debug map.merge($light-weights, $heavy-weights); - // ( - // "lightest": 100, - // "light": 300, - // "medium": 500, - // "bold": 700 - // ) - - // map.merge() can be used to add a single key/value pair to a map. - @debug map.merge($light-weights, ("lighter": 200)); - // ("lightest": 100, "light": 300, "lighter": 200) - - // It can also be used to overwrite a value in a map. - @debug map.merge($light-weights, ("light": 200)); - // ("lightest": 100, "light": 200) + // ("lightest": 100, "light": 300, "medium": 500, "bold": 700) === $light-weights: ("lightest": 100, "light": 300) $heavy-weights: ("medium": 500, "bold": 700) @debug map.merge($light-weights, $heavy-weights) + // ("lightest": 100, "light": 300, "medium": 500, "bold": 700) + <% end %> + + --- + + If `$keys` are passed, the map targeted for merging is nested within `$map1`. + The multiple keys in `$keys` form a path of nested maps that leads to the + targeted map. + + Returns a copy of `$map1` where the targeted map is replaced by a new map that + contains all the keys and values from both the targeted map and `$map2`. 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: ( + "Helvetica": ( + "weights": ( + "lightest": 100, + "light": 300 + ) + ) + ); + $heavy-weights: ("medium": 500, "bold": 700); + + @debug map.merge($fonts, "Helvetica", "weights", $heavy-weights); // ( - // "lightest": 100, - // "light": 300, - // "medium": 500, - // "bold": 700 + // "Helvetica": ( + // "weights": ( + // "lightest": 100, + // "light": 300, + // "medium": 500, + // "bold": 700 + // ) + // ) // ) + === + $fonts: ("Helvetica": ("weights": ("lightest": 100, "light": 300))) + $heavy-weights: ("medium": 500, "bold": 700) - // map.merge() can be used to add a single key/value pair to a map. - @debug map.merge($light-weights, ("lighter": 200)) - // ("lightest": 100, "light": 300, "lighter": 200) + @debug map.merge($fonts, "Helvetica", "weights", $heavy-weights) + // ( + // "Helvetica": ( + // "weights": ( + // "lightest": 100, + // "light": 300, + // "medium": 500, + // "bold": 700 + // ) + // ) + // ) + <% end %> +<% end %> - // It can also be used to overwrite a value in a map. - @debug map.merge($light-weights, ("light": 200)) - // ("lightest": 100, "light": 200) + +<% function 'map.deep-merge($map1, $map2)', returns: 'map' do %> + Identical to [`map.merge()`][], except that nested map values are *also* + recursively merged. + + [`map.merge()`][#merge] + + <% example(autogen_css: false) do %> + $helvetica-light: ( + "weights": ( + "lightest": 100, + "light": 300 + ) + ); + $helvetica-heavy: ( + "weights": ( + "medium": 500, + "bold": 700 + ) + ); + + @debug map.deep-merge($helvetica-light, $helvetica-heavy); + // ( + // "weights": ( + // "lightest": 100, + // "light": 300, + // "medium": 500, + // "bold": 700 + // ) + // ) + @debug map.merge($helvetica-light, $helvetica-heavy); + // ( + // "weights": ( + // "medium: 500, + // "bold": 700 + // ) + // ) + === + $helvetica-light: ("weights": ("lightest": 100, "light": 300)) + $helvetica-heavy: ("weights": ("medium": 500, "bold": 700)) + + @debug map.deep-merge($helvetica-light, $helvetica-heavy) + // ( + // "weights": ( + // "lightest": 100, + // "light": 300, + // "medium": 500, + // "bold": 700 + // ) + // ) + @debug map.merge($helvetica-light, $helvetica-heavy); + // ( + // "weights": ( + // "medium: 500, + // "bold": 700 + // ) + // ) <% end %> <% end %> @@ -129,16 +384,61 @@ title: sass:map <% end %> -<% function 'map.values($map)', 'map-values($map)', returns: 'list' do %> - Returns a comma-separated list of all the values in `$map`. +<% function 'map.deep-remove($map, $key, $keys...)', + returns: 'map' do %> + If `$keys` is empty, returns a copy of `$map` without a value associated with + `$key`. <% example(autogen_css: false) do %> $font-weights: ("regular": 400, "medium": 500, "bold": 700); - @debug map.values($font-weights); // 400, 500, 700 + @debug map.deep-remove($font-weights, "regular"); + // ("medium": 500, "bold": 700) === $font-weights: ("regular": 400, "medium": 500, "bold": 700) - @debug map.values($font-weights) // 400, 500, 700 + @debug map.deep-remove($font-weights, "regular") + // ("medium": 500, "bold": 700) + <% end %> + + If `$keys` is not empty, the map targeted for updating is nested within + `$map`. From left to right, including `$key` and excluding the last key in + `$keys`, these keys form a path of nested maps that leads to the targeted map. + + Returns a copy of `$map` where the targeted map does not have a value + associated with the last key in `$keys`. + + <% example(autogen_css: false) do %> + $fonts: ( + "Helvetica": ( + "weights": ( + "regular": 400, + "medium": 500, + "bold": 700 + ) + ) + ); + + @debug map.deep-remove($fonts, "Helvetica", "weights", "regular"); + // ( + // "Helvetica": ( + // "weights: ( + // "medium": 500, + // "bold": 700 + // ) + // ) + // ) + === + $fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700))) + + @debug map.deep-remove($fonts, "Helvetica", "weights", "regular") + // ( + // "Helvetica": ( + // "weights: ( + // "medium": 500, + // "bold": 700 + // ) + // ) + // ) <% end %> <% end %> diff --git a/source/documentation/values/maps.html.md.erb b/source/documentation/values/maps.html.md.erb index 0b6a3ac9f..7d089f941 100644 --- a/source/documentation/values/maps.html.md.erb +++ b/source/documentation/values/maps.html.md.erb @@ -68,55 +68,52 @@ easily be accessed in the block. ### Add to a Map It's also useful to add new pairs to a map, or to replace the value for an -existing key. The [`map.merge($map1, $map2)` function][] does this: it returns a -new map that contains all the key/value pairs in *both* arguments. +existing key. The [`map.set($map, $key, $value)` function][] does this: it +returns a copy of `$map` with the value at `$key` set to `$value`. -[`map.merge($map1, $map2)` function]: ../modules/map#merge +[`map.set($map, $key, $value)` function]: ../modules/map#set <% example(autogen_css: false) do %> @use "sass:map"; - $light-weights: ("lightest": 100, "light": 300); - $heavy-weights: ("medium": 500, "bold": 700); + $font-weights: ("regular": 400, "medium": 500, "bold": 700); - @debug map.merge($light-weights, $heavy-weights); - // ( - // "lightest": 100, - // "light": 300, - // "medium": 500, - // "bold": 700 - // ) + @debug map.set($font-weights, "extra-bold", 900); + // ("regular": 400, "medium": 500, "bold": 700, "extra-bold": 900) + @debug map.set($font-weights, "bold", 900); + // ("regular": 400, "medium": 500, "bold": 900) === @use "sass:map" - $light-weights: ("lightest": 100, "light": 300) - $heavy-weights: ("medium": 500, "bold": 700) + $font-weights: ("regular": 400, "medium": 500, "bold": 700) - @debug map.merge($light-weights, $heavy-weights) - // ( - // "lightest": 100, - // "light": 300, - // "medium": 500, - // "bold": 700 - // ) + @debug map.set($font-weights, "extra-bold": 900) + // ("regular": 400, "medium": 500, "bold": 700, "extra-bold": 900) + @debug map.set($font-weights, "bold", 900) + // ("regular": 400, "medium": 500, "bold": 900) <% end %> -`map.merge()` is often used with an inline map to add a single key/value pair. +Instead of setting values one-by-one, you can also merge two existing maps using +[`map.merge($map1, $map2)`][]. + +[`map.merge($map1, $map2)` function]: ../modules/map#merge <% example(autogen_css: false) do %> @use "sass:map"; - $font-weights: ("regular": 400, "medium": 500, "bold": 700); + $light-weights: ("lightest": 100, "light": 300); + $heavy-weights: ("medium": 500, "bold": 700); - @debug map.merge($font-weights, ("extra-bold": 900)); - // ("regular": 400, "medium": 500, "bold": 700, "extra-bold": 900) + @debug map.merge($light-weights, $heavy-weights); + // ("lightest": 100, "light": 300, "medium": 500, "bold": 700) === @use "sass:map" - $font-weights: ("regular": 400, "medium": 500, "bold": 700) + $light-weights: ("lightest": 100, "light": 300) + $heavy-weights: ("medium": 500, "bold": 700) - @debug map.merge($font-weights, ("extra-bold": 900)) - // ("regular": 400, "medium": 500, "bold": 700, "extra-bold": 900) + @debug map.merge($light-weights, $heavy-weights) + // ("lightest": 100, "light": 300, "medium": 500, "bold": 700) <% end %> If both maps have the same keys, the second map's values are used in the map @@ -125,21 +122,21 @@ that gets returned. <% example(autogen_css: false) do %> @use "sass:map"; - $font-weights: ("regular": 400, "medium": 500, "bold": 700); + $weights: ("light": 300, "medium": 500); - @debug map.merge($font-weights, ("medium": 600)); - // ("regular": 400, "medium": 600, "bold": 700) + @debug map.merge($weights, ("medium": 700)); + // ("light": 300, "medium": 700) === - @use "sass:map" + @use "sass:map"; - $font-weights: ("regular": 400, "medium": 500, "bold": 700) + $weights: ("light": 300, "medium": 500) - @debug map.merge($font-weights, ("medium": 600)) - // ("regular": 400, "medium": 600, "bold": 700) + @debug map.merge($weights, ("medium": 700)) + // ("light": 300, "medium": 700) <% end %> -Note that because Sass maps are [immutable][], `map.merge()` doesn't modify the -original list. +Note that because Sass maps are [immutable][], `map.set()` and `map.merge()` do +not modify the original list. [immutable]: #immutability From 871f2707818f02f9f5f7eca10fd1aee0dc53f23e Mon Sep 17 00:00:00 2001 From: awjin Date: Tue, 6 Oct 2020 21:08:59 -0500 Subject: [PATCH 2/5] Add missing .sass syntax --- source/documentation/modules/map.html.md.erb | 29 +++++++++++--------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/source/documentation/modules/map.html.md.erb b/source/documentation/modules/map.html.md.erb index 0c4215942..c8b622e6b 100644 --- a/source/documentation/modules/map.html.md.erb +++ b/source/documentation/modules/map.html.md.erb @@ -4,20 +4,23 @@ title: sass:map <%= partial '../snippets/built-in-module-status' %> - <% 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 %> +<% 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 + === + $config: (a: (b: (c: d))) + @debug map.get($config, a, b, c)) // d <% end %> +<% end %> <% function 'map.keys($map)', 'map-keys($map)', returns: 'list' do %> From e551214491dca9f85648b84f9865f0d2f547b902 Mon Sep 17 00:00:00 2001 From: awjin Date: Wed, 7 Oct 2020 15:17:55 -0500 Subject: [PATCH 3/5] Alphabetize functions. --- source/documentation/modules/map.html.md.erb | 312 +++++++++---------- 1 file changed, 156 insertions(+), 156 deletions(-) diff --git a/source/documentation/modules/map.html.md.erb b/source/documentation/modules/map.html.md.erb index c8b622e6b..a52928f33 100644 --- a/source/documentation/modules/map.html.md.erb +++ b/source/documentation/modules/map.html.md.erb @@ -23,63 +23,89 @@ title: sass:map <% end %> -<% function 'map.keys($map)', 'map-keys($map)', returns: 'list' do %> - Returns a comma-separated list of all the keys in `$map`. - - <% example(autogen_css: false) do %> - $font-weights: ("regular": 400, "medium": 500, "bold": 700); - - @debug map.keys($font-weights); // "regular", "medium", "bold" - === - $font-weights: ("regular": 400, "medium": 500, "bold": 700) - - @debug map.keys($font-weights) // "regular", "medium", "bold" - <% end %> -<% end %> - +<% function 'map.deep-merge($map1, $map2)', returns: 'map' do %> + Identical to [`map.merge()`][], except that nested map values are *also* + recursively merged. -<% function 'map.values($map)', 'map-values($map)', returns: 'list' do %> - Returns a comma-separated list of all the values in `$map`. + [`map.merge()`][#merge] <% example(autogen_css: false) do %> - $font-weights: ("regular": 400, "medium": 500, "bold": 700); + $helvetica-light: ( + "weights": ( + "lightest": 100, + "light": 300 + ) + ); + $helvetica-heavy: ( + "weights": ( + "medium": 500, + "bold": 700 + ) + ); - @debug map.values($font-weights); // 400, 500, 700 + @debug map.deep-merge($helvetica-light, $helvetica-heavy); + // ( + // "weights": ( + // "lightest": 100, + // "light": 300, + // "medium": 500, + // "bold": 700 + // ) + // ) + @debug map.merge($helvetica-light, $helvetica-heavy); + // ( + // "weights": ( + // "medium: 500, + // "bold": 700 + // ) + // ) === - $font-weights: ("regular": 400, "medium": 500, "bold": 700) + $helvetica-light: ("weights": ("lightest": 100, "light": 300)) + $helvetica-heavy: ("weights": ("medium": 500, "bold": 700)) - @debug map.values($font-weights) // 400, 500, 700 + @debug map.deep-merge($helvetica-light, $helvetica-heavy) + // ( + // "weights": ( + // "lightest": 100, + // "light": 300, + // "medium": 500, + // "bold": 700 + // ) + // ) + @debug map.merge($helvetica-light, $helvetica-heavy); + // ( + // "weights": ( + // "medium: 500, + // "bold": 700 + // ) + // ) <% end %> <% end %> -<% function 'map.has-key($map, $key, $keys...)', - 'map-has-key($map, $key, $keys...)', - returns: 'boolean' do %> - If `$keys` is empty, returns whether `$map` contains a value associated with +<% function 'map.deep-remove($map, $key, $keys...)', + returns: 'map' do %> + If `$keys` is empty, returns a copy of `$map` without a value associated with `$key`. <% example(autogen_css: false) do %> $font-weights: ("regular": 400, "medium": 500, "bold": 700); - @debug map.has-key($font-weights, "regular"); // true - @debug map.has-key($font-weights, "bolder"); // false + @debug map.deep-remove($font-weights, "regular"); + // ("medium": 500, "bold": 700) === $font-weights: ("regular": 400, "medium": 500, "bold": 700) - @debug map.has-key($font-weights, "regular") // true - @debug map.has-key($font-weights, "bolder") // false + @debug map.deep-remove($font-weights, "regular") + // ("medium": 500, "bold": 700) <% end %> - If `$keys` is not empty, the map targeted for searching is nested within + If `$keys` is not empty, the map targeted for updating is nested within `$map`. From left to right, including `$key` and excluding the last key in `$keys`, these 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. + Returns a copy of `$map` where the targeted map does not have a value + associated with the last key in `$keys`. <% example(autogen_css: false) do %> $fonts: ( @@ -92,13 +118,27 @@ title: sass:map ) ); - @debug map.has-key($fonts, "Helvetica", "weights", "regular"); // true - @debug map.has-key($fonts, "Helvetica", "colors"); // false + @debug map.deep-remove($fonts, "Helvetica", "weights", "regular"); + // ( + // "Helvetica": ( + // "weights: ( + // "medium": 500, + // "bold": 700 + // ) + // ) + // ) === $fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700))) - @debug map.has-key($fonts, "Helvetica", "weights", "regular") // true - @debug map.has-key($fonts, "Helvetica", "colors") // false + @debug map.deep-remove($fonts, "Helvetica", "weights", "regular") + // ( + // "Helvetica": ( + // "weights: ( + // "medium": 500, + // "bold": 700 + // ) + // ) + // ) <% end %> <% end %> @@ -144,39 +184,33 @@ title: sass:map <% end %> -<% function 'map.set($map, $key, $value)', - 'map.set($map, $keys..., $key, $value)', - returns: 'map' do %> - <% heads_up do %> - In practice, the actual arguments to `map.set($map, $keys..., $key, $value)` - are passed as `map.set($map, $args). They are described here as `$map, - $keys..., $key, $value` for explanation purposes only. - <% end %> - - If `$keys` are not passed, returns a copy of `$map` with the value at `$key` - set to `$value`. +<% function 'map.has-key($map, $key, $keys...)', + 'map-has-key($map, $key, $keys...)', + returns: 'boolean' do %> + If `$keys` is empty, returns whether `$map` contains a value associated with + `$key`. <% example(autogen_css: false) do %> $font-weights: ("regular": 400, "medium": 500, "bold": 700); - @debug map.set($font-weights, "regular", 300); - // ("regular": 300, "medium": 500, "bold": 700) + @debug map.has-key($font-weights, "regular"); // true + @debug map.has-key($font-weights, "bolder"); // false === $font-weights: ("regular": 400, "medium": 500, "bold": 700) - @debug map.set($font-weights, "regular", 300) - // ("regular": 300, "medium": 500, "bold": 700) + @debug map.has-key($font-weights, "regular") // true + @debug map.has-key($font-weights, "bolder") // false <% end %> - --- + If `$keys` is not empty, the map targeted for searching is nested within + `$map`. From left to right, including `$key` and excluding the last key in + `$keys`, these keys form a path of nested maps that leads to the targeted map. - 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 true if the targeted map contains a value associated with the last key + in `$keys`. - 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. + 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: ( @@ -189,29 +223,28 @@ title: sass:map ) ); - @debug map.set($fonts, "Helvetica", "weights", "regular", 300); - // ( - // "Helvetica": ( - // "weights": ( - // "regular": 300, - // "medium": 500, - // "bold": 700 - // ) - // ) - // ) + @debug map.has-key($fonts, "Helvetica", "weights", "regular"); // true + @debug map.has-key($fonts, "Helvetica", "colors"); // false === $fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700))) - @debug map.set($fonts, "Helvetica", "weights", "regular", 300) - // ( - // "Helvetica": ( - // "weights": ( - // "regular": 300, - // "medium": 500, - // "bold": 700 - // ) - // ) - // ) + @debug map.has-key($fonts, "Helvetica", "weights", "regular") // true + @debug map.has-key($fonts, "Helvetica", "colors") // false + <% end %> +<% end %> + + +<% function 'map.keys($map)', 'map-keys($map)', returns: 'list' do %> + Returns a comma-separated list of all the keys in `$map`. + + <% example(autogen_css: false) do %> + $font-weights: ("regular": 400, "medium": 500, "bold": 700); + + @debug map.keys($font-weights); // "regular", "medium", "bold" + === + $font-weights: ("regular": 400, "medium": 500, "bold": 700) + + @debug map.keys($font-weights) // "regular", "medium", "bold" <% end %> <% end %> @@ -302,66 +335,6 @@ title: sass:map <% end %> -<% function 'map.deep-merge($map1, $map2)', returns: 'map' do %> - Identical to [`map.merge()`][], except that nested map values are *also* - recursively merged. - - [`map.merge()`][#merge] - - <% example(autogen_css: false) do %> - $helvetica-light: ( - "weights": ( - "lightest": 100, - "light": 300 - ) - ); - $helvetica-heavy: ( - "weights": ( - "medium": 500, - "bold": 700 - ) - ); - - @debug map.deep-merge($helvetica-light, $helvetica-heavy); - // ( - // "weights": ( - // "lightest": 100, - // "light": 300, - // "medium": 500, - // "bold": 700 - // ) - // ) - @debug map.merge($helvetica-light, $helvetica-heavy); - // ( - // "weights": ( - // "medium: 500, - // "bold": 700 - // ) - // ) - === - $helvetica-light: ("weights": ("lightest": 100, "light": 300)) - $helvetica-heavy: ("weights": ("medium": 500, "bold": 700)) - - @debug map.deep-merge($helvetica-light, $helvetica-heavy) - // ( - // "weights": ( - // "lightest": 100, - // "light": 300, - // "medium": 500, - // "bold": 700 - // ) - // ) - @debug map.merge($helvetica-light, $helvetica-heavy); - // ( - // "weights": ( - // "medium: 500, - // "bold": 700 - // ) - // ) - <% end %> -<% end %> - - <% function 'map.remove($map, $keys...)', 'map-remove($map, $keys...)', returns: 'map' do %> @@ -387,29 +360,39 @@ title: sass:map <% end %> -<% function 'map.deep-remove($map, $key, $keys...)', +<% function 'map.set($map, $key, $value)', + 'map.set($map, $keys..., $key, $value)', returns: 'map' do %> - If `$keys` is empty, returns a copy of `$map` without a value associated with - `$key`. + <% heads_up do %> + In practice, the actual arguments to `map.set($map, $keys..., $key, $value)` + are passed as `map.set($map, $args). They are described here as `$map, + $keys..., $key, $value` for explanation purposes only. + <% end %> + + If `$keys` are not passed, returns a copy of `$map` with the value at `$key` + set to `$value`. <% example(autogen_css: false) do %> $font-weights: ("regular": 400, "medium": 500, "bold": 700); - @debug map.deep-remove($font-weights, "regular"); - // ("medium": 500, "bold": 700) + @debug map.set($font-weights, "regular", 300); + // ("regular": 300, "medium": 500, "bold": 700) === $font-weights: ("regular": 400, "medium": 500, "bold": 700) - @debug map.deep-remove($font-weights, "regular") - // ("medium": 500, "bold": 700) + @debug map.set($font-weights, "regular", 300) + // ("regular": 300, "medium": 500, "bold": 700) <% end %> - If `$keys` is not empty, the map targeted for updating is nested within - `$map`. From left to right, including `$key` and excluding the last key in - `$keys`, these keys form a path of nested maps that leads to the targeted map. + --- - Returns a copy of `$map` where the targeted map does not have a value - associated with the last key in `$keys`. + 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: ( @@ -422,10 +405,11 @@ title: sass:map ) ); - @debug map.deep-remove($fonts, "Helvetica", "weights", "regular"); + @debug map.set($fonts, "Helvetica", "weights", "regular", 300); // ( // "Helvetica": ( - // "weights: ( + // "weights": ( + // "regular": 300, // "medium": 500, // "bold": 700 // ) @@ -434,10 +418,11 @@ title: sass:map === $fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700))) - @debug map.deep-remove($fonts, "Helvetica", "weights", "regular") + @debug map.set($fonts, "Helvetica", "weights", "regular", 300) // ( // "Helvetica": ( - // "weights: ( + // "weights": ( + // "regular": 300, // "medium": 500, // "bold": 700 // ) @@ -445,3 +430,18 @@ title: sass:map // ) <% end %> <% end %> + + +<% function 'map.values($map)', 'map-values($map)', returns: 'list' do %> + Returns a comma-separated list of all the values in `$map`. + + <% example(autogen_css: false) do %> + $font-weights: ("regular": 400, "medium": 500, "bold": 700); + + @debug map.values($font-weights); // 400, 500, 700 + === + $font-weights: ("regular": 400, "medium": 500, "bold": 700) + + @debug map.values($font-weights) // 400, 500, 700 + <% end %> +<% end %> From c549a732a171ea3f45f5e8d7fd7340d371e263ac Mon Sep 17 00:00:00 2001 From: awjin Date: Wed, 7 Oct 2020 15:24:59 -0500 Subject: [PATCH 4/5] Delimiters and typos. --- source/documentation/modules/map.html.md.erb | 21 ++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/source/documentation/modules/map.html.md.erb b/source/documentation/modules/map.html.md.erb index a52928f33..726c37f9b 100644 --- a/source/documentation/modules/map.html.md.erb +++ b/source/documentation/modules/map.html.md.erb @@ -24,11 +24,9 @@ title: sass:map <% function 'map.deep-merge($map1, $map2)', returns: 'map' do %> - Identical to [`map.merge()`][], except that nested map values are *also* + Identical to [`map.merge()`](#merge), except that nested map values are *also* recursively merged. - [`map.merge()`][#merge] - <% example(autogen_css: false) do %> $helvetica-light: ( "weights": ( @@ -100,6 +98,8 @@ title: sass:map // ("medium": 500, "bold": 700) <% end %> + --- + If `$keys` is not empty, the map targeted for updating is nested within `$map`. From left to right, including `$key` and excluding the last key in `$keys`, these keys form a path of nested maps that leads to the targeted map. @@ -151,6 +151,8 @@ title: sass:map <%= partial 'code-snippets/example-map-get' %> + --- + If `$keys` is not empty, the map targeted for searching is nested within `$map`. From left to right, including `$key` and excluding the last key in `$keys`, these keys form a path of nested maps that leads to the targeted map. @@ -158,7 +160,8 @@ title: sass: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. + or if any key in `$keys` is missing from a map or references a value that is + not a map. <% example(autogen_css: false) do %> $fonts: ( @@ -202,6 +205,8 @@ title: sass:map @debug map.has-key($font-weights, "bolder") // false <% end %> + --- + If `$keys` is not empty, the map targeted for searching is nested within `$map`. From left to right, including `$key` and excluding the last key in `$keys`, these keys form a path of nested maps that leads to the targeted map. @@ -209,8 +214,8 @@ title: sass: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. + Returns false if it does not, or if any key in `$keys` is missing from a map + or references a value that is not a map. <% example(autogen_css: false) do %> $fonts: ( @@ -256,7 +261,7 @@ title: sass:map returns: 'map' do %> <% heads_up do %> In practice, the actual arguments to `map.merge($map1, $keys..., $map2)` - are passed as `map.set($map1, $args). They are described here as `$map1, + are passed as `map.set($map1, $args...). They are described here as `$map1, $keys..., $map2` for explanation purposes only. <% end %> @@ -365,7 +370,7 @@ title: sass:map returns: 'map' do %> <% heads_up do %> In practice, the actual arguments to `map.set($map, $keys..., $key, $value)` - are passed as `map.set($map, $args). They are described here as `$map, + are passed as `map.set($map, $args...). They are described here as `$map, $keys..., $key, $value` for explanation purposes only. <% end %> From a55bdf10bdafc892b761efca318dcd27a1c573a9 Mon Sep 17 00:00:00 2001 From: awjin Date: Wed, 7 Oct 2020 15:47:16 -0500 Subject: [PATCH 5/5] Fix passive voice. --- source/documentation/modules/map.html.md.erb | 37 +++++++++----------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/source/documentation/modules/map.html.md.erb b/source/documentation/modules/map.html.md.erb index 726c37f9b..eca404c83 100644 --- a/source/documentation/modules/map.html.md.erb +++ b/source/documentation/modules/map.html.md.erb @@ -100,9 +100,9 @@ title: sass:map --- - If `$keys` is not empty, the map targeted for updating is nested within - `$map`. From left to right, including `$key` and excluding the last key in - `$keys`, these keys form a path of nested maps that leads to the targeted map. + If `$keys` is not empty, follows the set of keys including `$key` and + excluding the last key in `$keys`, from left to right, to find the nested map + targeted for updating. Returns a copy of `$map` where the targeted map does not have a value associated with the last key in `$keys`. @@ -153,9 +153,9 @@ title: sass:map --- - If `$keys` is not empty, the map targeted for searching is nested within - `$map`. From left to right, including `$key` and excluding the last key in - `$keys`, these keys form a path of nested maps that leads to the targeted map. + If `$keys` is not empty, follows the set of keys including `$key` and + excluding the last key in `$keys`, from left to right, to find the nested map + targeted for searching. Returns the value in the targeted map associated with the last key in `$keys`. @@ -207,9 +207,9 @@ title: sass:map --- - If `$keys` is not empty, the map targeted for searching is nested within - `$map`. From left to right, including `$key` and excluding the last key in - `$keys`, these keys form a path of nested maps that leads to the targeted map. + If `$keys` is not empty, follows the set of keys including `$key` and + excluding the last key in `$keys`, from left to right, to find the nested map + targeted for searching. Returns true if the targeted map contains a value associated with the last key in `$keys`. @@ -290,14 +290,12 @@ title: sass:map --- - If `$keys` are passed, the map targeted for merging is nested within `$map1`. - The multiple keys in `$keys` form a path of nested maps that leads to the - targeted map. + If `$keys` is not empty, follows the `$keys` to find the nested map targeted + for merging. If any key in `$keys` is missing from a map or references a value + that is not a map, sets the value at that key to an empty map. Returns a copy of `$map1` where the targeted map is replaced by a new map that - contains all the keys and values from both the targeted map and `$map2`. If - any key in `$keys` references a value that is not a map, that value is - replaced with a map containing the key. + contains all the keys and values from both the targeted map and `$map2`. <% example(autogen_css: false) do %> $fonts: ( @@ -391,13 +389,12 @@ title: sass:map --- - 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. + If `$keys` are passed, follows the `$keys` to find the nested map targeted for + updating. If any key in `$keys` is missing from a map or references a value + that is not a map, sets the value at that key to an empty 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. + `$value`. <% example(autogen_css: false) do %> $fonts: (