Skip to content

Latest commit

 

History

History
196 lines (121 loc) · 7.6 KB

README.md

File metadata and controls

196 lines (121 loc) · 7.6 KB
Raw

Ramda

A practical functional library for Javascript programmers.

Build Status npm module dependencies ![Gitter](https://badges.gitter.im/Join Chat.svg)

Why Ramda?

There are already several excellent libraries with a functional flavor. Typically, they are meant to be general-purpose toolkits, suitable for working in multiple paradigms. Ramda has a more focused goal. We wanted a library designed specifically for a functional programming style, one that makes it easy to create functional pipelines, one that never mutates user data.

What's Different?

The primary distinguishing features of Ramda are:

  • Ramda emphasizes a purer functional style. Immutability and side-effect free functions are at the heart of its design philosophy. This can help you get the job done with simple, elegant code.

  • Ramda functions are automatically curried. This allows you to easily build up new functions from old ones simply by not supplying the final parameters.

  • The parameters to Ramda functions are arranged to make it convenient for currying. The data to be operated on is generally supplied last.

The last two points together make it very easy to build functions as sequences of simpler functions, each of which transforms the data and passes it along to the next. Ramda is designed to support this style of coding.

Also see Why Ramda?, Why Curry Helps and Hey Underscore, You're Doing It Wrong!.

Philosophy

Using Ramda should feel much like just using Javascript. It is practical, functional Javascript. 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 are plain Javascript objects, and our usual collections are Javascript arrays. We also keep other native features of Javascript, such as functions as objects with properties.

Functional programming is in good part about immutable objects and side-effect free functions. While Ramda does not enforce this, it enables such style to be as frictionless as possible.

We aim for an implementation both clean and elegant, but the API is king. We sacrifice a great deal of implementation elegance for even a slightly cleaner API.

Last but not least, Ramda strives for performance. A reliable and quick implementation wins over any notions of functional purity.

Installation

To use with node:

$ npm install ramda

Then in the console:

var R = 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.13.0/ramda.min.js"></script>

or one of the below links from jsDelivr:

<script src="//cdn.jsdelivr.net/ramda/0.13.0/ramda.min.js"></script>
<script src="//cdn.jsdelivr.net/ramda/0.13/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.

Or you can inject ramda into virtually any unsuspecting web site using this bookmarklet:

javascript:(function(){var el=document.createElement('div'),b=document.getElementsByTagName('body')[0];msg='';el.style.position='fixed';el.style.height='32px';el.style.width='220px';el.style.marginLeft='-110px';el.style.top='0';el.style.left='50%';el.style.padding='5px 10px';el.style.zIndex=1001;el.style.fontSize='12px';el.style.color='#222';el.style.backgroundColor='#f99';if(typeof ramda!='undefined'){msg='This page already using ramda v'+ramda.version;return showMsg()}function getScript(url,success){var script=document.createElement('script');script.src=url;var head=document.getElementsByTagName('head')[0],done=false;script.onload=script.onreadystatechange=function(){if(!done&&(!this.readyState||this.readyState=='loaded'||this.readyState=='complete')){done=true;success();script.onload=script.onreadystatechange=null;head.removeChild(script)}};head.appendChild(script)}getScript('http://cdn.jsdelivr.net/ramda/latest/ramda.min.js',function(){if(typeof ramda=='undefined'){msg='Sorry, but Ramda wasn\'t able to load'}else{msg='This page is now Ramda-fied with v'+ramda.version}return showMsg()});function showMsg(){el.innerHTML=msg;b.appendChild(el);window.setTimeout(function(){if(typeof jQuery=='undefined'){b.removeChild(el)}else{jQuery(el).fadeOut('slow',function(){jQuery(this).remove()})}},2500)}})();

Partial Builds

It is possible to build Ramda with a subset of the functionality to reduce its file size. Ramda's build system supports this with command line flags. For example if you're using R.compose, R.reduce, and R.filter you can create a partial build with:

./scripts/build -- src/compose.js src/reduce.js src/filter.js > dist/ramda.custom.js

This requires having Node/io.js installed.

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.

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.

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.