Here is a powerful toolbox providing you all the functions you need to manipulate your Sass lists.

  • By @import
  • Last update: Nov 18, 2022
  • Comments: 16

SassyLists Gem Version

Here is a powerful toolbox providing you all the functions you need to manipulate your Sass lists. See complete documentation here.

How to use it

Install with Gem

  1. gem install SassyLists

Install with Bower

  1. bower install SassyLists --save-dev
  2. Import the partial in your Sass files

What's in there?

  • sl-chunk(): returns whether list contains $value
  • sl-comma-list(): initializes an empty comma-separated list
  • sl-contain(): returns whether the list contains the value
  • sl-count-values(): counts the number of occurrences of each value of list
  • sl-debug(): returns list as a string
  • sl-every(): returns whether all items from list pass test from given function
  • sl-explode(): explodes a string into a list using a string as a delimiter
  • sl-first(): returns first value in list
  • sl-flatten(): turns multidimensional list into a one-level list
  • sl-has-values(): checks if list is not empty
  • sl-has-multiple-values(): checks if list has more than one value
  • sl-insert-nth(): inserts value at index
  • sl-intersection(): returns a list of shared values across all given lists
  • sl-is-empty(): checks if list is empty
  • sl-is-single(): checks if list has a single value
  • sl-is-symmetrical(): checks if list is symmetrical
  • sl-last(): returns last value in list
  • sl-last-index(): returns last index of value in list
  • sl-loop(): shifts indexes in list
  • sl-prepend(): prepends value to list
  • sl-purge(): removes all false and null values from list
  • sl-random-value(): returns random value from list
  • sl-range(): returns a list of values between 1 and given value
  • sl-remove(): removes value in list
  • sl-remove-duplicates(): removes duplicate values from list
  • sl-remove-nth(): removes value at index
  • sl-replace(): replaces value in list
  • sl-replace-nth(): replaces value at index
  • sl-reverse(): reverses list
  • sl-shuffle(): shuffles list
  • sl-slice(): slices list
  • sl-sort(): sorts list
  • sl-some(): returns whether some values from list pass test from given function
  • sl-sum(): sums all unitless values in list
  • sl-tail(): returns anything but the first element in list
  • sl-to-list(): casts value as list
  • sl-to-map(): casts list as map using indexes as keys
  • sl-to-string(): casts list as string (JS .join())
  • sl-union(): returns a list of values from given lists minus duplicates
  • sl-walk(): applies a function to every value of list

If you feel like an explorer, you can have a look at the code here.

Requirements

  • Sass ~> 3.4

If you are looking for the last version of SassyLists running on Sass 3.2, install 0.4.9.

If you are looking for the last version of SassyLists running on Sass 3.3, install 2.2.5.

Some functions depend on other functions. If you include functions individually, make sure to check for these dependencies in their respective docs.

Also read

Credits

A lot of thanks to all contributors and to at-import for their support.

Github

https://github.com/Team-Sass/SassyLists

Comments(16)

  • 1

    Renamed functions

    Hi Hugo,

    first off I love your functions :) but.. I got conflicts with your function names. Especially function "debug" and "to-string" are no good names in my opinion. Also names of the other functions are really common and it is not clear that they are dealing with lists.

    I tried to run your tests but I got this error message (even without any changes):

    Syntax error: List index is 1 but list has no items for `nth'
            on line 11 of /Users/mm/Projekte/EigeneProjekte/SassyLists/node_modules/bootcamp/dist/utils/_stringify.scss, in `should'
            from line 8 of test/SassyLists/_chunk.scss, in `@content'
            from line 8 of /Users/mm/Projekte/EigeneProjekte/SassyLists/node_modules/bootcamp/dist/core/mixins/_it.scss, in `it'
            from line 7 of test/SassyLists/_chunk.scss, in `@content'
            from line 14 of /Users/mm/Projekte/EigeneProjekte/SassyLists/node_modules/bootcamp/dist/core/mixins/_describe.scss, in `describe'
            from line 1 of test/SassyLists/_chunk.scss
            from line 8 of ./test/test.scss
      Use --trace for backtrace.
    

    There also was a syntax error in your gruntfile (missing comma).

    Greetings

  • 2

    NPM build is broken

    The current npm build command includes /stylesheets/_SassyLists.scss. It contains all the @import statements and thus generates an invalid dist file.

    How did you compiled the latest dist/_SassyLists.scss for the v3.0.0 ?

  • 3

    Roadmap 2.0

    • [x] Prefix all functions (#32)
    • [x] Change all false returns to null in case of error (#34)
    • [x] Add a dependency checker (#6)
    • [x] Add every() and some() functions (#2)
    • [x] Remove Compass dependency
  • 4

    npm install fails on peerDependencies of Bootcamp

    After a fresh clone of the repository, issuing npm install results in:

    npm ERR! peerinvalid The package grunt-contrib-sass does not satisfy its siblings' peerDependencies requirements!
    npm ERR! peerinvalid Peer [email protected] wants [email protected]~0.7.2
    

    Apparently, Bootcamp updated their dependencies to a newer version of grunt-contrib-sass: thejameskyle/[email protected]

    After manually updating SassyLists dependency on grunt-contrib-sass to ~0.7.2 in package.json, I get the following error when running grunt test:

    Running "sass:test" (sass) task
    Syntax error: List index is 1 but list has no items for `nth'
            on line 11 of /Users/leon/werkmap/SassyLists/node_modules/bootcamp/dist/utils/_stringify.scss, in `should'
            from line 8 of test/SassyLists/_chunk.scss, in `@content'
            from line 8 of /Users/leon/werkmap/SassyLists/node_modules/bootcamp/dist/core/mixins/_it.scss, in `it'
            from line 7 of test/SassyLists/_chunk.scss, in `@content'
            from line 14 of /Users/leon/werkmap/SassyLists/node_modules/bootcamp/dist/core/mixins/_describe.scss, in `describe'
            from line 1 of test/SassyLists/_chunk.scss
            from line 8 of ./test/test.scss
      Use --trace for backtrace.
    Warning: Exited with error code 1 Use --force to continue.
    
    Aborted due to warnings.
    

    Do you have any ideas for how to fix this?

  • 5

    empty list

    Hello,

    I either couldn't find it or it is not there.. however I am missing a function like "sl-empty" or "is-empty" or something like that. It may look like this:

    @function sl-empty($list) {
     @if length($list) == 0 {
        @return true;
      } @else {
      @return false;
     }
    }
    
  • 6

    New functions

    Sort values in $list sort($list)

    Returns true if every element in $list satisfies the provided testing $function every($list, $function)

    Returns true if at least one element in $list satisfies the provided testing $function some($list, $function)

  • 7

    Tail should return the rest of the list

    Currently, tail is an alias of last, returning the last item in the list. It is a common idiom to split a list into a head (first item) and tail (rest of the list), especially when using recursion.

    Therefore, I propose tail or rest to return the rest of the list instead of the last item.

    Example usage (based on this gist: https://gist.github.com/jlong/8760275):

    //
    // map-fetch($map, $keys)
    //
    // An easy way to fetch a deep value in a multi-level map. Works much like
    // map-get() except that you pass multiple keys as the second parameter to
    // go down multiple levels in the nested map.
    //
    @function map-fetch($map, $keys) {
      $value: map-get($map, head($keys));
      @if (length($keys) > 1) {
        @return map-fetch($value, tail($keys));
      } @else {
        @return $value;
      }
    }
    

    The code could be as easy as:

    @function tail($list) {
      @return slice($list, 2);
    }
    

    I'd be happy to submit a pull request, if needed.

  • 8

    "Walk" function

    The new call() function in Sass 3.3 could enable us to create walker functions, similar to those in PHP.

    http://www.php.net/manual/en/function.array-walk.php http://sass-lang.com/documentation/Sass/Script/Functions.html#call-instance_method

  • 9

    `compact()` breaks Compass

    I've been receiving a nasty error:

    Function compact takes 1 argument but 10 were passed.

    Took me a while to figure this out.

    Function compact(), used in SassyLists, overrides a Compass function with the same name.

    When you import SassyLists and then try to use Compass' transition() (and a number of other helpers), you receive the aforementioned error.

    SassyLists' compact() is an internal function, so it should be safe to rename it.

  • 10

    Remove purge() from replace()

    Instead of purging all falsy values, why not make $new-value: null remove matches.

    replace( (0, 1, 2, 3), 2);
    => (0, 1, 3) 
    

    https://github.com/Team-Sass/SassyLists/blob/master/stylesheets/SassyLists/_replace.scss#L32


    See: https://github.com/tctcl/ballistic/pull/47/files

  • 11

    Fixed remove-duplicates alias error

    Recursive removal is not supported yet in remove-duplicates but the alias was sending two arguments causing an error. Thus, removed the second argument in and from the remove-duplicates() alias unique().

  • 12

    fix: fix libsass 4 call deprecation warning #63

    Fix the following deprecation warning:

    DEPRECATION WARNING: Passing a string to call() is deprecated and will be illegal
    in Sass 4.0. Use call(get-function("fade")) instead.
    

    Call call() with a function retrieved by the new function get-function.

    Changes:

    • add sl-safe-call-function polyfill for call() with support of both function (LibSass >= 3.5) and function name string (LibSass < 3.5)
    • add a warning message about the deprecated usage of function name string in LibSass >= 3.5
    • use sl-safe-call-function instead of call()

    Closes https://github.com/at-import/SassyLists/issues/63

  • 13

    "Invalid CSS after" at `sl-str-compare` tests

    I got the following error when running tests:

    > mocha test/index.js
    
    /Users/ncoden/Documents/Documents/Projects/Programmation/Web/Forks/sassy-lists/node_modules/node-sass/lib/index.js:439
      throw assign(new Error(), JSON.parse(result.error));
      ^
    
    Error: Invalid CSS after "..., $__ORDER__ ):": expected ")", was "true,"
        at Object.module.exports.renderSync (/Users/ncoden/Documents/Documents/Projects/Programmation/Web/Forks/sassy-lists/node_modules/node-sass/lib/index.js:439:16)
        at Object.module.exports.runSass (/Users/ncoden/Documents/Documents/Projects/Programmation/Web/Forks/sassy-lists/node_modules/sass-true/lib/main.js:34:18)
        at Object.<anonymous> (/Users/ncoden/Documents/Documents/Projects/Programmation/Web/Forks/sassy-lists/test/index.js:5:10)
        at Module._compile (module.js:635:30)
        at Object.Module._extensions..js (module.js:646:10)
        at Module.load (module.js:554:32)
        at tryModuleLoad (module.js:497:12)
        at Function.Module._load (module.js:489:3)
        at Module.require (module.js:579:17)
        at require (internal/module.js:11:18)
        at /Users/ncoden/Documents/Documents/Projects/Programmation/Web/Forks/sassy-lists/node_modules/mocha/lib/mocha.js:220:27
        at Array.forEach (<anonymous>)
        at Mocha.loadFiles (/Users/ncoden/Documents/Documents/Projects/Programmation/Web/Forks/sassy-lists/node_modules/mocha/lib/mocha.js:217:14)
        at Mocha.run (/Users/ncoden/Documents/Documents/Projects/Programmation/Web/Forks/sassy-lists/node_modules/mocha/lib/mocha.js:469:10)
        at Object.<anonymous> (/Users/ncoden/Documents/Documents/Projects/Programmation/Web/Forks/sassy-lists/node_modules/mocha/bin/_mocha:404:18)
        at Module._compile (module.js:635:30)
        at Object.Module._extensions..js (module.js:646:10)
        at Module.load (module.js:554:32)
        at tryModuleLoad (module.js:497:12)
        at Function.Module._load (module.js:489:3)
        at Function.Module.runMain (module.js:676:10)
        at startup (bootstrap_node.js:187:16)
        at bootstrap_node.js:608:3
    

    Error seems to come from the tests on the sl-str-compare function. Something is going wrong and the test variables are exported as pure CSS.

    • node: v8.9.1
    • node-sass: v4.9.0
    • libsass: v3.5.4
  • 14

    Sass 4.0 `call()` deprecation warning

    The following is reported by node-sass v4.8.3

    DEPRECATION WARNING: Passing a string to call() is deprecated and will be illegal
    in Sass 4.0. Use call(get-function("fade")) instead.
    

    Possible Solution

    Like the warning says, use the get-function function inside each call()

  • 15

    Tests do not pass

    Tests for sl-flatten, sl-loop and sl-walk fail. But for flatten and walk, there is no visible differences between the actual result and what is expected.

    See: https://gist.github.com/ncoden/0d39c464193b82090897d335e8329693

  • 16

    Support reduction

    Hello!

    A sl-reduce() function would be great! Check this:

    @function reduce($list, $callback, $accumulator: 0){
        @if(not function-exists($callback)){
            @warn "Cannot find callback '" + inspect($callback) + "'.";
            @return $accumulator;
        }@else{
            @each $item in $list {
                $accumulator: call($callback, $accumulator, $item);
            }
            @return $accumulator;
        }
    }
    

    And a callback:

    @function add($a, $b){
        @return $a + $b;
    }
    

    Could be used like this:

    @debug reduce((1 2 3), add); // yields 6
    @debug reduce(("hello" "world"), add, ""); // yields "hello world"