- prelude.ls is a functionally oriented utility library.
- It is powerful and flexible.
- Almost all of its functions are curried.
- It is written in, and is the recommended base library for, LiveScript.
[1 to 5] |> map (^2) |> filter even |> fold (+), 0 #=> 20
Install via npm: npm install prelude-ls. MIT License. Changelog.
Follow @gkzahariev for updates on prelude.ls releases.
You can report bugs and discuss features on the issue page.
Curried functions
Calling with less than the full number of arguments returns a partially applied function.
fold (+), 0, [1 2 3] #=> 6 sum = fold (+), 0 sum [1 2 3] #=> 6 sum [4 5 6] #=> 15
Installation
Install via npm: npm install prelude-ls.
For use in the browser, just include the prelude-browser-min.js file, and then use prelude = require 'prelude-ls'
If you wish, you may use an underscore to refer to the library, _ = require 'prelude-ls', and then _.map f, xs
However, the preferred way to use the library is to grab what you need from it using object deconstruction: {map, filter, lines} = require 'prelude-ls', and then simply map f, xs
Function Reference
The prelude object has several sub-modules, List, Obj, Str, Func, and Num.
Almost all the functions in these modules are added to the main object which you recieve when you require prelude. However, in some cases, especially where the names conflict, you will have to use the functions through the module, eg. Obj.map conflicts with List.map, so map refers to List.map and you must use Obj.map to use the version which operates on objects.
A function which does nothing: it simply returns its single argument. Useful as a placeholder.
id 5 #=> 5
id {} #=> {}
Takes a string (type name) and a value, and returns if the value is of that type. Uses LiveScript's typeof! operator.
is-type 'Undefined' void #=> true
is-type 'Boolean' true #=> true
is-type 'Number' 1 #=> true
is-type 'String' 'hi' #=> true
is-type 'Object' {} #=> true
is-type 'Array' [] #=> true
is-type 'HTMLBodyElement' (document.query-selector 'body') #=> true
Takes its second argument, and replicates it n times to create a new list.
replicate 4 3 #=> [3, 3, 3, 3] replicate 4 'a' #=> ['a', 'a', 'a', 'a'] replicate 0 'a' #=> []
Applies a function to each item in the list and returns the original list. Used for side effects.
each (.push \boom), [['a'] ['b'] ['c']] #=> [['a', 'boom'], ['b', 'boom'], ['c', 'boom']]
Applies a function to each item in the list, and produces a new list with the results. The length of the result is the same length as the input.
map (* 2), [1 to 5] #=> [2, 4, 6, 8, 10]
map (.to-upper-case!), ['ha', 'ma'] #=> ['HA', 'MA']
map (.num), [{num: 3}, {num: 1}] #=> [3, 1]
Returns a new list which contains only the truthy values of the inputted list.
compact [0 1 false true '' 'ha'] #=> [1, true, 'ha']
Returns a new list composed of the items which pass the supplied function's test.
filter (< 3), [1 to 5] #=> [1, 2] filter even, [3, 4, 0] #=> [4, 0]
Like filter, but the new list is composed of all the items which fail the function's test.
reject odd, [1 to 5] #=> [2, 4]
Equivalent to [(filter f, xs), (reject f, xs)], but more efficient, using only one loop.
partition (> 60), [49 58 76 43 88 77 90] #=> [[76 88 77 90],[49 58 43]]
Returns the first item in list to pass the function's test. Returns undefined if all items fail the test.
find odd, [2 4 6 7 8 9 10] #=> 7
The first item of the list. Returns undefined if the list is empty.
head [1 to 5] #=> 1
The last item of the list. Returns undefined if the list is empty.
last [1 to 5] #=> 5
Returns a new list which is the reverse of the inputted one.
reverse [1 2 3] #=> [3, 2, 1]
Returns a new list which contains each value of the inputted list only once.
unique [1 1 1 3 3 6 7 8] #=> [1 3 6 7 8]
Returns a new list which contains each item which has a unique value when applied to the supplied function. If there are multiple different items with the same value when the function is applied, the first item is taken.
unique-by (.length), <[ and here are some words ]> #=> ['and', 'here', 'words']
Takes a list of items, and using the binary function supplied, folds them into a single value. Requires an initial value (the second argument), which will be the starting point, and result in case of an empty list.
fold (+), 0, [1 to 5] #=> 15 product = fold (*), 1
Like fold, except assumes a non-empty list, and thus doesn't require an initial value.
fold1 (+), [1 to 3] #=> 6
Like fold, except folding from the right instead of the left.
foldr (-), 9, [1 2 3 4] #=> 7 foldr (+), 'e', <[ a b c d ]> #=> 'abcde'
Like foldr, except assumes a non-empty list, and thus doesn't require an initial value.
foldr1 (-), [1 2 3 4 9] #=> 7
Unfoldr builds a list from a seed value (the second argument). It takes a function which either returns null if it is done producing the list, or returns [x, y], x which is prepended to the list, and y is used as the next element in the recursive call.
unfoldr (-> if it == 0 then null else [it, it - 1]), 10 #=> [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
Like map, except concatenates the output.
concat-map (-> [1 to it]), [1 2 3] #=> [1, 1, 2, 1, 2, 3]
Flattens a list which contains sub lists and elements of arbitrary depth into a list of elements with no sub lists.
flatten [1, [[2], 3], [4, [[5]]]] #=> [1, 2, 3, 4, 5]
Returns a new list containing the elements which are present in the first list and not in the others. This function is not curried as it takes a variable number of arguments.
difference [1 2 3] [1] #=> [2, 3] difference [1 2 3 4 5] [5 2 10] [9] #=> [1, 3, 4]
Produces a new list containing all the items which are present in all the lists. This function is not curried as it takes a variable number of arguments.
intersection [2 3] [9 8] [12 1] [99] #=> [] intersection [1 2 3] [101 2 1 10] [2 1] [-1 0 1 2] #=> [1, 2] intersection [1 2 3] [2 1 3] [3 1 2] #=> [1, 2, 3]
Produces a new list containing all the elements of all the inputted lists only once. This function is not curried as it takes a variable number of arguments.
union [1 5 7] [3 5] [] #=> [1 5 7 3]
Takes a list of items, and a function, and produces an object whose keys are the result of applying the function to the inputted list, and whose values are the number of its occurrences.
count-by floor, [4.2, 6.1, 6.4] #=> {4: 1, 6: 2}
count-by (.length), <[ one two three ]> #=> {3: 2, 5: 1}
Takes a list of items, and a function, and produces an object whose keys are the result of applying the function to the inputted list, and whose values are a list of all the occurrences.
group-by floor, [4.2, 6.1, 6.4] #=> {4: [4.2], 6: [6.1, 6.4]}
group-by (.length), <[ one two three ]> #=> {3: ['one', 'two'], 5: ['three']}
Returns false if any item in the list is false, otherwise returns true.
and-list [true, 2 + 2 == 4] #=> true and-list [true true false ] #=> false and-list [] #=> true
Returns true if any item in the list is true, otherwise returns false.
or-list [false false true false] #=> true or-list [] #=> false
Returns true if any of the items in the list are true when applied to the test.
any even, [3, 5, 7, 8, 9] #=> true any even, [] #=> false
Returns true if all the items in the list are true when applied to the test.
all (is-type 'String'), <[ ha ma la ]> #=> true all (is-type 'String'), [] #=> true
Takes a binary function which compares two items and returns either a positive number, 0, or a negative number, and sorts the inputted list using that function. The original list is not modified.
f = (x, y) -> | x.length > y.length => 1 | x.length < y.length => -1 | otherwise => 0 sort-with f, <[ three one two ]> #=> ['one','two','three']
Sorts a list using the inputted function for making the comparison between the items.
sort-by (.length), arr #=> ['a', 'ha', 'hey', 'there']
table =
* id: 1
name: 'george'
* id: 2
name: 'mike'
* id: 3
name: 'donald'
sort-by (.name), table
#=> [{"id":3,"name":"donald"},{"id":1,"name":"george"},{"id":2,"name":"mike"}]
Gets the product of all the items in the list.
product [1 2 3] #=> 6 product [] #=> 1
Takes a list of comparable items, and returns the largest of them.
maximum [4 1 9 3] #=> 9
Takes a list of comparable items, and returns the smallest of them.
minimum ['c', 'e', 'a', 'd', 'b'] #=> 'a'
Takes a list of items, and returns the item with the largest value resulting from applying the supplied function to that item.
maximum-by (.length), <[ hi there I am looooong ]> #=> 'looooong'
Takes a list of items, and returns the item with the smallest value resulting from applying the supplied function to that item.
minimum-by (.length), <[ hi there I am looooong ]> #=> 'I'
Like fold, except instead of just returning the final value, returns a list composed of the initial value, the intermediate values, and then the final value. Requires an initial value (the second argument), which is used case of an empty list.
scan (+), 0, [1 to 3] #=> [0, 1, 3, 6]
Like scan, except assumes non-empty list, and thus doesn't require an initial value.
scan1 (+), [1 to 3] #=> [1, 3, 6]
Like scan, except from the right.
scanr (+), 0, [1 to 3] #=> [6, 5, 3, 0]
Like scanr, except assumes non-empty list, and thus doesn't require an initial value.
scanr1 (+), [1 to 3] #=> [6, 5, 3]
Returns the result of dropping the first n items of the list.
drop 2 [1 to 5] #=> [3, 4, 5]
Equivalent to [(take n, xs), (drop n, xs)]
split-at 2 [1 to 5] #=> [[1, 2], [3, 4, 5]]
Takes the first items of the list which pass the test.
take-while odd, [1 3 5 4 8 7 9] #=> [1, 3, 5]
Drops the first items of the list which pass the test.
drop-while even, [2 4 5 6] #=> [5, 6]
Equivalent to [(take-while f, xs), (drop-while f, xs)]
span even, [2 4 5 6] #=> [[2, 4], [5, 6]]
Equivalent to span (not) << f, xs
break-list (== 3), [1 to 5] #=> [[1, 2], [3, 4, 5]]
Zips together its two arguments into a list of lists.
zip [1 2 3] [4 5 6] #=> [[1, 4], [2, 5], [3, 6]]
Zips together its two arguments using a function into a list of resulting values.
zip-with (+), [1 2 3] [4 5 6] #=> [5, 7, 9]
Zips together its arguments into a list of lists. This function is not curried as it takes a variable number of arguments.
zip-all [1 2 3] [4 5 6] [7 8 9] #=> [[1, 4, 7], [2, 5, 8], [3, 6, 9]]
As zip-all, but applies the supplied function to the lists and creates a list of the results. The supplied function must take in as many arguments as there are lists being inputed. This function is not curried as it takes a variable number of arguments.
zip-all-with (-> &0 + &1 + &2), [1 2 3], [3 2 1] [1 1 1] #=> [5, 5, 5]
Gets the element at the nth index (the first argument). If negative, will work from the end.
at 2, [1 2 3 4] #=> 3 at -3, [1 2 3 4] #=> 2
Returns the index of the first occurrence of the supplied element in the list. Returns undefined if the element is not found.
elem-index 'a', <[ c a b a ]> #=> 1
Returns an array of all the indices of the supplied element in the list. Returns an empty list if the element is not found at all.
elem-indices 'a', <[ c a b a ]> #=> [1, 3]
Returns the index of the first element to pass the predicate. Returns undefined if the predicate never passes.
find-index even, [1 2 3 4] #=> 1
Returns an array of all the indices of the elements which pass the predicate. Returns an empty list if the predicate never passes.
find-indices even, [1 2 3 4] #=> [1, 3]
Returns a list of the keys of the object.
keys a: 2, b: 3, c: 9 #=> ['a', 'b', 'c']
Returns a list of the values of the object.
values a: 2, b: 3, c: 9 #=> [2, 3, 9]
Takes a list of pairs and turns them into an object.
pairs-to-obj [['a' 'b'] ['c' 'd'] ['e' 1]] #=> {a: 'b', c: 'd', e: 1}
Takes an object and returns a list of pairs.
obj-to-pairs {a: 'b', c: 'd', e: 1} #=> [['a', 'b'], ['c', 'd'], ['e', 1]]
Takes two lists and zips them up into an object.
lists-to-obj <[ a b c ]> [1 2 3] #=> {a: 1, b: 2, c: 3}
Takes an object and returns a list with two lists, one of its keys, one with its values.
obj-to-lists {a: 1, b: 2, c: 3} #=> [['a', 'b', 'c'], [1, 2, 3]]
Whether the object is empty (has no enumerable keys).
Obj.empty {} #=> true
Applies a function to each value in the object, and returns the original object. Used for side effects.
count = 4
Obj.each (-> count += it), {a: 1, b: 2, c: 3}
count #=> 10
Applies a function to each value of the object, and produces a new object with the same keys and the new values. The size of the result is the same size as the input.
Obj.map (+ 2), {a: 2, b: 3, c: 4} #=> {a: 4, b: 5, c: 6}
Returns a new object which contains only the truthy values of the inputted object.
Obj.compact {a: 0, b: 1, c: false, d: '', e: 'ha'} #=> {b: 1, e: 'ha'}
Returns a new object composed of the values which pass the supplied function's test.
Obj.filter even, {a: 3, b: 4, c: 0} #=> {b: 4, c: 0}
Like filter, but the new object is composed of all the values which fail the function's test.
Obj.reject (== 2), {a:1, b:2} #=> {a: 1}
Equivalent to [(Obj.filter f, xs), (Obj.reject f, xs)], but more efficient, only using one loop.
Obj.partition (== 2), {a:1, b:2, c:3} #=> [{b: 2}, {a: 1, c: 3}]
Returns the first value to pass the test.
Obj.find even, {a:1, b:2, c:3, d:4} #=> 2
Splits a string on a separator into a list of strings.
split '|' '1|2|3' #=> ['1', '2', '3']
Joins a list with the specified separator.
join '|' [1 til 4] #=> '1|2|3'
Splits a string at newlines into a list.
lines '''one
two
three'''
#=> ['one', 'two', 'three']
Joins a list of strings into a single string using newlines.
unlines [\one \two \three] #=> 'one # two # three'
Splits a string at spaces (one or more), returning a list of strings.
words 'hello, what is that?' #=> ['hello,', 'what', 'is', 'that?']
Joins a list of strings into a single string using spaces.
unwords ['one' 'two' 'three'] #=> 'one two three'
Splits a string at every character, returning a list of one character strings.
chars 'hello' #=> ['h', 'e', 'l', 'l', 'o']
Joins a list of strings into a single string using no separator.
unchars ['t' 'h' 'e' 'r' 'e'] #=> 'there' unchars ['ma', 'ma'] #=> 'mama'
Takes its second argument, and repeats it n times to create a new, single, string.
repeat 4 'a' #=> 'aaaa' repeat 2 'ha' #=> 'haha'
Camelizes a string.
camelize 'hi-there' #=> 'hiThere' camelize 'hi_there' #=> 'hiThere'
Dasherizes a string.
dasherize 'hiThere' #=> 'hi-there' dasherize 'FooBar' #=> 'foo-bar' dasherize 'innerHTML' #=> 'inner-HTML'
Returns a slice of the inputted string.
slice 2 4 'hello' #=> 'll'
Returns the result of dropping the first n items of the string.
drop 1 'goat' #=> 'oat'
Equivalent to [(Str.take n, xs), (Str.drop n, xs)]
split-at 4 'hello' #=> ['hell', 'o']
Takes the first items of the string which pass the test.
take-while (in [\a to \d]), 'cabdek' #=> 'cabd'
Drops the first items of the string which pass the test.
drop-while (is \m), 'mmmmmhmm' #=> 'hmm'
Equivalent to [(take-while f, xs), (drop-while f, xs)]
span (is \m), 'mmmmmhmm' #=> ['mmmmm', 'hmm']
Equivalent to span (not) << f, xs
Str.break-str (is \h), 'mmmmmhmm' #=> ['mmmmm', 'hmm']
Returns the application of the supplied list as arguments to the supplied function.
apply (+), [2 3] #=> 5
Returns a curried version of the supplied function. Useful for currying functions from non-LiveScript libraries.
add = (x, y) -> x + y add-curried = curry add add-four = add-curried 4 add-four 2 #=> 6
Returns a function with the arguments flipped.
inverted-power = flip (^) inverted-power 2 3 #=> 9
Fix-point function for anonymous recursion, implemented with the Y combinator.
(fix (fib) -> (n) -> | n <= 1 => 1 | otherwise => fib(n-1) + fib(n-2))(9) #=> 55
Combines two functions: (f, g, x, y) --> f (g x), (g y). Looks nice when applied infix.
same-length = (==) `over` (.length) same-length 'hi', 'me' #=> true same-length 'one', 'boom' #=> false
Caches computed results, speeding up later calls with the same arguments.
f = memoize expensive-function f 2 # slow, but result is then cached f 2 # fast
Takes two arguments which can be compared using >, returns the larger one.
max 3 1 #=> 3 max 'a' 'c' #=> 'c'
Takes two arguments which can be compared using >, returns the smaller one.
min 3 1 #=> 1 min 'a' 'c' #=> 'a'
Takes a number and returns either -1, 0, or 1 depending on the sign of the number.
signum -5 #=> -1 signum 0 #=> 0 signum 9 #=> 1
Number rounded to nearest whole number.
round 0.6 #=> 1 round 0.5 #=> 1 round 0.4 #=> 0
Is it NaN (not a number)? More accurate than the native isNaN function.
is-it-NaN sqrt -1 #=> true