Project Ramda
A practical functional library for Javascript programmers.
Goals
Using this library should feel as much like using Javascript as
possible. Of course it's functional Javascript, but we're not
introducing lambda expressions in strings, we're not borrowing consed
lists, we're not porting over all of the Clojure functions.
Our basic data structures will be normal Javascript objects, and our
usual collections will be Javascript arrays. We will not try to reach
the point where all the functions have only zero, one, or two arguments.
We will certainly try to keep some of the normal features of Javascript
that seem to be unusual in functional languages, including variable
length function signatures and functions as objects with properties.
Ramda will never be a drop-in replacement for Underscore (or LoDash, or
even a drop-in-and-mechanically-switch-the-parameter-order-everywhere
replacement.) It is intended to work with a different style of coding.
Functional programming is in good part about immutable objects and
side-effect free functions. While Ramda does not expect to do anything to
enforce that style, its code should always work to make that style as
frictionless as possible.
As much as we can, we would like the implementation to be both clean and
elegant. But the API is king: we will sacrifice a great deal of
implementation elegance for even a slightly cleaner API.
Unlike the developers of that silly-named Eweda project, though, this
one will focus also on performance, striving for a reliable and quick
implementation over any notions of functional purity.
Installation
To use with node:
$ npm install ramda
Then in the console:
var ramda = require('ramda');
To use directly in the browser:
<script src="path/to/yourCopyOf/ramda.js"></script>
or the minified version:
<script src="path/to/yourCopyOf/ramda.min.js"></script>
or from a CDN, either cdnjs:
<script src="//cdnjs.cloudflare.com/ajax/libs/ramda/0.7.2/ramda.min.js"></script>
or one of the below links from jsDelivr:
<script src="//cdn.jsdelivr.net/ramda/0.7.2/ramda.min.js"></script>
<script src="//cdn.jsdelivr.net/ramda/0.7/ramda.min.js"></script>
<script src="//cdn.jsdelivr.net/ramda/latest/ramda.min.js"></script>
(note that using latest
is taking a significant risk that ramda API changes could break your code.)
These script tags add the variable ramda
on the browser's global scope.
Documentation
Please review the API documentation.
Introductions
The Name
Ok, so we like sheep. That's all. It's a short name, not already
taken. It could as easily have been eweda
, but then we would be
forced to say eweda lamb!, and no one wants that. For non-English
speakers, lambs are baby sheep, ewes are female sheep, and rams are male
sheep. So perhaps ramda is a grown-up lambda... but probably not.
Structure
Automatic Currying
The functions included should automatically allow for partial
application without an explicit call to lPartial. Many of these operate
on lists. A single list parameter should probably come last, which
might conflict with the design of other libraries that have strong
functional components (I'm looking at you Underscore!)
The idea is that, if foldl has this signature:
var foldl = function(fn, accum, arr) { }
and we have this simple function:
var add = function(a, b) {return a + b;};
then, instead of having to manually call lPartial like this:
var sum = lPartial(foldl, add, 0);
var total = sum([1, 2, 3, 4]);
with ramda, we can just do this:
var sum = foldl(add, 0);
var total = sum([1, 2, 3, 4]);
Running The Test Suite
Console:
To run the test suite from the console, you need to have mocha
installed:
npm install -g mocha
Then from the root of the project, you can just call
mocha
Alternately, if you've installed the dependencies, via:
npm install
npm install -g grunt-cli
then you can run the tests (and get more detailed output) via our grunt
task:
grunt test
Browser:
To run the test suite in the browser, you can simply open test/index.html
.
Alternatively, you can use testem to
test across different browsers (or even headlessly), with livereloading of
tests too. Install testem (npm install -g testem
) and run testem
. Open the
link provided in your browser and you will see the results in your terminal.
If you have PhantomJS installed, you can run testem -l phantomjs
to run the
tests completely headlessly.
So What's With Eweda?
The eweda library was written by
the developers of this library, with similar goals. But that one strove
more for implementation elegance than for practical capabilities. Ramda
is all about giving users real-world tools. Eweda can be seen more as
an academic excercise, mostly proving out what does and doesn't work, and
doing so as elegantly as possible.
Acknowledgements
Thanks to J. C. Phillipps for the Ramda logo.
Ramda logo artwork © 2014 J. C. Phillipps. Licensed Creative Commons
CC BY-NC-SA 3.0.