Skip to content

Commit d494abd

Browse files
committed
Merge pull request #6 from purescript/docs
Docs
2 parents d3d1296 + 229cbf6 commit d494abd

File tree

5 files changed

+394
-16
lines changed

5 files changed

+394
-16
lines changed

Gruntfile.js

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,32 @@ module.exports = function(grunt) {
22

33
"use strict";
44

5-
grunt.initConfig({
6-
5+
grunt.initConfig({
6+
77
libFiles: [
88
"src/**/*.purs",
99
"bower_components/purescript-*/src/**/*.purs",
1010
],
11-
11+
1212
clean: ["output"],
13-
13+
1414
pscMake: ["<%=libFiles%>"],
1515
dotPsci: ["<%=libFiles%>"],
16-
docgen: {
16+
pscDocs: {
1717
readme: {
1818
src: "src/**/*.purs",
1919
dest: "README.md"
2020
}
21-
}
21+
},
22+
23+
jsvalidate: ["output/**/*.js"]
2224

2325
});
2426

2527
grunt.loadNpmTasks("grunt-contrib-clean");
2628
grunt.loadNpmTasks("grunt-purescript");
27-
28-
grunt.registerTask("make", ["pscMake", "dotPsci", "docgen"]);
29+
grunt.loadNpmTasks("grunt-jsvalidate");
30+
31+
grunt.registerTask("make", ["pscMake", "jsvalidate", "dotPsci", "pscDocs"]);
2932
grunt.registerTask("default", ["make"]);
3033
};

README.md

Lines changed: 220 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,55 +4,272 @@
44

55
### Types
66

7-
data Maybe a where
8-
Nothing :: Maybe a
9-
Just :: a -> Maybe a
7+
#### `Maybe`
8+
9+
The `Maybe` type is used to represent optional values and can be seen as
10+
something like a type-safe `null`, where `Nothing` is `null` and `Just x`
11+
is the non-null value `x`.
12+
13+
data Maybe a
14+
= Nothing
15+
| Just a
1016

1117

1218
### Type Class Instances
1319

20+
#### `altMaybe`
21+
22+
The `Alt` instance allows for a choice to be made between two `Maybe`
23+
values with the `<|>` operator, where the first `Just` encountered
24+
is taken.
25+
26+
``` purescript
27+
Just x <|> Just y == Just x
28+
Nothing <|> Just y == Just y
29+
Nothing <|> Nothing == Nothing
30+
```
31+
1432
instance altMaybe :: Alt Maybe
1533

34+
#### `alternativeMaybe`
35+
36+
The `Alternative` instance guarantees that there are both `Applicative` and
37+
`Plus` instances for `Maybe`.
38+
1639
instance alternativeMaybe :: Alternative Maybe
1740

41+
#### `applicativeMaybe`
42+
43+
The `Applicative` instance enables lifting of values into `Maybe` with the
44+
`pure` or `return` function (`return` is an alias for `pure`):
45+
46+
``` purescript
47+
pure x :: Maybe _ == Just x
48+
return x :: Maybe _ == Just x
49+
```
50+
51+
Combining `Functor`'s' `<$>` with `Apply`'s `<*>` and `Applicative`'s
52+
`pure` can be used to pass a mixture of `Maybe` and non-`Maybe` typed
53+
values to a function that does not usually expect them, by using `pure`
54+
for any value that is not already `Maybe` typed:
55+
56+
``` purescript
57+
f <$> Just x <*> pure y == Just (f x y)
58+
```
59+
60+
Even though `pure = Just` it is recommended to use `pure` in situations
61+
like this as it allows the choice of `Applicative` to be changed later
62+
without having to go through and replace `Just` with a new constructor.
63+
1864
instance applicativeMaybe :: Applicative Maybe
1965

66+
#### `applyMaybe`
67+
68+
The `Apply` instance allows functions contained within a `Just` to
69+
transform a value contained within a `Just` using the `(<*>)` operator:
70+
71+
``` purescript
72+
Just f <*> Just x == Just (f x)
73+
```
74+
75+
`Nothing` values are left untouched:
76+
77+
``` purescript
78+
Just f <$> Nothing == Nothing
79+
Nothing <$> Just x == Nothing
80+
```
81+
82+
Combining `Functor`'s' `<$>` with `Apply`'s `<*>` can be used transform a
83+
pure function to take `Maybe`-typed arguments so `f :: a -> b -> c`
84+
becomes `f :: Maybe a -> Maybe b -> Maybe c`:
85+
86+
``` purescript
87+
f <$> Just x <*> Just y == Just (f x y)
88+
```
89+
90+
The `Nothing`-preserving behaviour of both operators means the result of
91+
an expression like the above but where any one of the values is `Nothing`
92+
means the whole result becomes `Nothing` also:
93+
94+
``` purescript
95+
f <$> Nothing <*> Just y == Nothing
96+
f <$> Just x <*> Nothing == Nothing
97+
f <$> Nothing <*> Nothing == Nothing
98+
```
99+
20100
instance applyMaybe :: Apply Maybe
21101

102+
#### `bindMaybe`
103+
104+
The `Bind` instance allows sequencing of `Maybe` values and functions that
105+
return a `Maybe` by using the `>>=` operator:
106+
107+
``` purescript
108+
Just x >>= f = f x
109+
Nothing >>= f = Nothing
110+
```
111+
22112
instance bindMaybe :: Bind Maybe
23113

114+
#### `eqMaybe`
115+
116+
The `Eq` instance allows `Maybe` values to be checked for equality with
117+
`==` and inequality with `/=` whenever there is an `Eq` instance for the
118+
type the `Maybe` contains.
119+
24120
instance eqMaybe :: (Eq a) => Eq (Maybe a)
25121

122+
#### `extendMaybe`
123+
124+
The `Extend` instance allows sequencing of `Maybe` values and functions
125+
that accept a `Maybe a` and return a non-`Maybe` result using the
126+
`<<=` operator.
127+
128+
``` purescript
129+
f <<= Nothing = Nothing
130+
f <<= Just x = Just (f x)
131+
```
132+
26133
instance extendMaybe :: Extend Maybe
27134

135+
#### `functorMaybe`
136+
137+
The `Functor` instance allows functions to transform the contents of a
138+
`Just` with the `<$>` operator:
139+
140+
``` purescript
141+
f <$> Just x == Just (f x)
142+
```
143+
144+
`Nothing` values are left untouched:
145+
146+
``` purescript
147+
f <$> Nothing == Nothing
148+
```
149+
28150
instance functorMaybe :: Functor Maybe
29151

152+
#### `monadMaybe`
153+
154+
The `Monad` instance guarantees that there are both `Applicative` and
155+
`Bind` instances for `Maybe`. This also enables the `do` syntactic sugar:
156+
157+
``` purescript
158+
do
159+
x' <- x
160+
y' <- y
161+
pure (f x' y')
162+
```
163+
164+
Which is equivalent to:
165+
166+
``` purescript
167+
x >>= (\x' -> y >>= (\y' -> pure (f x' y')))
168+
```
169+
30170
instance monadMaybe :: Monad Maybe
31171

172+
#### `monadPlusMaybe`
173+
174+
The `MonadPlus` instance guarantees that there are both `Monad` and
175+
`Alternative` instances for `Maybe`.
176+
32177
instance monadPlusMaybe :: MonadPlus Maybe
33178

179+
#### `ordMaybe`
180+
181+
The `Ord` instance allows `Maybe` values to be compared with
182+
`compare`, `>`, `>=`, `<` and `<=` whenever there is an `Ord` instance for
183+
the type the `Maybe` contains.
184+
185+
`Nothing` is considered to be less than any `Just` value.
186+
34187
instance ordMaybe :: (Ord a) => Ord (Maybe a)
35188

189+
#### `plusMaybe`
190+
191+
The `Plus` instance provides a default `Maybe` value:
192+
193+
``` purescript
194+
empty :: Maybe _ == Nothing
195+
```
196+
36197
instance plusMaybe :: Plus Maybe
37198

199+
#### `semigroupMaybe`
200+
201+
The `Semigroup` instance enables use of the operator `<>` on `Maybe` values
202+
whenever there is a `Semigroup` instance for the type the `Maybe` contains.
203+
The exact behaviour of `<>` depends on the "inner" `Semigroup` instance,
204+
but generally captures the notion of appending or combining things.
205+
206+
``` purescript
207+
Just x <> Just y = Just (x <> y)
208+
Just x <> Nothing = Just x
209+
Nothing <> Just y = Just y
210+
Nothing <> Nothing = Nothing
211+
```
212+
38213
instance semigroupMaybe :: (Semigroup a) => Semigroup (Maybe a)
39214

215+
#### `showMaybe`
216+
217+
The `Show` instance allows `Maybe` values to be rendered as a string with
218+
`show` whenever there is an `Show` instance for the type the `Maybe`
219+
contains.
220+
40221
instance showMaybe :: (Show a) => Show (Maybe a)
41222

42223

43224
### Values
44225

226+
#### `fromMaybe`
227+
228+
Takes a default value, and a `Maybe` value. If the `Maybe` value is
229+
`Nothing` the default value is returned, otherwise the value inside the
230+
`Just` is returned.
231+
232+
``` purescript
233+
fromMaybe default Nothing == default
234+
fromMaybe default (Just x) == x
235+
```
236+
45237
fromMaybe :: forall a. a -> Maybe a -> a
46238

239+
#### `isJust`
240+
241+
Returns `true` when the `Maybe` value was constructed with `Just`.
242+
47243
isJust :: forall a. Maybe a -> Boolean
48244

245+
#### `isNothing`
246+
247+
Returns `true` when the `Maybe` value is `Nothing`.
248+
49249
isNothing :: forall a. Maybe a -> Boolean
50250

251+
#### `maybe`
252+
253+
Takes a default value, a function, and a `Maybe` value. If the `Maybe`
254+
value is `Nothing` the default value is returned, otherwise the function
255+
is applied to the value inside the `Just` and the result is returned.
256+
257+
``` purescript
258+
maybe default f Nothing == default
259+
maybe default f (Just x) == f x
260+
```
261+
51262
maybe :: forall a b. b -> (a -> b) -> Maybe a -> b
52263

53264

54265
## Module Data.Maybe.Unsafe
55266

56267
### Values
57268

269+
#### `fromJust`
270+
271+
A partial function that extracts the value from the `Just` data
272+
constructor. Passing `Nothing` to `fromJust` will throw an error at
273+
runtime.
274+
58275
fromJust :: forall a. Maybe a -> a

package.json

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
{
22
"private": true,
33
"dependencies": {
4-
"grunt": "~0.4.4",
5-
"grunt-purescript": "~0.5.1",
6-
"grunt-contrib-clean": "~0.5.0"
4+
"grunt": "^0.4.5",
5+
"grunt-contrib-clean": "^0.5.0",
6+
"grunt-jsvalidate": "^0.2.2",
7+
"grunt-purescript": "^0.6.0"
78
}
89
}

0 commit comments

Comments
 (0)