1 | Data.Maybe
|
2 | ==========
|
3 |
|
4 | [![Build Status](https://secure.travis-ci.org/folktale/data.maybe.png?branch=master)](https://travis-ci.org/folktale/data.maybe)
|
5 | [![NPM version](https://badge.fury.io/js/data.maybe.png)](http://badge.fury.io/js/data.maybe)
|
6 | [![Dependencies Status](https://david-dm.org/folktale/data.maybe.png)](https://david-dm.org/folktale/data.maybe)
|
7 | [![stable](http://hughsk.github.io/stability-badges/dist/stable.svg)](http://github.com/hughsk/stability-badges)
|
8 |
|
9 |
|
10 | A structure for values that may not be present, or computations that may
|
11 | fail. `Maybe(a)` explicitly models the effects that implicit in `Nullable`
|
12 | types, thus has none of the problems associated with using `null` or
|
13 | `undefined` — like `NullPointerException` or `TypeError`.
|
14 |
|
15 | Furthermore, being a Monad, `Maybe(a)` can be composed in manners similar to
|
16 | other monads, by using the generic sequencing and composition operations
|
17 | provided for the common interface in
|
18 | [Fantasy Land](https://github.com/fantasyland/fantasy-land).
|
19 |
|
20 |
|
21 | ## Example
|
22 |
|
23 | ```js
|
24 | var Maybe = require('data.maybe')
|
25 |
|
26 | // :: [a], (a -> Bool) -> Maybe(a)
|
27 | function find(collection, predicate) {
|
28 | for (var i = 0; i < collection.length; ++i) {
|
29 | var item = collection[i]
|
30 | if (predicate(item)) return Maybe.Just(item)
|
31 | }
|
32 | return Maybe.Nothing()
|
33 | }
|
34 |
|
35 | var numbers = [-2, -1, 0, 1, 2]
|
36 | var a = find(numbers, function(a){ return a > 5 })
|
37 | var b = find(numbers, function(a){ return a === 0 })
|
38 |
|
39 | // Call a function only if both a and b
|
40 | // have values (sequencing)
|
41 | a.chain(function(x) {
|
42 | return b.chain(function(y) {
|
43 | doSomething(x, y)
|
44 | })
|
45 | })
|
46 |
|
47 | // Transform values only if they're available:
|
48 | a.map(function(x){ return x + 1 })
|
49 | // => Maybe.Nothing
|
50 | b.map(function(x){ return x + 1 })
|
51 | // => Maybe.Just(1)
|
52 |
|
53 | // Use a default value if no value is present
|
54 | a.orElse(function(){ return Maybe.Just(-1) })
|
55 | // => Maybe.Just(-1)
|
56 | b.orElse(function(){ return Maybe.Just(-1) })
|
57 | // => Maybe.Just(0)
|
58 | ```
|
59 |
|
60 |
|
61 | ## Installing
|
62 |
|
63 | The easiest way is to grab it from NPM. If you're running in a Browser
|
64 | environment, you can use [Browserify][]:
|
65 |
|
66 | $ npm install data.maybe
|
67 |
|
68 |
|
69 | ### Using with CommonJS
|
70 |
|
71 | If you're not using NPM, [Download the latest release][release], and require
|
72 | the `data.maybe.umd.js` file:
|
73 |
|
74 | ```js
|
75 | var Maybe = require('data.maybe')
|
76 | ```
|
77 |
|
78 |
|
79 | ### Using with AMD
|
80 |
|
81 | [Download the latest release][release], and require the `data.maybe.umd.js`
|
82 | file:
|
83 |
|
84 | ```js
|
85 | require(['data.maybe'], function(Maybe) {
|
86 | ( ... )
|
87 | })
|
88 | ```
|
89 |
|
90 |
|
91 | ### Using without modules
|
92 |
|
93 | [Download the latest release][release], and load the `data.maybe.umd.js`
|
94 | file. The properties are exposed in the global `folktale.data.Maybe` object:
|
95 |
|
96 | ```html
|
97 | <script src="/path/to/data.maybe.umd.js"></script>
|
98 | ```
|
99 |
|
100 |
|
101 | ### Compiling from source
|
102 |
|
103 | If you want to compile this library from the source, you'll need [Git][],
|
104 | [Make][], [Node.js][], and run the following commands:
|
105 |
|
106 | $ git clone git://github.com/folktale/data.maybe.git
|
107 | $ cd data.maybe
|
108 | $ npm install
|
109 | $ make bundle
|
110 |
|
111 | This will generate the `dist/data.maybe.umd.js` file, which you can load in
|
112 | any JavaScript environment.
|
113 |
|
114 |
|
115 | ## Documentation
|
116 |
|
117 | You can [read the documentation online][docs] or build it yourself:
|
118 |
|
119 | $ git clone git://github.com/folktale/data.maybe.git
|
120 | $ cd data.maybe
|
121 | $ npm install
|
122 | $ make documentation
|
123 |
|
124 | Then open the file `docs/index.html` in your browser.
|
125 |
|
126 |
|
127 | ## Platform support
|
128 |
|
129 | This library assumes an ES5 environment, but can be easily supported in ES3
|
130 | platforms by the use of shims. Just include [es5-shim][] :)
|
131 |
|
132 |
|
133 | ## Licence
|
134 |
|
135 | Copyright (c) 2013 Quildreen Motta.
|
136 |
|
137 | Released under the [MIT licence](https://github.com/folktale/data.maybe/blob/master/LICENCE).
|
138 |
|
139 |
|
140 | [Fantasy Land]: https://github.com/fantasyland/fantasy-land
|
141 | [Browserify]: http://browserify.org/
|
142 | [Git]: http://git-scm.com/
|
143 | [Make]: http://www.gnu.org/software/make/
|
144 | [Node.js]: http://nodejs.org/
|
145 | [es5-shim]: https://github.com/kriskowal/es5-shim
|
146 | [docs]: http://folktale.github.io/data.maybe
|
147 |
|
148 | [release]: https://github.com/folktale/data.maybe/releases/download/v1.0.3/data.maybe-1.0.3.tar.gz
|
149 |
|