sass-list-maps 0.9.2 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fdc88d29473b92024c87d8ed0a9632d54da27d73
-  data.tar.gz: c73f8bd8f1d21d41ccdf37d2d4b252bd8bfc17eb
+  metadata.gz: a0f364c482873fa534b9168cfeeb88ec97a21dab
+  data.tar.gz: 9191db0a554e5fbeb72884143607c3f3cc629850
 SHA512:
-  metadata.gz: f9ae2bca742ff29fbee7744b30fa7afe64ceb311dfad0a33694dce51e174b5efffd356403305b1c5d67a627492d23a82aa402ddbeef4ec14ca1b8bbdefd277c0
-  data.tar.gz: 5bdf3f67eab7ffcdbdab4edda0ca876ca4484db9106f6d4898f1d7e448d9efcf11a341b5e959c21b2bbafa16f1d3400aa9e1c061926ad4a527fb60c7689cf451
+  metadata.gz: 0cca799423392ec54da72fab4411c592896612b515a89c0aaa1775d985c88bc4977de61681e5ac892fbd432390c4bcd02dbcdc72fba63901b3348c1a4f915f7a
+  data.tar.gz: c03d6c7c3e0f1c25b5e1eecfc649adb981169f706a83f0c30f13f0505fe542fac454fc3f81fa65b7862fb9f43923d4a0d3b70a6b34c68353352b32f33009baaa

data/README.md

@@ -1,14 +1,15 @@
 ## Sass List–Maps
 
-Forward-compatible map (hash) functionality for [libsass](https://github.com/hcatlin/libsass) and [ruby-sass](http://sass-lang.com/) < 3.3.x using lists.
+Forward-compatible map (hash) functionality for [libsass](https://github.com/hcatlin/libsass) and [ruby-sass](http://sass-lang.com/) 3.2.x using lists.
 
 ![](sass-hash.jpg)
 
-*Some Sass hash. Not everyone likes this joke somehow.*
+*Some Sass hash. Not everyone likes this joke.*
 
 ###### Latest Updates
 
-* 0.9.2 -- improved performance with `set-nth()` function
+* 0.9.3 -- deprecated `list()` function in favor of native `zip()` for creating single-pair list-maps
+* 0.9.2 -- improved merge performance with rewritten `set-nth()` function
 * 0.9.2 -- included `get()`, `merge()`, and `set()` aliases by default
 * now listed at the [sache.in](http://www.sache.in/) directory of Sass & Compass Extensions
 
@@ -18,7 +19,7 @@ You can test-drive these functions [at Sassmeister in this pre-loaded gist](http
 
 ###### Install it
 
-Sass List-Maps can now be installed as a Bower component or a gem (Compass extension) as alternative to cloning, downloading or cutting and pasting from this repo:
+Sass List-Maps can be installed as a Bower component or a gem (Compass extension) as alternative to cloning, downloading or cutting and pasting from this repo:
 
 ```sh
 # installation with bower
@@ -118,18 +119,18 @@ $list-map: ( alpha 1, beta 2, gamma 3 );
 
 $list-map: ( alpha 1, beta 2, gamma 3 );
 
-$new-map: map-merge($list-map, list(gamma 4));
+$new-map: map-merge($list-map, zip(gamma, 4));
 // -> $new-map = ( alpha 1, beta 2, gamma 4 )
 
 $short-map: map-remove($list-map, alpha);
 // -> $short-map = ( beta 2, gamma 3)
 ```
 
-**NB**: notice the use of the `list()` function in the second example. This is due to the fact that Sass has no succinct way to create a list containing another list, if the containing list is only 1 element in length. Since a list-map must always be a list-of-lists—even if it only contains one item—you must use the `list()` function (included here) when creating list-maps of only one key-value pair.
+**NB**: notice the use of the `zip()` function in the second example. This is used because Sass has no way to create a list containing a single item that is also a list, using notation alone. For list-maps with only one pair therefore, we use the `zip()` function to combine its arguments in to a list of pairs.
 
 #### Advanced
 
-In addition to the core ruby-sass 3.3+ map functions, this repo includes 'depth' versions of `map-get()` and `map-merge()`, suffixed here with `-z`.
+In addition to the core ruby-sass 3.3+ map functions, this library includes 'depth' or 'nested' versions of `map-get()` and `map-merge()` -- suffixed here with `-z`.
 
 ##### 4. `map-get-z($list, $keys...)`
 
@@ -155,7 +156,7 @@ $list-map-z: (
 
 ##### 5. `map-merge-z($list, $keys-and-value...)`
 
-The `map-merge-z()` function takes a chain of keys to indicate where (at what depth) to merge, interpreting its final argument as the value to be merged. This value can be of any type including another list/list-map. Note that if only one key/value argument is passed and it is not a list, it is interpreted as the key, and an empty list is merged in as the value:
+The `map-merge-z()` function takes a chain of keys to indicate where (at what depth) to merge, and takes its final argument as the value to be merged. This value can be of any type including another list/list-map. Note that if only one key/value argument is passed and it is not a list, it is interpreted as the key, and an empty list is merged in as the value:
 
 ```scss
 @import "sass-list-maps";
@@ -180,15 +181,23 @@ $new-map4-z: map-merge-z($list-map-z, delta, epsilon, 5);
 // -> ( alpha ( beta ( gamma 3 ) ), ( delta ( epsilon 5 ) ) )
 ```
 
-##### 6. Unified syntax
+##### 6. UNIFIED SYNTAX: `get()`, `merge()`, `set()`
 
-Note that in the above examples, the `-z` suffixed functions work like their 'simple' counterparts if given only two arguments. This is by design, so that they can transparently replace them. Moreover, the `map-merge-z($list, $keys-and-value...)` and `map-merge-z($list1, $list2)` argument patterns are interchangeable. This means that `map-merge-z()` can be treated as if it were `map-set-z($list, $keys..., $value)`, which is a common alternative syntax when dealing with hashes. In light of this, the following aliased functions are provided—as of version 0.9.2—to unify and simplify the usage of map functions as much as is possible:
+Note that in the above 'advanced' examples, the `-z` suffixed functions work like their 'simple' counterparts if given only two arguments, which means they can transparently replace them and will respond to the number of 'key' arguments required. Moreover, `map-merge-z($list, $key[s...], $value)` and `map-merge-z($list1, $list2)` argument patterns are interchangeable, which means that `map-merge-z()` can be treated as if it were `map-set-z()`, which can be a more intuitive semantic. The following aliases are provided—as of version 0.9.2—to unify and simplify all of the above list-map logic to three universal functions:
 
 ```scss
+@import "sass-list-maps";
+
+// get($list, $key[s...])
+// accepts 1 or more key args as target, returns value
 @function get($args...) { @return map-get-z($args...); }
 
+// merge($list1, [$keys...,] $list2)
+// accepts 0 or more key args as target, merges list at target
 @function merge($args...) { @return map-merge-z($args...); }
 
+// set($list, $key[s...], $value)
+// accepts 1 or more key args as target, sets value at target
 @function set($args...) { @return map-merge-z($args...); }
 ```
 
@@ -196,20 +205,18 @@ Note that in the above examples, the `-z` suffixed functions work like their 'si
 
 There are a few points that bear mentioning/repeating:
 
-* operating on global variables in libsass and in ruby-sass versions before 3.3.x works differently than in 3.3+. You can make changes to global variables from inside a mixin scope but you can't create them from there. This has implications for mixins that do operations on global list-maps.
-* as noted, the 'list-map' syntax is less forgiving than that of native maps (watch the commas). Also, it lacks any error-checking (e.g. native maps will produce a warning if you have duplicate keys). And obviously fancy features of native maps such as passing a map to a function in the form `my-function($map...)` whereupon you can reference the key/value elements inside the function as if they were named variables, doesn't work with list-maps.
-* as noted, the `list()` function is required if you want to make a list-map with only one pair, since Sass has no short way of specifying a list of a list like that (e.g. `$list: ((key value));` doesn't work, you need `$list: list(key value);`).
-* as of this writing, this code contains no test-suites or inline error-catches or warnings of any kind. I've been using it in my own work but there are surely edge-cases I haven't seen. I welcome reports and contributions.
+* operating on global variables in libsass and in ruby-sass 3.2.x or earlier, works differently than in 3.3.x+: You can make changes to global variables from inside a mixin scope but you can't create them from there. There is no `!global` flag. This has implications for mixins that operate on global list-maps.
+* as noted, the 'list-map' syntax is less forgiving than that of native maps (watch your commas). Also, it lacks any error-checking (e.g. native maps will produce a warning if you have duplicate keys). And obviously fancy features of native maps such as passing a map to a function in the form `my-function($map...)` whereupon you can reference the key/value elements inside the function as if they were named variables, doesn't work with list-maps.
+* as noted, the `zip()` function is required if you want to make a list-map with only one pair, since Sass has no short way of specifying a list with one list inside (e.g. `$list: ((key value));` doesn't work, you need `$list: zip(key, value);`).
+* as of this writing, this code contains no test-suites or inline error-catches or warnings of any kind. I've been using it in my own work but there are surely edge-cases I haven't seen. I welcome reports and contributions!
 
 ### To-Dos
 
 * Make a depth-based version of `map-remove()`
-* <del>Make this in to a bower package</del> *done*
-* <del>Make this in to a gem</del> *done*
 * Push a native maps version of the 'advanced' functions above
 
 ### Acknowledgements
 
 First and foremost, gratitude to the core Sass devs (@nex3 and @chriseppstein) for their tireless advancement of the gold-standard of CSS pre-processing, and secondly to @jedfoster and @anotheruiguy for [Sassmeister](http://sassmeister.com/), which makes developing complex functions and mixins relatively painless.
 
-Also acknowledgements to @HugoGiraudel for [SassyLists](http://sassylists.com/), from which I borrowed some functions early on, and especially `debug()`, without which I would not have been able to figure out what was going on (and going wrong) in ruby-sass 3.2 and libsass.
+Also acknowledgements to @HugoGiraudel for [SassyLists](http://sassylists.com/), from which I adapted some early functions, and especially for his list `debug()` function, without which I would not have been able to figure out what was going on (and going wrong) in ruby-sass 3.2.x and libsass.

data/sass-list-maps.scss

@@ -1,13 +1,11 @@
 // list helper functions
+// 0.9.3 -- "list()" now deprecated in favor of "zip()".
 
 @function list($args...) {
 	$output: ();
 	@each $arg in $args { $output: append($output, $arg); }
 	@return $output;
 }
-@function unlist($list) {
-	@return if(length($list) == 1, nth($list, 1), $list);
-}
 @function slice($list, $start: 1, $end: length($list), $sep: 'comma') {
 	$output: ();
 	@for $i from $start through $end {
@@ -23,10 +21,13 @@
 	@return $output;
 }
 
-// list-map helper functions, purely semantic
+// list-map helper functions
+// 0.9.3 -- key() and value() tentatively added as alternatives to 'tuple-' named funcs
 
 @function tuple-key($tuple) { @return nth($tuple, 1); }
 @function tuple-value($tuple) { @return nth($tuple, 2); }
+@function key($tuple) { @return nth($tuple, 1); }
+@function value($tuple) { @return nth($tuple, 2); }
 
 // list-map versions of map-keys(), -values() and -has-key() functions
 
@@ -68,7 +69,7 @@
 	@return $out;
 }
 
-// advanced: map-get-z() and map-merge-z()
+// deep/nested map functions: map-get-z() and map-merge-z()
 
 @function map-get-z($list, $keys...) {
 	@each $key in $keys {
@@ -80,17 +81,18 @@
 	$arg-length: length($keys-and-value);
 	$value: nth($keys-and-value, $arg-length);
 	$key-length: $arg-length - 1;
-	@if $key-length == 0 { $value: if(type-of($value) == 'list', map-merge($list, $value), map-merge($list, list($value ()))); }
+	@if $key-length == 0 { $value: if(type-of($value) == 'list', map-merge($list, $value), map-merge($list, zip($value, ()))); }
 	@else { $start: if(type-of($value) == 'list', 0, 1);
 		@for $i from $start through $key-length {
 			$new-list: (); $old-list: ();
-			@if $i == 0 { $new-list: $value; } @else { $new-list: list(nth($keys-and-value, $key-length + 1 - $i) $value); }
+			@if $i == 0 { $new-list: $value; } @else { $new-list: zip(nth($keys-and-value, $key-length + 1 - $i), $value); }
 			@if $i == $key-length { $old-list: $list; } @else { $old-list: map-get-z($list, slice($keys-and-value, 1, $key-length - $i)...) or (); }
 			$value: map-merge($old-list, $new-list); } }
 	@return $value;
 }
 
-// aliases: keep it simple stupid
+// 0.9.2 -- aliases
+// these replace map-*() and map-*-z() variants with a single universal function
 
 @function get($args...) { @return map-get-z($args...); }
 @function merge($args...) { @return map-merge-z($args...); }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sass-list-maps
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.9.3
 platform: ruby
 authors:
 - Lu Nelson
@@ -38,7 +38,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 3.2.0
-description: Forward-compatible map functionality for libsass and ruby-sass <3.3
+description: Forward-compatible map functionality for libsass and ruby-sass 3.2.x
 email: lunelson@gmail.com
 executables: []
 extensions: []
@@ -71,5 +71,5 @@ rubyforge_project:
 rubygems_version: 2.2.1
 signing_key: 
 specification_version: 4
-summary: Maps for libsass and ruby-sass <3.3
+summary: Maps for libsass and ruby-sass 3.2.x
 test_files: []