A set of utilities inspired by Ramda, lodash FP, and other Functional libraries for Sass.
Like Ramda, all the functions in SassFP are iteratee-first, data-last. Some native Sass methods have been re-supplied here with that argument order, but, so far, only those that I've personally needed in projects.
- String Methods
- List Methods
- Functional Methods
- Object Methods
- Mathematical Methods
- Misc Methods
- Argument-converted Sass Functions
- Convenience Type Boolean Methods
($prefix, $str)
Returns $str prefixed with $prefix.
prefixStr('selector', 'one'); // => 'selectorone'($suffix, $str)
Returns $str with $suffix appended to it.
suffixStr('selector', 'one'); // => 'oneselector'($separator, $str)
Converts a string to a list by splitting on $separator.
explode('-', 'selector-one'); // => ('selector', 'one')($path, $val)
Converts a dot-delimited string and any value into a Sass map with that same object heirarchy.
pathToMap('x', 10px); => (x: 10px)
pathToMap('x.y', 10px); => (x: (y: 10px))
pathToMap('x.y.z', 10px); => (x: (y: (z: 10px)))($glue: '', $list: ())
Returns a string where all the members of $list have been concatenated together with $glue between them.
implode('-', ('selector', 'one')); // => 'selector-one'($times, $item)
Returns a list where $item is represented $times times
repeat(3, 10); // => (10, 10, 10)($start, $end, $list)
Returns $list's members beginning at position $start and ending at $end.
slice(3, 5, ('alex', 'billy', 'charlie', 'dani', 'elliot')); // => ('charlie', 'dani', 'elliot')($list)
Returns the first member of $list.
head(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'alex'($list)
Returns all but the first member of $list.
tail(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'billy' 'charlie' 'dani' 'elliot'($list)
Returns all but the last member of $list.
init(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'alex' 'billy' 'charlie' 'dani'($list)
Returns the last member of $list.
last(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'elliot'($list...)
Returns a flattened version of $list.
flatten(#fff, red, (#222, #333)); // => (#fff, red, #222, #333)($predicate, $list)
Returns 2-dimensional list where the first member contains all the members of $list for which $predicate is true, and the second, all those for which it is false.
partition(gt5, (4,5,6,7)); // => ((6 7), (4 5))
partition(gt5, (0,1,2,3)); // => ((), (0 1 2 3))
partition(gt5, (6,7,8,9)); // => ((6 7 8 9), ())($item, $list)
Returns a Boolean whether $item is in $list.
$strlist: ('alex' 'billy' 'charlie' 'dani' 'elliot');
contains('alex', $strlist); => true
contains('allen', $strlist); => false
contains('billy', $strlist); => true($list1, $list2)
Returns a new list of what both $list1 and $list2 have in common. Inverse of difference.
$strlist: ('alex' 'billy' 'charlie' 'dani' 'elliot');
intersection(('alex', 'billy', 'allen'), $strlist); // // => ('alex' 'billy')
intersection(('alex.a', 'billy', 'allen'), $strlist); // // => ('billy')
intersection(('alex.a', 'allen'), $strlist); // // => ()($list1, $list2)
Returns new list of what $list1 and $list2 do not have in common. Inverse of intersection.
$strlist: ('alex' 'billy' 'charlie' 'dani' 'elliot');
difference(('alex' 'billy'), $strlist); // => ()
difference(('alex' 'billy' 'allen'), $strlist); // => ('allen')
difference(('alex.a' 'billy' 'allen'), $strlist); // => ('alex.a' 'allen')($val)
Returns the value passed to it.
always(1) // => 1
always('asdf') // => "asdf"
always(('x', 'y', 'z')) // => ("x", "y", "z")
always(true) // => true
always(false) // => false($fn, $list)
Returns a new list where each member of $list has had function $fn run against it.
@function darkenbyten($color) {
@return darken($color, 10%);
}
map(darkenbyten, (#fff, red, #222, #333)); // => #e6e6e6 #cc0000 #090909 #1a1a1aAs of v1.2, $fn may itself be a list where the first member is the function to be run against each member of $list, and the others are extra arguments that the function would require in effect allowing functions to be decorated.
@function darkenby($pct, $color) {
@return darken($color, $pct);
}
map((darkenby, 10%), (#fff, red, #222, #333)); // => #e6e6e6 #cc0000 #090909 #1a1a1aBecause Sass supports space-separated lists, the commas are optional, and omitting them may increase legibility and in any case is equivalent.
map((darkenby 10%), (#fff, red, #222, #333)); // => #e6e6e6 #cc0000 #090909 #1a1a1aMost important, however, is that the value(s) provided by iterating over list must always be in the last argument position $fn expects.
($predicate, $list)
Returns a new list where $predicate returns true for members of $list. Inverse of reject.
@function gt5($val) {
@return $val > 5;
}
filter(gt5, (4,5,6,7)); // => (6, 7)($predicate, $list)
Returns a new list where $predicate returns false for members of $list. Inverse of filter.
reject(gt5, (4,5,6,7)); // => (4, 5)($fn, $initial, $list)
Accumulates the result of running each member of $list through $fn starting with the $initial value and $list's first member.
reduce(prefixStr, '.', ('alex', 'billy', 'charlie')); // => ".alexbillycharlie"
reduce(suffixStr, '', ('alex', 'billy', 'charlie')); // => "charliebillyalex"
reduce(add, 0, (4,5,6)); // => 15($params...)
Accepts a list of arguments where the last item is the initial data and the others are a sequence of functions to run. Returns the result of each of the functions being run on the successive results from first to last. The very last item must be the data being operated on. Functions being passed in with additional parameters take the form of sub-lists.
pipe(
flatten,
(map, darkenbyten),
(#fff, red, (#222, #333))
); // => #e6e6e6 #cc0000 #090909 #1a1a1a($params...)
Same as pipe, but functions run in reverse order. Initial data remains last argument.
compose(
unquote,
(prefixStr, '.'),
(implode, '-'),
(join, ('d', 'e')),
('a', 'b', 'c')
); // => .d-e-a-b-c
compose(
double,
(reduce, add, 0),
(map, square),
(4,5,6)
); // => 154($key-list, $map)
Allows for getting at nested attributes in a Sass map using list syntax. Ensures a null return for any unrecognized paths.
$colors: (header:(one: #333, two: #444), footer: #666);
path(('header', 'two'), $colors); // => #444
path(('footer'), $colors); // => #666
path(('header', 'two', 'three', 'four'), $colors); // => null($path, $map)
Allows for getting at nested attributes in a Sass map using dot syntax. Ensures a null return for any unrecognized paths.
$colors: (header:(one: #333, two: #444), footer: #666);
prop('header.two', $colors); // => #444
prop('footer', $colors); // => #666
prop('body', $colors); // => null($fallback, $key-list, $map)
Returns the value of a path lookup when successful, and returns a provided fallback when not.
$colors: (header:(one: #333, two: #444), footer: #666);
pathOr(':(', ('header', 'two'), $colors); // => #444
pathOr(':(', ('body'), $colors); // => ':('
pathOr(':(', ('header', 'two', 'three', 'four'), $colors); // => ':('($fallback, $path, $map)
Returns the value of a prop lookup when successful, and returns a provided fallback when not.
$colors: (header:(one: #333, two: #444), footer: #666);
propOr(':(', 'header.two', $colors); // => #444
propOr(':(', 'footer', $colors); // => #666
propOr(':(', 'body', $colors); // => ':('($map1, $map2)
Merges 2 deeply-nested map objects.
$colors: (header:(one: #333, two: #444), footer: #666);
assign($colors, (header: (one: red))); // => (header:(one: red, two: #444), footer: #666)
assign($colors, (header: (three: red))); // => (header:(one: #333, two: #444, three: red), footer: #666)($key-list, $map)
Creates new map object from $map selecting keys provided by $key-list.
$colors: (header:(one: #333, two: #444), footer: #666);
pick('footer', $colors); // => (footer: #666)
pick('header.one', $colors); // => (header:(one: #333))
pick(('header', 'footer'), $colors); // same as original($key-list, $map)
Creates new map object from the provided one, then removing a specified list of keys.
omit(
('header.one', 'header.three.four'),
(header: (
one: #333,
two: #444,
three: (
four: red,
five: blue
)
),
footer: #666
));
// =>
// (header: (
// two: #444,
// three: (
// five: blue
// )
// ),
// footer: #666
// )($map)
Creates a flat, dot-delimited list of all the paths of $map.
$colors: (header:(one: #333, two: #444), footer: #666);
listPaths($colors); // => ("header" "header.one" "header.two" "footer")($x, $y)
Adds $y to $x.
add(10, 2); // => 12($x, $y)
Multiplies $x by $y.
multiply(10, 2); // => 20($x, $y)
Subtracts $y from $x.
subtract(10, 2); // => 8($x, $y)
Divides $x by $y.
divide(10, 2); // => 5($x, $y)
Returns $x's percent of $y.
percent(2, 10); // => 50%($x)
Doubles $x.
double(10); // => 20($x)
Squares $x.
square(10); // => 100($x)
Increments $x.
inc(10); // => 11($x)
Decrements $x.
dec(10); // => 9($num-list...)
Accepts a list of numbers and returns the sum of them.
sum(10, 5, 2); // => 17($exponent: 1, $num: 1)
Returns the total after multiplying $num $exponent times.
power(2, 10); // => 100 (10^2)
power(10, 2); // => 1024 (2^10)($digits: 2, $num: 1)
Returns $num to $digits number of significant digits dropping anything beyond it. $digits is 2 by default since Sass has a default of returning 3 significant digits.
to-decimal-places(2, 10.129); // => 10.12($unit, $val)
Appends $unit to $val.
applyUnit(px, 50); // => 50px
applyUnit(em, 50); // => 50em($val)
Shortcut function to apply px unit.
px(50); // => 50px($val)
Shortcut function to apply em unit.
em(50); // => 50em($val)
Shortcut function to apply vw unit.
vw(50); // => 50vw($val)
Shortcut function to apply vh unit.
vh(50); // => 50vh($val)
Shortcut function to apply rem unit.
rem(50); // => 50remExisting Sass functions with data-last argument orders.
($item, $list)
Adds an item to the end of a provided list. See Sass append documentation.
fpAppend('charlie', ('alex', 'billy')); // => 'alex' 'billy' 'charlie'($list2, $list1)
Joins $list2 to the end of $list1. See Sass join documentation.
fpJoin(('charlie' 'dani'), ('alex', 'billy')); // => 'alex' 'billy' 'charlie' 'dani'($position, $list)
Returns the item at $position from $list. See Sass nth documentation.
fpNth(2, ('alex', 'billy')); // => 'billy'($val)
Returns whether $val is a list.
is_list((#fff, red, #222, #333)); // => true
is_list(#fff red #222 #333); // => true
is_list(#fff); // => false($val)
Returns whether $val is a color.
is_color(red); // => true
is_color('red'); // => false($val)
Returns whether $val is a string.
is_string('val'); // => true
is_string(false); // => false($val)
Returns whether $val is a boolean.
is_boolean(false); // => true
is_boolean('val'); // => false($val)
Returns whether $val is a number.
is_number(10); // => true
is_number('10'); // => false($val)
Returns whether $val is a null.
is_null(null); // => true
is_null(true); // => false($val)
Returns whether $val is a map.
is_map((header: red)); // => true
is_map((header red)); // => false($val)
Returns whether $val is not a list.
isnt_list((#fff, red, #222, #333)); // => false
isnt_list(#fff red #222 #333); // => false
isnt_list(#fff); // => true($val)
Returns whether $val is not a color.
isnt_color(red); // => false
isnt_color('red'); // => true($val)
Returns whether $val is not a string.
isnt_string('val'); // => false
isnt_string(false); // => true($val)
Returns whether $val is not a boolean.
isnt_boolean(false); // => false
isnt_boolean('val'); // => true($val)
Returns whether $val is not a number.
isnt_number(10); // => false
isnt_number('10'); // => true($val)
Returns whether $val is not a null.
isnt_null(null); // => false
isnt_null(true); // => true($val)
Returns whether $val is not a map.
isnt_map((header: red)); // => false
isnt_map((header red)); // => true($a, $b)
Returns whether $a and $b are equivalent.
equals(1, 1); // => true
equals(1, '1'); // => false
equals((header: red), (header: red)); // => true
equals((header red), (header red)); // => true