Skip to content

Commit 5bb520f

Browse files
garybgaryb
committed
Document the rest
1 parent 135fea5 commit 5bb520f

2 files changed

Lines changed: 95 additions & 32 deletions

File tree

‎README.md‎

Lines changed: 49 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@ is the non-null value `x`.
1919

2020
#### `altMaybe`
2121

22-
The `Alt` instance for `Maybe` allows for a choice to be made between two
23-
`Maybe` values with the `<|>` operator, where the first `Just` encountered
22+
The `Alt` instance allows for a choice to be made between two `Maybe`
23+
values with the `<|>` operator, where the first `Just` encountered
2424
is taken.
2525

2626
``` purescript
@@ -33,18 +33,19 @@ Nothing <|> Nothing == Nothing
3333

3434
#### `alternativeMaybe`
3535

36-
The `Alternative` instance for `Maybe` guarantees that there are both
37-
`Applicative` and `Plus` instances for `Maybe`.
36+
The `Alternative` instance guarantees that there are both `Applicative` and
37+
`Plus` instances for `Maybe`.
3838

3939
instance alternativeMaybe :: Alternative Maybe
4040

4141
#### `applicativeMaybe`
4242

43-
The `Applicative` instance for `Maybe` enables lifting of values into
44-
`Maybe` with the `pure` function:
43+
The `Applicative` instance enables lifting of values into `Maybe` with the
44+
`pure` or `return` function (`return` is an alias for `pure`):
4545

4646
``` purescript
4747
pure x :: Maybe _ == Just x
48+
return x :: Maybe _ == Just x
4849
```
4950

5051
Combining `Functor`'s' `<$>` with `Apply`'s `<*>` and `Applicative`'s
@@ -64,8 +65,8 @@ without having to go through and replace `Just` with a new constructor.
6465

6566
#### `applyMaybe`
6667

67-
The `Apply` instance for `Maybe` allows functions contained within a `Just`
68-
to transform a value contained within a `Just` using the `(<*>)` operator:
68+
The `Apply` instance allows functions contained within a `Just` to
69+
transform a value contained within a `Just` using the `(<*>)` operator:
6970

7071
``` purescript
7172
Just f <*> Just x == Just (f x)
@@ -78,8 +79,9 @@ Just f <$> Nothing == Nothing
7879
Nothing <$> Just x == Nothing
7980
```
8081

81-
Combining `Functor`'s' `<$>` with `Apply`'s `<*>` can be used to pass
82-
multiple `Maybe` values to a function that does not usually expect them:
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`:
8385

8486
``` purescript
8587
f <$> Just x <*> Just y == Just (f x y)
@@ -99,8 +101,8 @@ f <$> Nothing <*> Nothing == Nothing
99101

100102
#### `bindMaybe`
101103

102-
The `Bind` instance for `Maybe` allows sequencing of `Maybe` values and
103-
functions that return a `Maybe` by using the `>>=` operator:
104+
The `Bind` instance allows sequencing of `Maybe` values and functions that
105+
return a `Maybe` by using the `>>=` operator:
104106

105107
``` purescript
106108
Just x >>= f = f x
@@ -119,6 +121,10 @@ type the `Maybe` contains.
119121

120122
#### `extendMaybe`
121123

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+
122128
``` purescript
123129
f <<= Nothing = Nothing
124130
f <<= Just x = Just (f x)
@@ -128,8 +134,8 @@ f <<= Just x = Just (f x)
128134

129135
#### `functorMaybe`
130136

131-
The `Functor` instance for `Maybe` allows functions to transform the
132-
contents of a `Just` with the `<$>` operator:
137+
The `Functor` instance allows functions to transform the contents of a
138+
`Just` with the `<$>` operator:
133139

134140
``` purescript
135141
f <$> Just x == Just (f x)
@@ -145,10 +151,29 @@ f <$> Nothing == Nothing
145151

146152
#### `monadMaybe`
147153

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+
148170
instance monadMaybe :: Monad Maybe
149171

150172
#### `monadPlusMaybe`
151173

174+
The `MonadPlus` instance guarantees that there are both `Monad` and
175+
`Alternative` instances for `Maybe`.
176+
152177
instance monadPlusMaybe :: MonadPlus Maybe
153178

154179
#### `ordMaybe`
@@ -163,8 +188,7 @@ the type the `Maybe` contains.
163188

164189
#### `plusMaybe`
165190

166-
The `Plus` instance for `Maybe` enables a `Maybe` value to be constructed
167-
from no other values with the `empty` function:
191+
The `Plus` instance provides a default `Maybe` value:
168192

169193
``` purescript
170194
empty :: Maybe _ == Nothing
@@ -174,6 +198,11 @@ empty :: Maybe _ == Nothing
174198

175199
#### `semigroupMaybe`
176200

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+
177206
``` purescript
178207
Just x <> Just y = Just (x <> y)
179208
Just x <> Nothing = Just x
@@ -185,6 +214,10 @@ Nothing <> Nothing = Nothing
185214

186215
#### `showMaybe`
187216

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+
188221
instance showMaybe :: (Show a) => Show (Maybe a)
189222

190223

‎src/Data/Maybe.purs‎

Lines changed: 46 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,8 @@ isJust = maybe false (const true)
4242
isNothing :: forall a. Maybe a -> Boolean
4343
isNothing = maybe true (const false)
4444

45-
-- | The `Functor` instance for `Maybe` allows functions to transform the
46-
-- | contents of a `Just` with the `<$>` operator:
45+
-- | The `Functor` instance allows functions to transform the contents of a
46+
-- | `Just` with the `<$>` operator:
4747
-- |
4848
-- | ``` purescript
4949
-- | f <$> Just x == Just (f x)
@@ -58,8 +58,8 @@ instance functorMaybe :: Functor Maybe where
5858
(<$>) fn (Just x) = Just (fn x)
5959
(<$>) _ _ = Nothing
6060

61-
-- | The `Apply` instance for `Maybe` allows functions contained within a `Just`
62-
-- | to transform a value contained within a `Just` using the `(<*>)` operator:
61+
-- | The `Apply` instance allows functions contained within a `Just` to
62+
-- | transform a value contained within a `Just` using the `(<*>)` operator:
6363
-- |
6464
-- | ``` purescript
6565
-- | Just f <*> Just x == Just (f x)
@@ -72,8 +72,9 @@ instance functorMaybe :: Functor Maybe where
7272
-- | Nothing <$> Just x == Nothing
7373
-- | ```
7474
-- |
75-
-- | Combining `Functor`'s' `<$>` with `Apply`'s `<*>` can be used to pass
76-
-- | multiple `Maybe` values to a function that does not usually expect them:
75+
-- | Combining `Functor`'s' `<$>` with `Apply`'s `<*>` can be used transform a
76+
-- | pure function to take `Maybe`-typed arguments so `f :: a -> b -> c`
77+
-- | becomes `f :: Maybe a -> Maybe b -> Maybe c`:
7778
-- |
7879
-- | ``` purescript
7980
-- | f <$> Just x <*> Just y == Just (f x y)
@@ -92,11 +93,12 @@ instance applyMaybe :: Apply Maybe where
9293
(<*>) (Just fn) x = fn <$> x
9394
(<*>) Nothing _ = Nothing
9495

95-
-- | The `Applicative` instance for `Maybe` enables lifting of values into
96-
-- | `Maybe` with the `pure` function:
96+
-- | The `Applicative` instance enables lifting of values into `Maybe` with the
97+
-- | `pure` or `return` function (`return` is an alias for `pure`):
9798
-- |
9899
-- | ``` purescript
99100
-- | pure x :: Maybe _ == Just x
101+
-- | return x :: Maybe _ == Just x
100102
-- | ```
101103
-- |
102104
-- | Combining `Functor`'s' `<$>` with `Apply`'s `<*>` and `Applicative`'s
@@ -114,8 +116,8 @@ instance applyMaybe :: Apply Maybe where
114116
instance applicativeMaybe :: Applicative Maybe where
115117
pure = Just
116118

117-
-- | The `Alt` instance for `Maybe` allows for a choice to be made between two
118-
-- | `Maybe` values with the `<|>` operator, where the first `Just` encountered
119+
-- | The `Alt` instance allows for a choice to be made between two `Maybe`
120+
-- | values with the `<|>` operator, where the first `Just` encountered
119121
-- | is taken.
120122
-- |
121123
-- | ``` purescript
@@ -127,21 +129,20 @@ instance altMaybe :: Alt Maybe where
127129
(<|>) Nothing r = r
128130
(<|>) l _ = l
129131

130-
-- | The `Plus` instance for `Maybe` enables a `Maybe` value to be constructed
131-
-- | from no other values with the `empty` function:
132+
-- | The `Plus` instance provides a default `Maybe` value:
132133
-- |
133134
-- | ``` purescript
134135
-- | empty :: Maybe _ == Nothing
135136
-- | ```
136137
instance plusMaybe :: Plus Maybe where
137138
empty = Nothing
138139

139-
-- | The `Alternative` instance for `Maybe` guarantees that there are both
140-
-- | `Applicative` and `Plus` instances for `Maybe`.
140+
-- | The `Alternative` instance guarantees that there are both `Applicative` and
141+
-- | `Plus` instances for `Maybe`.
141142
instance alternativeMaybe :: Alternative Maybe
142143

143-
-- | The `Bind` instance for `Maybe` allows sequencing of `Maybe` values and
144-
-- | functions that return a `Maybe` by using the `>>=` operator:
144+
-- | The `Bind` instance allows sequencing of `Maybe` values and functions that
145+
-- | return a `Maybe` by using the `>>=` operator:
145146
-- |
146147
-- | ``` purescript
147148
-- | Just x >>= f = f x
@@ -151,10 +152,31 @@ instance bindMaybe :: Bind Maybe where
151152
(>>=) (Just x) k = k x
152153
(>>=) Nothing _ = Nothing
153154

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

172+
-- | The `MonadPlus` instance guarantees that there are both `Monad` and
173+
-- | `Alternative` instances for `Maybe`.
156174
instance monadPlusMaybe :: MonadPlus Maybe
157175

176+
-- | The `Extend` instance allows sequencing of `Maybe` values and functions
177+
-- | that accept a `Maybe a` and return a non-`Maybe` result using the
178+
-- | `<<=` operator.
179+
-- |
158180
-- | ``` purescript
159181
-- | f <<= Nothing = Nothing
160182
-- | f <<= Just x = Just (f x)
@@ -163,6 +185,11 @@ instance extendMaybe :: Extend Maybe where
163185
(<<=) _ Nothing = Nothing
164186
(<<=) f x = Just (f x)
165187

188+
-- | The `Semigroup` instance enables use of the operator `<>` on `Maybe` values
189+
-- | whenever there is a `Semigroup` instance for the type the `Maybe` contains.
190+
-- | The exact behaviour of `<>` depends on the "inner" `Semigroup` instance,
191+
-- | but generally captures the notion of appending or combining things.
192+
-- |
166193
-- | ``` purescript
167194
-- | Just x <> Just y = Just (x <> y)
168195
-- | Just x <> Nothing = Just x
@@ -174,6 +201,9 @@ instance semigroupMaybe :: (Semigroup a) => Semigroup (Maybe a) where
174201
(<>) x Nothing = x
175202
(<>) (Just x) (Just y) = Just (x <> y)
176203

204+
-- | The `Show` instance allows `Maybe` values to be rendered as a string with
205+
-- | `show` whenever there is an `Show` instance for the type the `Maybe`
206+
-- | contains.
177207
instance showMaybe :: (Show a) => Show (Maybe a) where
178208
show (Just x) = "Just (" ++ show x ++ ")"
179209
show Nothing = "Nothing"

0 commit comments

Comments
 (0)