sass-list-maps 0.9.7 → 0.9.9
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +100 -45
- data/_sass-list-maps.scss +30 -4
- metadata +5 -4
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 85bcf7214f40042aadd55fa5398155b44c7d6082
|
|
4
|
+
data.tar.gz: 144f031bb7e12acb9d541603da96652be0296ac6
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 7dfa1543f07dc9011a7ffeca5e7bf861c8b34ee0ea165063abc86e040d9f5495fbe492c58ae5b8d5d7b38f04a999bea18aba0305dd1726094d6523aeec0e3508
|
|
7
|
+
data.tar.gz: 126beea1c3b5b2b5c43cbe144b1be70bde50e03651590c6d6b3a77e3ea7f2f8d8aecece338bc83b21fcb8f46b9abd2bddc591bcb0dc9e0522e5a856f8ba0a86c
|
data/README.md
CHANGED
|
@@ -1,63 +1,68 @@
|
|
|
1
1
|
## Sass List–Maps
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
These functions provide forward-compatible map (hash) data-type functionality for [libsass](http://libsass.org/) and [ruby-sass](http://sass-lang.com/) 3.2.x using the SassScript `list` data-type. They are a polyfill for the `map` data-type introduced in ruby-sass 3.3.x. They feature-match all the current native (ruby-sass) `map` functions, and add nested (or 'chained') `get()`, `set()` and `merge()` functions and inspection / debugging functions as well.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
#### Updates
|
|
8
8
|
|
|
9
|
-
* 0.9.
|
|
10
|
-
* 0.9.
|
|
11
|
-
* 0.9.3 --
|
|
12
|
-
* 0.9.2 -- improved merge performance with
|
|
13
|
-
* 0.9.
|
|
14
|
-
* now listed at the [sache.in](http://www.sache.in/) directory of Sass & Compass Extensions
|
|
9
|
+
* 0.9.9 -- added `map-pretty()` function to inspect/debug list-maps in pretty-printed form
|
|
10
|
+
* 0.9.6-0.9.8 -- argument-handling enhancements; typo fixes
|
|
11
|
+
* 0.9.3-0.9.5 -- handling single-pair lists automatically. This means no more need for `list()` or `zip()` functions, which are now deprecated.
|
|
12
|
+
* 0.9.2 -- improved merge performance with new `set-nth()` function; included `get()`, `merge()`, and `set()` aliases by default
|
|
13
|
+
* 0.9.1 -- now listed at the [sache.in](http://www.sache.in/) directory of Sass & Compass Extensions
|
|
15
14
|
|
|
16
|
-
|
|
15
|
+
#### Try it
|
|
17
16
|
|
|
18
|
-
You can test-drive these functions
|
|
17
|
+
You can test-drive these functions at [Sassmeister, in this pre-loaded gist](http://sassmeister.com/gist/8645654)—but note that the libsass version at Sassmeister might be a couple of point-releases behind this repo.
|
|
19
18
|
|
|
20
|
-
|
|
19
|
+
#### Install it
|
|
21
20
|
|
|
22
|
-
Sass List-Maps can be installed as a Bower component or a gem
|
|
21
|
+
'Sass List-Maps' can be installed as a Bower component for non-ruby setups (see [node-sass options](http://github.com/sindresorhus/grunt-sass#includepaths) if you are using libsass via node) or as a gem-based Compass extension for ruby setups:
|
|
23
22
|
|
|
24
23
|
```sh
|
|
25
24
|
# installation with bower
|
|
26
25
|
bower install sass-list-maps
|
|
27
26
|
|
|
27
|
+
# if using grunt-sass, you need to set 'includePaths' option
|
|
28
|
+
options: {
|
|
29
|
+
includePaths: [
|
|
30
|
+
'./bower_components/sass-list-maps'
|
|
31
|
+
]
|
|
32
|
+
}
|
|
33
|
+
|
|
28
34
|
# installation with rubygems, for compass
|
|
29
35
|
gem install sass-list-maps
|
|
36
|
+
|
|
37
|
+
# Add to your Sass
|
|
38
|
+
@import "sass-list-maps";
|
|
30
39
|
```
|
|
31
40
|
|
|
32
|
-
You can also just fork or download this repo or
|
|
41
|
+
You can of course also just fork or download this repo or copy-and-paste, as the functions are all in one file.
|
|
33
42
|
|
|
34
43
|
### Introduction
|
|
35
44
|
|
|
36
|
-
Maps (
|
|
45
|
+
Maps (known in programming as hashes, dictionaries, or objects<sup>1</sup>) allow dynamic creating, setting, merging and retrieving of data. They are native to ruby-sass as of version 3.3.x, but for earlier ruby-sass versions, and for the libsass C-based compiler (until the point at which maps are integrated there natively), this is an alternative solution which feature-matches ruby-sass' 3.3.x map functionality using the `list` data-type. Additional functions are also provided to allow nested (chained) getting and merging/setting, and inspection for debugging.
|
|
37
46
|
|
|
38
|
-
|
|
47
|
+
*<sup>1</sup>objects (as in javascript) are not exactly the same thing as maps and hashes, but for these purposes close enough.*
|
|
39
48
|
|
|
40
|
-
|
|
49
|
+
#### Syntax
|
|
41
50
|
|
|
42
|
-
|
|
51
|
+
Compared to ruby-sass' native maps, 'list-maps' are lists like any other list in Sass, but they are *lists of pairs*, formatted in such a way as to be interpreted like a map. To this purpose, the first item in each pair is interpreted as the 'key' (usually a string), while the second is interpreted as the correspondent 'value'. This 'value' can be any Sass-script data-type, including a list—which means list-maps can contain other list-maps, allowing them to form nested data structures.
|
|
43
52
|
|
|
53
|
+
The formatting used here keeps as close as possible to the syntax of native maps, with the difference that there no colons (`:`) used, and the placement of commas is more critical (e.g. a comma after the last item is not allowed):
|
|
44
54
|
|
|
45
55
|
```scss
|
|
46
|
-
/*
|
|
56
|
+
/* a single-line list-map -- compatible with any
|
|
47
57
|
version/compiler of sass including 3.3+ */
|
|
48
|
-
|
|
49
58
|
$list-map: ( alpha 1, beta 2, gamma 3 );
|
|
50
59
|
|
|
51
|
-
/*
|
|
52
|
-
in any version/compiler
|
|
53
|
-
|
|
54
|
-
|
|
60
|
+
/* a single-line ruby-sass native map
|
|
61
|
+
-- would cause an error in any version/compiler
|
|
62
|
+
other than ruby-sass 3.3+ */
|
|
55
63
|
$native-map: ( alpha: 1, beta: 2, gamma: 3,);
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
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):
|
|
59
64
|
|
|
60
|
-
|
|
65
|
+
/* a multi-line list-map */
|
|
61
66
|
$list-map-z: (
|
|
62
67
|
alpha (
|
|
63
68
|
beta (
|
|
@@ -66,7 +71,8 @@ $list-map-z: (
|
|
|
66
71
|
)
|
|
67
72
|
);
|
|
68
73
|
|
|
69
|
-
|
|
74
|
+
/* a mutli-line ruby-sass native map */
|
|
75
|
+
s$native-map-z: (
|
|
70
76
|
alpha: (
|
|
71
77
|
beta: (
|
|
72
78
|
gamma: 3,
|
|
@@ -75,17 +81,15 @@ $native-map-z: (
|
|
|
75
81
|
);
|
|
76
82
|
```
|
|
77
83
|
|
|
78
|
-
It should be clear that list-maps and native maps are very similar
|
|
79
|
-
|
|
80
|
-
### 'List-map' functions
|
|
84
|
+
It should be clear that these 'list-maps' and ruby-sass' native maps are very similar—in fact they are in principle the same (native maps are a special type of list). For this reason it was possible to reverse engineer the map functions of ruby-sass' 3.3+ to use the SassScript 'list' data-type.
|
|
81
85
|
|
|
82
|
-
The
|
|
86
|
+
### The Functions
|
|
83
87
|
|
|
84
|
-
|
|
88
|
+
These functions have the same names as the map functions in ruby-sass >= 3.3.x, which means that if they were used in ruby-sass 3.3.x or higher they would conflict. Therefore, the following code assume a sass environment of either ruby-sass < 3.3.x or libsass. Also, as with native maps in ruby-sass, native list functions (e.g. `nth()`, `index()`) can also be used on list-maps since they are still lists.
|
|
85
89
|
|
|
86
|
-
|
|
90
|
+
#### Core (matching the ruby-sass 3.3.x native map functions)
|
|
87
91
|
|
|
88
|
-
|
|
92
|
+
###### 1. `map-keys($list)`, `map-values($list)`, `map-has-key($list, $key)`
|
|
89
93
|
|
|
90
94
|
```scss
|
|
91
95
|
@import "sass-list-maps";
|
|
@@ -100,7 +104,7 @@ $list-map: ( alpha 1, beta 2, gamma 3 );
|
|
|
100
104
|
}
|
|
101
105
|
```
|
|
102
106
|
|
|
103
|
-
|
|
107
|
+
###### 2. `map-get($list, $key)`
|
|
104
108
|
|
|
105
109
|
```scss
|
|
106
110
|
@import "sass-list-maps";
|
|
@@ -114,7 +118,7 @@ $list-map: ( alpha 1, beta 2, gamma 3 );
|
|
|
114
118
|
}
|
|
115
119
|
```
|
|
116
120
|
|
|
117
|
-
|
|
121
|
+
###### 3. `map-merge($list1, $list2), map-remove($list, $key)`
|
|
118
122
|
|
|
119
123
|
```scss
|
|
120
124
|
@import "sass-list-maps";
|
|
@@ -130,11 +134,13 @@ $short-map: map-remove($list-map, alpha);
|
|
|
130
134
|
|
|
131
135
|
**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.
|
|
132
136
|
|
|
133
|
-
#### Advanced
|
|
137
|
+
#### Advanced (beyond the ruby-sass 3.3.x native map functions)
|
|
134
138
|
|
|
135
|
-
In addition to
|
|
139
|
+
In addition to ruby-sass' native map functionality, this library also provides nested (deep / chained) 'get' and 'set'/'merge' and debugging functions.
|
|
136
140
|
|
|
137
|
-
#####
|
|
141
|
+
##### Nesting / Chaining
|
|
142
|
+
|
|
143
|
+
###### 4. `map-get-z($list, $keys...)`
|
|
138
144
|
|
|
139
145
|
The `map-get-z()` function will retrieve values from a list-map according to a chain of keys (similar to the way nested array/hash/object values are accessed in other languages):
|
|
140
146
|
|
|
@@ -156,7 +162,7 @@ $list-map-z: (
|
|
|
156
162
|
}
|
|
157
163
|
```
|
|
158
164
|
|
|
159
|
-
|
|
165
|
+
###### 5. `map-merge-z($list, $keys-and-value...)`
|
|
160
166
|
|
|
161
167
|
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:
|
|
162
168
|
|
|
@@ -175,7 +181,7 @@ $new-map1-z: map-merge-z($list-map-z, delta);
|
|
|
175
181
|
// -> ( alpha ( beta ( gamma 3 ) ), ( delta ( ) ) )
|
|
176
182
|
$new-map2A-z: map-merge-z($list-map-z, delta, epsilon);
|
|
177
183
|
// -> ( alpha ( beta ( gamma 3 ) ), ( delta epsilon ) )
|
|
178
|
-
$new-map2B-z: map-merge-z($list-map-z,
|
|
184
|
+
$new-map2B-z: map-merge-z($list-map-z, (delta epsilon));
|
|
179
185
|
// -> ( alpha ( beta ( gamma 3 ) ), ( delta epsilon ) )
|
|
180
186
|
$new-map3-z: map-merge-z($list-map-z, (delta 4, epsilon 5));
|
|
181
187
|
// -> ( alpha ( beta ( gamma 3 ) ), ( delta 4 ), ( epsilon 5 ) )
|
|
@@ -183,9 +189,57 @@ $new-map4-z: map-merge-z($list-map-z, delta, epsilon, 5);
|
|
|
183
189
|
// -> ( alpha ( beta ( gamma 3 ) ), ( delta ( epsilon 5 ) ) )
|
|
184
190
|
```
|
|
185
191
|
|
|
186
|
-
#####
|
|
192
|
+
##### Inspection / Debugging
|
|
193
|
+
|
|
194
|
+
###### 6. `map-inspect()`, `map-pretty()`
|
|
187
195
|
|
|
188
|
-
|
|
196
|
+
To aid in development, list-map inspection functions are provided. `map-inspect()` will format a list-map as a string on one line, while `map-pretty()` will format the same string on multiple lines with indentation.
|
|
197
|
+
|
|
198
|
+
```scss
|
|
199
|
+
@import "sass-list-maps";
|
|
200
|
+
|
|
201
|
+
$testmap: (
|
|
202
|
+
alpha (
|
|
203
|
+
beta 2,
|
|
204
|
+
gamma (
|
|
205
|
+
delta 14,
|
|
206
|
+
epsilon 2
|
|
207
|
+
)
|
|
208
|
+
),
|
|
209
|
+
zeta 1,
|
|
210
|
+
eta (
|
|
211
|
+
theta 55
|
|
212
|
+
)
|
|
213
|
+
);
|
|
214
|
+
|
|
215
|
+
.debug {
|
|
216
|
+
inspect: map-inspect($testmap);
|
|
217
|
+
pretty: map-pretty($testmap);
|
|
218
|
+
}
|
|
219
|
+
```
|
|
220
|
+
```css
|
|
221
|
+
.debug {
|
|
222
|
+
inspect: '(alpha (beta 2, gamma (delta 14, epsilon 2)), zeta 1, eta (theta 55))';
|
|
223
|
+
pretty: '(
|
|
224
|
+
alpha (
|
|
225
|
+
beta 2,
|
|
226
|
+
gamma (
|
|
227
|
+
delta 14,
|
|
228
|
+
epsilon 2
|
|
229
|
+
)
|
|
230
|
+
),
|
|
231
|
+
zeta 1,
|
|
232
|
+
eta (
|
|
233
|
+
theta 55
|
|
234
|
+
)
|
|
235
|
+
)'; }
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
##### One Syntax to Rule them All
|
|
239
|
+
|
|
240
|
+
###### 7. `get()`, `merge()`, `set()`
|
|
241
|
+
|
|
242
|
+
Since the 'advanced' nested/chained `map-get-z()` and `map-merge-z()` take a variable number of `$keys`, and `map-merge-z()` can accept argument patterns consistent with both merge- and set-style operations, the following aliases can provide unified function syntaxes to replace the 'core' `get()` and `merge()` functions while adding a `set()` function:
|
|
189
243
|
|
|
190
244
|
```scss
|
|
191
245
|
@import "sass-list-maps";
|
|
@@ -203,6 +257,7 @@ Note that in the above 'advanced' examples, the `-z` suffixed functions work lik
|
|
|
203
257
|
@function set($args...) { @return map-merge-z($args...); }
|
|
204
258
|
```
|
|
205
259
|
|
|
260
|
+
|
|
206
261
|
### Caveats
|
|
207
262
|
|
|
208
263
|
There are a few points that bear mentioning/repeating:
|
data/_sass-list-maps.scss
CHANGED
|
@@ -58,11 +58,11 @@
|
|
|
58
58
|
}
|
|
59
59
|
@function map-prev-key($list, $key) {
|
|
60
60
|
$list: list-map-check($list); $keys: map-keys($list);
|
|
61
|
-
@return nth($keys, index($keys, $key) - 1)
|
|
61
|
+
@return nth($keys, index($keys, $key) - 1);
|
|
62
62
|
}
|
|
63
63
|
@function map-next-key($list, $key) {
|
|
64
64
|
$list: list-map-check($list); $keys: map-keys($list);
|
|
65
|
-
@return nth($keys, index($keys, $key) + 1)
|
|
65
|
+
@return nth($keys, index($keys, $key) + 1);
|
|
66
66
|
}
|
|
67
67
|
|
|
68
68
|
// list-map versions of list-map-get(), -merge() and -remove()
|
|
@@ -128,7 +128,6 @@
|
|
|
128
128
|
@function set($args...) { @return map-merge-z($args...); }
|
|
129
129
|
|
|
130
130
|
// new as of 0.9.5: map-inspect()
|
|
131
|
-
// experimental
|
|
132
131
|
|
|
133
132
|
@function map-inspect($list...) {
|
|
134
133
|
@if length($list) == 1 { $list: list-map-check($list...); }
|
|
@@ -146,4 +145,31 @@
|
|
|
146
145
|
$i: $i + 1;
|
|
147
146
|
}
|
|
148
147
|
@return $output + ')';
|
|
149
|
-
}
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
// new as of 0.9.9: map-pretty()
|
|
151
|
+
|
|
152
|
+
@function map-pretty($list, $level: 1) {
|
|
153
|
+
@if length($list) == 1 { $list: list-map-check($list...); }
|
|
154
|
+
@else { $list: list-map-check($list); }
|
|
155
|
+
$indent: $tab; $outdent: $tab;
|
|
156
|
+
@for $n from 1 through $level { $indent: $indent + $tab; }
|
|
157
|
+
@for $n from 1 through $level - 1 { $outdent: $outdent + $tab; }
|
|
158
|
+
$output: '(' + $cr + $indent; $i: 1;
|
|
159
|
+
@each $tuple in $list {
|
|
160
|
+
@if length($tuple) != 2 {
|
|
161
|
+
$output: $output + '#{$tuple}'; }
|
|
162
|
+
@else {
|
|
163
|
+
$key: nth($tuple, 1); $value: nth($tuple, 2);
|
|
164
|
+
@if type-of($value) == 'list' { $output: $output + '#{$key} #{map-pretty($value, $level+1)}'; }
|
|
165
|
+
@else { $output: $output + '#{$key} #{$value}'; } }
|
|
166
|
+
@if $i < length(map-keys($list)) { $output: $output + ',' + $cr + $indent; }
|
|
167
|
+
$i: $i + 1;
|
|
168
|
+
}
|
|
169
|
+
// @return unquote($output + $cr + $outdent + ')'); // replace last line with this one for unquoted output in libsass
|
|
170
|
+
@return $output + $cr + $outdent + ')';
|
|
171
|
+
}
|
|
172
|
+
// aliases of above
|
|
173
|
+
@function map-inspect-pretty($list...) { @return map-pretty($list...); }
|
|
174
|
+
@function map-inspect-p($list...) { @return map-pretty($list...); }
|
|
175
|
+
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: sass-list-maps
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.9.
|
|
4
|
+
version: 0.9.9
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Lu Nelson
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2014-
|
|
11
|
+
date: 2014-04-29 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: compass
|
|
@@ -38,7 +38,8 @@ dependencies:
|
|
|
38
38
|
- - ~>
|
|
39
39
|
- !ruby/object:Gem::Version
|
|
40
40
|
version: 3.2.0
|
|
41
|
-
description: Forward-compatible map
|
|
41
|
+
description: Forward-compatible map (hash) manipulation functions for libsass and
|
|
42
|
+
ruby-sass < 3.3
|
|
42
43
|
email: lunelson@gmail.com
|
|
43
44
|
executables: []
|
|
44
45
|
extensions: []
|
|
@@ -71,5 +72,5 @@ rubyforge_project:
|
|
|
71
72
|
rubygems_version: 2.2.1
|
|
72
73
|
signing_key:
|
|
73
74
|
specification_version: 4
|
|
74
|
-
summary:
|
|
75
|
+
summary: Map (hash) data in libsass and ruby-sass < 3.3
|
|
75
76
|
test_files: []
|