sass-list-maps 0.9.3 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a0f364c482873fa534b9168cfeeb88ec97a21dab
-  data.tar.gz: 9191db0a554e5fbeb72884143607c3f3cc629850
+  metadata.gz: 5c97d160f874130a49e80f8d7aa48d669330a12b
+  data.tar.gz: 696c4f6fd2d0b64dab79e981fd54b59e55ca4977
 SHA512:
-  metadata.gz: 0cca799423392ec54da72fab4411c592896612b515a89c0aaa1775d985c88bc4977de61681e5ac892fbd432390c4bcd02dbcdc72fba63901b3348c1a4f915f7a
-  data.tar.gz: c03d6c7c3e0f1c25b5e1eecfc649adb981169f706a83f0c30f13f0505fe542fac454fc3f81fa65b7862fb9f43923d4a0d3b70a6b34c68353352b32f33009baaa
+  metadata.gz: 03e109aef6c8fa11da09c5e8ffab01d1bd45eb7a222e033b45cf6d48e0474e1d87e6cbf032114331a5114959d2ca0de9f582e928f6143ffcbb81f87c6373fb91
+  data.tar.gz: 95b7fd14ebe94db84ee5f767e2e64e8bbfa06bd1bfffa182691e780d3298a7e2dee8c5f7a7c8145ea6a1c8012414a92844d4dd62b9f758aa29fbadf768ce0a32

data/README.md

@@ -4,22 +4,21 @@ Forward-compatible map (hash) functionality for [libsass](https://github.com/hca
 
 ![](sass-hash.jpg)
 
-*Some Sass hash. Not everyone likes this joke.*
-
 ###### Latest Updates
 
-* 0.9.3 -- deprecated `list()` function in favor of native `zip()` for creating single-pair list-maps
+* 0.9.5 -- now handles single-pair lists automatically. This means no more need for `list()` or `zip()` functions, which are now deprecated.
+* 0.9.3 -- <del>deprecated `list()` function in favor of native `zip()` for creating single-pair list-maps</del> this was the best
 * 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
 
 ###### Try it out
 
-You can test-drive these functions [at Sassmeister in this pre-loaded gist](http://sassmeister.com/gist/8645654), and you can use them in your own Sassmeister gists by setting the compiler to Sass 3.2.x or libsass and including the "Sass List–Maps" extension in the control panel.
+You can test-drive these functions [at Sassmeister in this pre-loaded gist](http://sassmeister.com/gist/8645654). NB: the libsass version at Sassmeister might be a couple of point-releases behind this repo.
 
 ###### Install it
 
-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:
+Sass List-Maps can be installed as a Bower component or a gem (Compass extension):
 
 ```sh
 # installation with bower
@@ -29,15 +28,17 @@ bower install sass-list-maps
 gem install sass-list-maps
 ```
 
+You can also just fork or download this repo or cut-and-paste.
+
 ### Introduction
 
-Maps (also known as hashes or objects\*) allow dynamic creating, setting and retrieving of data. They are supported natively in ruby-sass as of version 3.3.x with dedicated syntax and functions; but for earlier ruby-sass versions—and for the increasingly popular libsass C-based compiler (until the point at which maps are integrated there natively)—this is an alternative solution. These functions feature-match ruby-sass 3.3's map functionality as closely as possible using the `list` data-type. Additional functions are also provided to extend this functionality with nested getting and merging/setting.
+Maps (also known as hashes or objects\*) allow dynamic creating, setting and retrieving of data. They are supported natively in ruby-sass as of version 3.3.x with a new syntax and dedicated functions; but for earlier ruby-sass versions—and for the increasingly popular libsass C-based compiler (until the point at which maps are integrated there natively)—this is an alternative solution. These functions feature-match ruby-sass 3.3's map functionality using the `list` data-type. Additional functions are also provided to extend this functionality with nested getting and merging/setting.
 
 *\* objects (as in javascript) are not exactly the same thing as maps and hashes, but for these purposes close enough.*
 
 ### 'List-map' syntax
 
-List-maps—as I'll refer to them for the sake of clarity, as opposed to native maps—are like any other list in Sass but must be formatted carefully, as a list of pairs. The formatting I recommend keeps as close as possible to the syntax of native maps, with the difference that there no colons (`:`), and the placement of commas is more critical (e.g. trailing commas—commas after the last item—are allowed in native maps and in lists in ruby-sass 3.3+ but not in any other version):
+List-maps—as opposed to native maps—are like any other list in Sass but must be formatted specifically as a list of pairs. The formatting I recommend keeps as close as possible to the syntax of native maps, with the difference that there no colons (`:`), and the placement of commas is more critical (e.g. trailing commas—commas after the last item—are allowed in native maps and in lists in ruby-sass 3.3+ but not in any other version):
 
 
 ```scss
@@ -53,7 +54,7 @@ in any version/compiler other than ruby-sass 3.3+
 $native-map: ( alpha: 1, beta: 2, gamma: 3,);
 ```
 
-Being a list of pairs then, a list-map list can be of any length, but each item in that list must be a list of exactly two. The first of these is the 'key' and is usually a string; the second is the 'value' and can be of any type, including being another list (of pairs!). In this way list-maps can be nested. Such a 'nested' list-map looks like this in its simplest form (compared again to a native map):
+As a list of pairs, a list-map list can be of any length; but each item in that list must be a list of exactly two. The first of these is the 'key' and is usually a string; the second is the 'value'. This 'value' however, can be of any type—including another list (of pairs)—which allows list-maps to form nested or tree-like data structures. Such a 'nested' list-map looks like this (compared again to a native map):
 
 ```scss
 $list-map-z: (
@@ -119,18 +120,18 @@ $list-map: ( alpha 1, beta 2, gamma 3 );
 
 $list-map: ( alpha 1, beta 2, gamma 3 );
 
-$new-map: map-merge($list-map, zip(gamma, 4));
+$new-map: map-merge($list-map, 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 `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.
+**NB**: you might notice in the second example above, that the second argument to map-merge isn't really a 'list-map' it's just a list of two items. This is the so-called "single item" list conundrum in Sass which is a bit tricky, but these functions as of 0.9.5 handle this case automatically.
 
 #### Advanced
 
-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`.
+In addition to the core ruby-sass 3.3+ map functions, this library includes 'deep' or 'nested' versions of `map-get()` and `map-merge()` -- suffixed here with `-z`.
 
 ##### 4. `map-get-z($list, $keys...)`
 
@@ -207,7 +208,6 @@ There are a few points that bear mentioning/repeating:
 
 * 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

data/_sass-list-maps.scss

@@ -0,0 +1,148 @@
+// list helper functions
+// 0.9.3 -- "list()" now deprecated in favor of "zip()".
+// 0.9.5 -- "zip()" now deprecated as well: single-pair lists are handled automatically
+
+@function list($args...) {
+  $output: ();
+  @each $arg in $args { $output: append($output, $arg, 'comma'); }
+  @return $output;
+}
+@function slice($list, $start: 1, $end: length($list), $sep: 'comma') {
+  $output: ();
+  @for $i from $start through $end {
+    $output: append($output, nth($list, $i), $sep); }
+  @return $output;
+}
+@function set-nth($list, $index, $value, $sep: 'comma') {
+  $length: length($list); $output: ();
+  @if $index > $length or $index <= 0 { @return $list; }
+  @if $index > 1 { @for $i from 1 through $index - 1 { $output: append($output, nth($list, $i), $sep); } }
+  $output: append($output, $value, $sep);
+  @if $length > 1 { @for $i from $index + 1 through $length { $output: append($output, nth($list, $i), $sep); } }
+  @return $output;
+}
+
+// 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); }
+
+// 0.9.5 -- added list-map-check()
+
+@function list-map-check($list) { @if length($list) == 2 and length(nth($list, 1)) == 1 { @return append((), $list, 'comma'); } @return $list; }
+
+// list-map versions of list-map-keys(), -values() and -has-key() functions
+// 0.9.5 -- now all handle single- or double-wrapped list-maps (single-pair case) automatically
+// 0.9.5 -- added map-prev-key() and map-next-key() functions
+
+@function map-keys($list...) {
+  @if length($list) == 1 { $list: list-map-check($list...); }
+  @else { $list: list-map-check($list); } $output: ();
+  @each $tuple in $list { $output: append($output, tuple-key($tuple), 'comma'); }
+  @return $output;
+}
+@function map-values($list...) {
+  @if length($list) == 1 { $list: list-map-check($list...); }
+  @else { $list: list-map-check($list); } $output: ();
+  @each $tuple in $list { $output: append($output, tuple-value($tuple), 'comma'); }
+  @return $output;
+}
+@function map-has-key($list, $key) {
+  $list: list-map-check($list);
+  @each $tuple in $list { @if tuple-key($tuple) == $key { @return true; } }
+  @return false;
+}
+@function map-prev-key($list, $key) {
+  $list: list-map-check($list); $keys: map-keys($list);
+  @return nth($keys, index($keys, $key) - 1)
+}
+@function map-next-key($list, $key) {
+  $list: list-map-check($list); $keys: map-keys($list);
+  @return nth($keys, index($keys, $key) + 1)
+}
+
+// list-map versions of list-map-get(), -merge() and -remove()
+// 0.9.5 -- list-map-check() has been integrated to handle single-pair inputs, and give correct outputs
+
+@function map-get($list, $key, $check: true) {
+  @if $check { $list: list-map-check($list); } @each $tuple in $list {
+    @if tuple-key($tuple) == $key { @return list-map-check(tuple-value($tuple)); } }
+   // @if tuple-key($tuple) == $key { @return list-map-check($tuple); } }
+  @return null;
+}
+@function map-merge($list1, $list2, $check: true) {
+  @if $check { $list1: list-map-check($list1); $list2: list-map-check($list2); }
+  $keys1: map-keys($list1);
+  @each $tuple in $list2 {
+    $index: index($keys1, tuple-key($tuple));
+    @if $index { $list1: set-nth($list1, $index, $tuple); }
+    @else { $list1: append($list1, $tuple, 'comma'); } }
+  @return $list1;
+}
+@function map-remove($list, $key) {
+  $list: list-map-check($list);
+  $keys: map-keys($list); $output: ();
+  @for $n from 1 through length($list) {
+    @if nth($keys, $n) != $key { $output: append($output, nth($list, $n), 'comma'); } }
+  @return $output;
+}
+
+// deep/nested map functions: list-map-get-z() and list-map-merge-z()
+// 0.9.5 -- list-map-check() has been integrated, implicitly or explicitly
+
+@function map-get-z($list, $keys...) {
+  @if $list == null { @return null; }
+  $length: length($keys);
+  $list: map-get($list, nth($keys, 1));
+  @if $length > 1 {
+    @for $n from 2 through $length {
+      @if $list == null { @return null; }
+      $list: map-get($list, nth($keys, $n), false); }
+    @return $list; }
+  @else { @return $list; }
+}
+@function map-merge-z($list, $keys-and-value...) {
+  $arg-length: length($keys-and-value);
+  $value: nth($keys-and-value, $arg-length);
+  $key-length: $arg-length - 1;
+  $list: list-map-check($list);
+  @if $key-length == 0 {
+    $value: if(type-of($value) == 'list', map-merge($list, list-map-check($value), false), map-merge($list, append((), $value (), 'comma'), false)); }
+  @else { $start: 1; @if type-of($value) == 'list' { $start: 0; $value: list-map-check($value); }
+    @for $i from $start through $key-length {
+      $new-list: (); $old-list: ();
+      @if $i == 0 { $new-list: $value; } @else { $new-list: append((), nth($keys-and-value, $key-length + 1 - $i) $value, 'comma'); }
+      @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 added as of 0.9.2: unify and replace map-*() and map-*-z() variants
+
+@function get($args...) { @return list-map-get-z($args...); }
+@function merge($args...) { @return list-map-merge-z($args...); }
+@function set($args...) { @return list-map-merge-z($args...); }
+
+// new as of 0.9.5: map-inspect()
+// experimental
+
+@function map-inspect($list...) {
+  @if length($list) == 1 { $list: list-map-check($list...); }
+  @else { $list: list-map-check($list); }
+  $output: '('; $i: 1;
+  @each $tuple in $list {
+    @if length($tuple) != 2 {
+      $output: $output + '#{$tuple}'; }
+    @else {
+      $key: nth($tuple, 1);
+      $value: nth($tuple, 2);
+      @if type-of($value) == 'list' { $output: $output + '#{$key} #{map-inspect($value)}'; }
+      @else { $output: $output + '#{$key} #{$value}'; } }
+    @if $i < length(map-keys($list)) { $output: $output + ', '; }
+    $i: $i + 1;
+  }
+  @return $output + ')';
+}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sass-list-maps
 version: !ruby/object:Gem::Version
-  version: 0.9.3
+  version: 0.9.5
 platform: ruby
 authors:
 - Lu Nelson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-24 00:00:00.000000000 Z
+date: 2014-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: compass
@@ -46,8 +46,8 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- _sass-list-maps.scss
 - lib/sass-list-maps.rb
-- sass-list-maps.scss
 homepage: https://github.com/lunelson/sass-list-maps
 licenses:
 - MIT

data/sass-list-maps.scss

@@ -1,99 +0,0 @@
-// 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 slice($list, $start: 1, $end: length($list), $sep: 'comma') {
-	$output: ();
-	@for $i from $start through $end {
-		$output: append($output, nth($list, $i), $sep); }
-	@return $output;
-}
-@function set-nth($list, $index, $value, $sep: 'comma') {
-	$length: length($list); $output: ();
-	@if $index > $length or $index <= 0 { @return $list; }
-	@for $i from 1 through $index - 1 { $output: append($output, nth($list, $i), $sep); }
-	$output: append($output, $value, $sep);
-	@for $i from $index + 1 through $length { $output: append($output, nth($list, $i), $sep); }
-	@return $output;
-}
-
-// 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
-
-@function map-keys($list) {
-	$output: ();
-	@each $tuple in $list { $output: append($output, tuple-key($tuple), 'comma'); }
-	@return $output;
-}
-@function map-values($list) {
-	$output: ();
-	@each $tuple in $list { $output: append($output, tuple-value($tuple), 'comma'); }
-	@return $output;
-}
-@function map-has-key($list, $key) {
-	@each $tuple in $list { @if tuple-key($tuple) == $key { @return true; } }
-	@return false;
-}
-
-// list-map versions of map-get(), -merge() and -remove()
-
-@function map-get($list, $key) {
-	@if length($list) == 0 { @return null; }
-	@else if length(nth($list, 1)) == 1 { @if tuple-key($list) == $key { @return tuple-value($list); } }
-	@else { @each $tuple in $list { @if tuple-key($tuple) == $key { @return tuple-value($tuple); } } }
-	@return null;
-}
-@function map-merge($list1, $list2) {
-	$keys1: map-keys($list1);
-	@each $tuple in $list2 {
-		$index: index($keys1, tuple-key($tuple));
-		@if $index { $list1: set-nth($list1, $index, $tuple); }
-		@else { $list1: append($list1, $tuple, 'comma'); } }
-	@return $list1;
-}
-@function map-remove($list, $key) {
-	$keys: map-keys($list); $out: ();
-	@for $n from 1 through length($list) {
-		@if nth($keys, $n) != $key { $out: append($out, nth($list, $n), 'comma'); } }
-	@return $out;
-}
-
-// deep/nested map functions: map-get-z() and map-merge-z()
-
-@function map-get-z($list, $keys...) {
-	@each $key in $keys {
-		@if $list == null { @return null; }
-		@else { $list: map-get($list, $key); } }
-	@return $list;
-}
-@function map-merge-z($list, $keys-and-value...) {
-	$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, 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: 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;
-}
-
-// 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...); }
-@function set($args...) { @return map-merge-z($args...); }