sassfp
v1.6.1
Published
Library of functional methods for Sass
Downloads
355
Maintainers
Readme
SassFP
v1.6.1
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.
Installation
SassFP is a node-module and can be installed via
npm install sassfp
Requirements
SassFP requires Sass 3.3 or greater due to its reliance on and ability to
manipulate Sass maps. As of v1.3.1
, it is compatible with Sass 3.5.
- String Methods
- List Methods
- Functional Methods
- Object Methods
- Mathematical Methods
- Misc Methods
- Argument-converted Sass Functions
- Convenience Type Boolean Methods
- Relational Methods
String Methods
prefixStr
($prefix, $str)
Returns $str
prefixed with $prefix
.
prefixStr('selector', 'one'); // => 'selectorone'
suffixStr
($suffix, $str)
Returns $str
with $suffix
appended to it.
suffixStr('selector', 'one'); // => 'oneselector'
explode
($separator, $str)
Converts a string to a list by splitting on $separator.
explode('-', 'selector-one'); // => ('selector', 'one')
pathToMap
($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)))
List Methods
implode
($glue: '', $list: ())
Returns a string where all the members of $list
have been concatenated
together with $glue
between them.
implode('-', ('selector', 'one')); // => 'selector-one'
repeat
($times, $item)
Returns a list where $item
is represented $times
times
repeat(3, 10); // => (10, 10, 10)
slice
($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')
head
($list)
Returns the first member of $list
.
head(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'alex'
tail
($list)
Returns all but the first member of $list
.
tail(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'billy' 'charlie' 'dani' 'elliot'
init
($list)
Returns all but the last member of $list
.
init(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'alex' 'billy' 'charlie' 'dani'
last
($list)
Returns the last member of $list
.
last(('alex' 'billy' 'charlie' 'dani' 'elliot')); // => 'elliot'
flatten
($list...)
Returns a flattened version of $list
.
flatten(#fff, red, (#222, #333)); // => (#fff, red, #222, #333)
partition
($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), ())
contains
($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
intersection
($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); // // => ()
difference
($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')
Functional Methods
always
($val,
$b
)
Returns the first value passed to it. As of v1.5.0
, this accepts a second
optional parameter, $b
, to not only better align with Ramda's signature, but
to also allow it to participate in compositional flows. identity
ought to
be substituted for any previous usage of always
, though there are no plans
to deprecate the single-argument functionality.
always(1) // => 1
always('asdf') // => "asdf"
always(('x', 'y', 'z')) // => ("x", "y", "z")
always('x', 'y') // => "x"
always(true, false) // => true
always(false, true) // => false
identity
($val)
Returns the value passed to it.
identity(1) // => 1
identity('asdf') // => "asdf"
identity(('x', 'y', 'z')) // => ("x", "y", "z")
identity(true) // => true
identity(false) // => false
T
($val...)
Returns true
, regardless of what arguments are passed or how many there are.
T(1) // => true
T('asdf') // => true
T(('x', 'y', 'z')) // => true
T('x', 'y', 'z') // => true
T(true) // => true
T(false) // => true
T() // => true
F
($val...)
Returns false
, regardless of what arguments are passed or how many there are.
F(1) // => false
F('asdf') // => false
F(('x', 'y', 'z')) // => false
F('x', 'y', 'z') // => false
F(true) // => false
F(false) // => false
F() // => false
map
($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 #1a1a1a
As of v1.2.0
, $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 #1a1a1a
Because Sass supports space-separated lists, the commas are optional, and omitting them may increase legibility.
map((darkenby 10%), (#fff, red, #222, #333)); // => #e6e6e6 #cc0000 #090909 #1a1a1a
Most important, however, is that the value(s) provided by iterating over
$list
must always be in the last argument position $fn
expects.
map-with-index
($fn, $list)
Returns a new list where each member of $list
has had function $fn
run against it and its index as two arguments. Works identically to map,
but with the item's index passed as an additional argument to $fn
in the
last argument position and the value provided by $list
in the
second-to-last.
map-with-index(prefixStr, ("alex", "billy", "charlie")); // => ("alex1", "billy2", "charlie3")
map-with-index(add, (4, 5, 6)); // => (5, 7, 9)
filter
($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)
reject
($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)
reduce
($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
As of v1.4.0
, $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.
reduce((sum, 1, 2), 0 (4, 5, 6)); // => 24
Most important, however, is that the value(s) provided by iterating over
$list
must always be in the last argument position $fn
expects and the
accumulator in the second-to-last. So, in the example above, the execution
goes like this:
function add'l values accumulator member outcome
⬇︎ ⬇︎ ⬇︎ ⬇︎ ⬇︎ ⬇︎
sum( 1, 2, 0, 4 ) => 7
sum( 1, 2, 7, 5 ) => 15
sum( 1, 2, 15, 6 ) => 24
In the particular case of sum
, argument order isn't important, but for others it could very well be.
pipe
($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
compose
($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
cond
(($predicates-and-actions-list, $data))
Accepts a two dimensional list of predicate and transformation functions that,
taken together, are read as a series of nested if / else
statements, where the
first true
value encountered has its transformation executed against the
supplied data. Like pipe
and compose
, the data comes in the last
position.
The assumption of both the predicate and transformation functions is that they are unary functions where the provided data serves as the parameter to both functions. Alternatively, n-ary functions may also be used in either assuming that the passed value is coming in the functions' last argument positions, and all other arguments are provided by as a list.
To ensure a return, use the T
function in the last position of
predicate-transformation pairs (so, second-to-last in overall list), coupled
with an always
. As noted with map
, omitting commas in the inner
lists may help with legibility.
@function darkenby($pct, $color) { @return darken($color, $pct); }
@function lightenby($pct, $color) { @return lighten($color, $pct); }
cond((
((equals yellow), (lightenby 20))
((equals red), (darkenby 10))
(T, (always #000))
red
)) // => #cc0000
Object Methods
path
($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
prop
($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
pathOr
($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); // => ':('
propOr
($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); // => ':('
assign
($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)
pick
($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
omit
($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
// )
listPaths
($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")
Mathematical Methods
add
($x, $y)
Adds $y
to $x
.
add(10, 2); // => 12
multiply
($x, $y)
Multiplies $x
by $y
.
multiply(10, 2); // => 20
subtract
($x, $y)
Subtracts $y
from $x
.
subtract(10, 2); // => 8
divide
($x, $y)
Divides $x
by $y
.
divide(10, 2); // => 5
percent
($x, $y)
Returns $x
's percent of $y
.
percent(2, 10); // => 50%
double
($x)
Doubles $x
.
double(10); // => 20
square
($x)
Squares $x
.
square(10); // => 100
inc
($x)
Increments $x
.
inc(10); // => 11
dec
($x)
Decrements $x
.
dec(10); // => 9
sum
($num-list...)
Accepts a list of numbers and returns the sum of them.
sum(10, 5, 2); // => 17
power
($exponent: 1, $num: 1)
Returns the total after multiplying $num
$exponent
times.
power(2, 10); // => 100 (10^2)
power(10, 2); // => 1024 (2^10)
to-decimal-places
($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
Misc Methods
applyUnit
($unit, $val)
Appends $unit
to $val
.
applyUnit(px, 50); // => 50px
applyUnit(em, 50); // => 50em
px
($val)
Shortcut function to apply px
unit.
px(50); // => 50px
em
($val)
Shortcut function to apply em
unit.
em(50); // => 50em
vw
($val)
Shortcut function to apply vw
unit.
vw(50); // => 50vw
vh
($val)
Shortcut function to apply vh
unit.
vh(50); // => 50vh
rem
($val)
Shortcut function to apply rem
unit.
rem(50); // => 50rem
Argument-converted Sass Functions
Existing Sass functions with data-last argument orders.
fpAppend
($item, $list)
Adds an item to the end of a provided list. See Sass append documentation.
fpAppend('charlie', ('alex', 'billy')); // => 'alex' 'billy' 'charlie'
fpJoin
($list2, $list1)
Joins $list2
to the end of $list1
. See Sass join documentation.
fpJoin(('charlie' 'dani'), ('alex', 'billy')); // => 'alex' 'billy' 'charlie' 'dani'
fpNth
($position, $list)
Returns the item at $position
from $list
. See Sass nth documentation.
fpNth(2, ('alex', 'billy')); // => 'billy'
Convenience Type Boolean Methods
is_list
($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
is_color
($val)
Returns whether $val
is a color.
is_color(red); // => true
is_color('red'); // => false
is_string
($val)
Returns whether $val
is a string.
is_string('val'); // => true
is_string(false); // => false
is_boolean
($val)
Returns whether $val
is a boolean.
is_boolean(false); // => true
is_boolean('val'); // => false
is_number
($val)
Returns whether $val
is a number.
is_number(10); // => true
is_number('10'); // => false
is_null
($val)
Returns whether $val
is a null.
is_null(null); // => true
is_null(true); // => false
is_map
($val)
Returns whether $val
is a map.
is_map((header: red)); // => true
is_map((header red)); // => false
isnt_list
($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
isnt_color
($val)
Returns whether $val
is not a color.
isnt_color(red); // => false
isnt_color('red'); // => true
isnt_string
($val)
Returns whether $val
is not a string.
isnt_string('val'); // => false
isnt_string(false); // => true
isnt_boolean
($val)
Returns whether $val
is not a boolean.
isnt_boolean(false); // => false
isnt_boolean('val'); // => true
isnt_number
($val)
Returns whether $val
is not a number.
isnt_number(10); // => false
isnt_number('10'); // => true
isnt_null
($val)
Returns whether $val
is not a null.
isnt_null(null); // => false
isnt_null(true); // => true
isnt_map
($val)
Returns whether $val
is not a map.
isnt_map((header: red)); // => false
isnt_map((header red)); // => true
Relational
equals
($a, $b)
Returns whether $a
and $b
are equivalent (function version of Sass
==
operator).
equals(1, 1); // => true
equals(1, '1'); // => false
equals((header: red), (header: red)); // => true
equals((header red), (header red)); // => true
eq
($a, $b)
Returns whether $a
and $b
are equivalent (alias of equals
).
lt
($a, $b)
Returns whether the first argument is less than the second (function version of
Sass <
operator).
lt(1, 10) // => true
lt(10, 1) // => false
lt(1, 1) // => false
lte
($a, $b)
Returns whether the first argument is less than or equal to the second (function
version of Sass <=
operator).
lte(1, 10) // => true
lte(10, 1) // => false
lte(1, 1) // => true
gt
($a, $b)
Returns whether the first argument is greater than the second (function version
of Sass >
operator).
gt(1, 10) // => false
gt(10, 1) // => true
gt(1, 1) // => false
gte
($a, $b)
Returns whether the first argument is greater than or equal to the second
(function version of Sass >=
operator).
gte(1, 10) // => false
gte(10, 1) // => true
gte(1, 1) // => true