6328c3a · rowtype-yoga/purescript-native

git.iko.soy/rowtype-yoga/purescript-native

on golang help sign in

Merge pull request #932 from purescript/prelude-docs

6328c3aPhil Freeman12 years ago

prelude/README.md+158−25

compare with golang

unifiedsplit

@@ -72,6 +72,8 @@ element `id`, just composable morphisms.

73- Associativity: `p <<< (q <<< r) = (p <<< q) <<< r`

75+One example of a `Semigroupoid` is the function type constructor `(->)`, with `(<<<)` defined

76+as function composition.

76#### `semigroupoidArr`

78#### `semigroupoidArr`

@@ -86,6 +88,7 @@ instance semigroupoidArr :: Semigroupoid Prim.Function

86(>>>) :: forall a b c d. (Semigroupoid a) => a b c -> a c d -> a b d

88(>>>) :: forall a b c d. (Semigroupoid a) => a b c -> a c d -> a b d

87```

89```

91+Forwards composition, or `(<<<)` with its arguments reversed.

90#### `Category`

93#### `Category`

@@ -160,12 +163,9 @@ length (groupBy productCategory (filter isInStock (products)))

160(:) :: forall a. a -> [a] -> [a]

163(:) :: forall a. a -> [a] -> [a]

161```

164```

162

165

163−Attaches an element to the front of a list.

166+An infix alias for `cons`.

164−

165−```purescript

166−1 : [2, 3, 4] = [1, 2, 3, 4]

167−```

168

167

168+Note, the running time of this function is `O(n)`.

169

170#### `cons`

171

@@ -173,6 +173,13 @@ Attaches an element to the front of a list.

173cons :: forall a. a -> [a] -> [a]

174```

175

176+Attaches an element to the front of an array, creating a new array.

177+

178+```purescript

179+cons 1 [2, 3, 4] = [1, 2, 3, 4]

180+```

181+

182+Note, the running time of this function is `O(n)`.

176

183

177#### `Show`

184#### `Show`

178

185

@@ -181,6 +188,10 @@ class Show a where

181 show :: a -> String

188 show :: a -> String

182```

189```

183

190

191+The `Show` type class represents those types which can be converted into a human-readable `String` representation.

192+

193+While not required, it is recommended that for any expression `x`, the string `show x` be executable PureScript code

194+which evaluates to the same value as the expression `x`.

184

195

185#### `showUnit`

196#### `showUnit`

186

197

@@ -224,10 +235,12 @@ class Functor f where

224 (<$>) :: forall a b. (a -> b) -> f a -> f b

235 (<$>) :: forall a b. (a -> b) -> f a -> f b

225```

236```

226

237

227−A `Functor` is intuitively a type which can be mapped over, and more formally a mapping

238+A `Functor` is a type constructor which supports a mapping operation `(<$>)`.

228−between [`Category`](#category)s that preserves structure.

239+

240+`(<$>)` can be used to turn functions `a -> b` into functions `f a -> f b` whose argument and return

241+types use the type constructor `f` to represent some computational context.

229

242

230−`Functor`s should obey the following rules.

243+`Functor` instances should satisfy the following laws:

231

244

232- Identity: `(<$>) id = id`

245- Identity: `(<$>) id = id`

233- Composition: `(<$>) (f <<< g) = (<$> f) <<< (<$> g)`

246- Composition: `(<$>) (f <<< g) = (<$> f) <<< (<$> g)`

@@ -239,6 +252,11 @@ between [`Category`](#category)s that preserves structure.

239(<#>) :: forall f a b. (Functor f) => f a -> (a -> b) -> f b

252(<#>) :: forall f a b. (Functor f) => f a -> (a -> b) -> f b

240```

253```

241

254

255+`(<#>)` is `(<$>)` with its arguments flipped. For example:

256+

257+```purescript

258+[1, 2, 3] <#> \n -> n * n

259+```

242

260

243#### `void`

261#### `void`

244

262

@@ -246,6 +264,16 @@ between [`Category`](#category)s that preserves structure.

246void :: forall f a. (Functor f) => f a -> f Unit

264void :: forall f a. (Functor f) => f a -> f Unit

247```

265```

248

266

267+The `void` function is used to ignore the type wrapped by a [`Functor`](#functor), replacing it with `Unit` and

268+keeping only the type information provided by the type constructor itself.

269+

270+`void` is often useful when using `do` notation to change the return type of a monadic computation:

271+

272+```purescript

273+main = forE 1 10 \n -> void do

274+ print n

275+ print (n * n)

276+```

249

277

250#### `Apply`

278#### `Apply`

251

279

@@ -254,13 +282,24 @@ class (Functor f) <= Apply f where

254 (<*>) :: forall a b. f (a -> b) -> f a -> f b

282 (<*>) :: forall a b. f (a -> b) -> f a -> f b

255```

283```

256

284

257−`Apply`s are intuitively [`Applicative`](#applicative)s less `pure`, and more formally a

285+The `Apply` class provides the `(<*>)` which is used to apply a function to an argument under a type constructor.

258−strong lax semi-monoidal endofunctor.

286+

287+`Apply` can be used to lift functions of two or more arguments to work on values wrapped with the type constructor `f`.

288+It might also be understood in terms of the `lift2` function:

289+

290+```purescript

291+lift2 :: forall f a b c. (Apply f) => (a -> b -> c) -> f a -> f b -> f c

292+lift2 f a b = f <$> a <*> b

293+```

294+

295+`(<*>)` is recovered from `lift2` as `lift2 ($)`. That is, `(<*>)` lifts the function application operator `($)` to arguments

296+wrapped with the type constructor `f`.

259

297

260−`Apply`s should obey the following rule.

298+`Apply` instances should satisfy the following law:

261

299

262- Associative Composition: `(<<<) <$> f <*> g <*> h = f <*> (g <*> h)`

300- Associative Composition: `(<<<) <$> f <*> g <*> h = f <*> (g <*> h)`

263

301

302+Formally, `Apply` represents a strong lax semi-monoidal endofunctor.

264

303

265#### `Applicative`

304#### `Applicative`

266

305

@@ -269,10 +308,14 @@ class (Apply f) <= Applicative f where

269 pure :: forall a. a -> f a

308 pure :: forall a. a -> f a

270```

309```

271

310

272−`Applicative`s are [`Functor`](#functor)s which can be "applied" by sequencing composition

311+The `Applicative` type class extends the [`Apply`](#apply) type class with a `pure` function, which can be used to

273−(`<*>`) or embedding pure expressions (`pure`).

312+create values of type `f a` from values of type `a`.

274

313

314+Where [`Apply`](#apply) provides the ability to lift functions of two or more arguments to functions whose arguments are wrapped using `f`,

315+and [`Functor`](#functor) provides the ability to lift functions of one argument, `pure` can be seen as the function which lifts functions of

316+_zero_ arguments. That is, `Applicative` functors support a lifting operation for any number of function arguments.

317+

275−`Applicative`s should obey the following rules.

318+`Applicative` instances should satisfy the following laws:

276

319

277- Identity: `(pure id) <*> v = v`

320- Identity: `(pure id) <*> v = v`

278- Composition: `(pure <<<) <*> f <*> g <*> h = f <*> (g <*> h)`

321- Composition: `(pure <<<) <*> f <*> g <*> h = f <*> (g <*> h)`

@@ -286,6 +329,15 @@ class (Apply f) <= Applicative f where

286liftA1 :: forall f a b. (Applicative f) => (a -> b) -> f a -> f b

329liftA1 :: forall f a b. (Applicative f) => (a -> b) -> f a -> f b

287```

330```

288

331

332+`liftA1` provides a default implementation of `(<$>)` for any [`Applicative`](#applicative) functor,

333+without using `(<$>)` as provided by the [`Functor`](#functor)-[`Applicative`](#applicative) superclass relationship.

334+

335+`liftA1` can therefore be used to write [`Functor`](#functor) instances as follows:

336+

337+```purescript

338+instance functorF :: Functor F where

339+ (<$>) = liftA1

340+```

289

341

290#### `Bind`

342#### `Bind`

291

343

@@ -294,12 +346,33 @@ class (Apply m) <= Bind m where

294 (>>=) :: forall a b. m a -> (a -> m b) -> m b

346 (>>=) :: forall a b. m a -> (a -> m b) -> m b

295```

347```

296

348

297−A `Bind` is an [`Apply`](#apply) with a bind operation which sequentially composes actions.

349+The `Bind` type class extends the [`Apply`](#apply) type class with a "bind" operation `(>>=)` which composes computations

350+in sequence, using the return value of one computation to determine the next computation.

351+

352+The `>>=` operator can also be expressed using `do` notation, as follows:

353+

354+```purescript

355+x >>= f = do y <- x

356+ f y

357+```

358+

359+where the function argument of `f` is given the name `y`.

360+

361+`Bind` instances should satisfy the following law:

298

362

299−`Bind`s should obey the following rule.

363+- Associativity: `(x >>= f) >>= g = x >>= (\k => f k >>= g)`

300

364

301−- Associativity: `forall f g x. (x >>= f) >>= g = x >>= (\k => f k >>= g)`

365+Or, expressed using `do` notation:

302

366

367+- Associativity: `do { z <- do { y <- x ; f y } ; g z } = do { k <- x ; do { y <- f k ; g y } }`

368+

369+Associativity tells us that we can regroup operations which use do-notation, so that we can unambiguously write, for example:

370+

371+```purescript

372+do x <- m1

373+ y <- m2 x

374+ m3 x y

375+```

303

376

304#### `Monad`

377#### `Monad`

305

378

@@ -307,14 +380,19 @@ A `Bind` is an [`Apply`](#apply) with a bind operation which sequentially compos

307class (Applicative m, Bind m) <= Monad m where

380class (Applicative m, Bind m) <= Monad m where

308```

381```

309

382

310−`Monad` is a class which can be intuitively thought of as an abstract datatype of actions or

383+The `Monad` type class combines the operations of the `Bind` and `Applicative` type classes. Therefore, `Monad` instances

311−more formally though of as a monoid in the category of endofunctors.

384+represent type constructors which support sequential composition, and also lifting of functions of arbitrary arity.

312

385

313−`Monad`s should obey the following rules.

386+`Monad` instances should satisfy the following laws:

314

387

315- Left Identity: `pure x >>= f = f x`

388- Left Identity: `pure x >>= f = f x`

316- Right Identity: `x >>= pure = x`

389- Right Identity: `x >>= pure = x`

317

390

391+Or, expressed using `do` notation:

392+

393+- Left Identity: `do { y <- pure x ; f y } = f x`

394+- Right Identity: `do { y <- x ; pure y } = x`

395+

318

396

319#### `return`

397#### `return`

320

398

@@ -322,6 +400,7 @@ more formally though of as a monoid in the category of endofunctors.

322return :: forall m a. (Monad m) => a -> m a

400return :: forall m a. (Monad m) => a -> m a

323```

401```

324

402

403+`return` is an alias for `pure`.

325

404

326#### `liftM1`

405#### `liftM1`

327

406

@@ -329,6 +408,15 @@ return :: forall m a. (Monad m) => a -> m a

329liftM1 :: forall m a b. (Monad m) => (a -> b) -> m a -> m b

408liftM1 :: forall m a b. (Monad m) => (a -> b) -> m a -> m b

330```

409```

331

410

411+`liftM1` provides a default implementation of `(<$>)` for any [`Monad`](#monad),

412+without using `(<$>)` as provided by the [`Functor`](#functor)-[`Monad`](#monad) superclass relationship.

413+

414+`liftM1` can therefore be used to write [`Functor`](#functor) instances as follows:

415+

416+```purescript

417+instance functorF :: Functor F where

418+ (<$>) = liftM1

419+```

332

420

333#### `ap`

421#### `ap`

334

422

@@ -336,6 +424,15 @@ liftM1 :: forall m a b. (Monad m) => (a -> b) -> m a -> m b

336ap :: forall m a b. (Monad m) => m (a -> b) -> m a -> m b

424ap :: forall m a b. (Monad m) => m (a -> b) -> m a -> m b

337```

425```

338

426

427+`ap` provides a default implementation of `(<*>)` for any [`Monad`](#monad),

428+without using `(<*>)` as provided by the [`Apply`](#apply)-[`Monad`](#monad) superclass relationship.

429+

430+`ap` can therefore be used to write [`Apply`](#apply) instances as follows:

431+

432+```purescript

433+instance applyF :: Apply F where

434+ (<*>) = ap

435+```

339

436

340#### `functorArr`

437#### `functorArr`

341

438

@@ -384,8 +481,8 @@ class Semiring a where

384

481

385Addition and multiplication, satisfying the following laws:

482Addition and multiplication, satisfying the following laws:

386

483

387−- `a` is a commutative monoid under addition with identity element zero

484+- `a` is a commutative monoid under addition

388−- `a` is a monoid under multiplication with identity element one

485+- `a` is a monoid under multiplication

389- multiplication distributes over addition

486- multiplication distributes over addition

390- multiplication by `zero` annihilates `a`

487- multiplication by `zero` annihilates `a`

391

488

@@ -485,6 +582,10 @@ newtype Unit

485 = Unit { }

582 = Unit { }

486```

583```

487

584

585+The `Unit` type has a single inhabitant, called `unit`. It represents values with no computational content.

586+

587+`Unit` is often used, wrapped in a monadic type constructor, as the return type of a computation where only

588+the _effects_ are important.

488

589

489#### `unit`

590#### `unit`

490

591

@@ -492,6 +593,7 @@ newtype Unit

492unit :: Unit

593unit :: Unit

493```

594```

494

595

596+`unit` is the sole inhabitant of the `Unit` type.

495

597

496#### `Eq`

598#### `Eq`

497

599

@@ -501,7 +603,16 @@ class Eq a where

501 (/=) :: a -> a -> Boolean

603 (/=) :: a -> a -> Boolean

502```

604```

503

605

504−Class for types that have an equality comparison.

606+The `Eq` type class represents types which support decidable equality.

607+

608+`Eq` instances should satisfy the following laws:

609+

610+- Reflexivity: `x == x = true`

611+- Symmetry: `x == y = y == x`

612+- Transitivity: if `x == y` and `y == z` then `x == z`

613+- Negation: `x /= y = not (x == y)`

614+

615+`(/=)` may be implemented in terms of `(==)`, but it might give a performance improvement to implement it separately.

505

616

506#### `refEq`

617#### `refEq`

507

618

@@ -561,6 +672,11 @@ data Ordering

561 | EQ

672 | EQ

562```

673```

563

674

675+The `Ordering` data type represents the three possible outcomes of comparing two values:

676+

677+`LT` - The first value is _less than_ the second.

678+`GT` - The first value is _greater than_ the second.

679+`EQ` - The first value is _equal to_ or _incomparable to_ the second.

564

680

565#### `eqOrdering`

681#### `eqOrdering`

566

682

@@ -590,9 +706,9 @@ class (Eq a) <= Ord a where

590 compare :: a -> a -> Ordering

706 compare :: a -> a -> Ordering

591```

707```

592

708

593−Class for types that have ordered comparisons.

709+The `Ord` type class represents types which support comparisons.

594

710

595−Represents a partially ordered set satisfying the following laws:

711+`Ord` instances should satisfy the laws of _partially orderings_:

596

712

597- Reflexivity: `a <= a`

713- Reflexivity: `a <= a`

598- Antisymmetry: if `a <= b` and `b <= a` then `a = b`

714- Antisymmetry: if `a <= b` and `b <= a` then `a = b`

@@ -605,6 +721,7 @@ Represents a partially ordered set satisfying the following laws:

605(<) :: forall a. (Ord a) => a -> a -> Boolean

721(<) :: forall a. (Ord a) => a -> a -> Boolean

606```

722```

607

723

724+Test whether one value is _strictly less than_ another.

608

725

609#### `(>)`

726#### `(>)`

610

727

@@ -612,6 +729,7 @@ Represents a partially ordered set satisfying the following laws:

612(>) :: forall a. (Ord a) => a -> a -> Boolean

729(>) :: forall a. (Ord a) => a -> a -> Boolean

613```

730```

614

731

732+Test whether one value is _strictly greater than_ another.

615

733

616#### `(<=)`

734#### `(<=)`

617

735

@@ -619,6 +737,7 @@ Represents a partially ordered set satisfying the following laws:

619(<=) :: forall a. (Ord a) => a -> a -> Boolean

737(<=) :: forall a. (Ord a) => a -> a -> Boolean

620```

738```

621

739

740+Test whether one value is _non-strictly less than_ another.

622

741

623#### `(>=)`

742#### `(>=)`

624

743

@@ -626,6 +745,7 @@ Represents a partially ordered set satisfying the following laws:

626(>=) :: forall a. (Ord a) => a -> a -> Boolean

745(>=) :: forall a. (Ord a) => a -> a -> Boolean

627```

746```

628

747

748+Test whether one value is _non-strictly greater than_ another.

629

749

630#### `ordUnit`

750#### `ordUnit`

631

751

@@ -675,6 +795,7 @@ class Bits b where

675 complement :: b -> b

795 complement :: b -> b

676```

796```

677

797

798+The `Bits` type class identifies types which support bitwise operations.

678

799

679#### `bitsNumber`

800#### `bitsNumber`

680

801

@@ -692,6 +813,10 @@ class BoolLike b where

692 not :: b -> b

813 not :: b -> b

693```

814```

694

815

816+The `BoolLike` type class identifies types which support Boolean operations.

817+

818+`BoolLike` instances are required to satisfy the laws of a _Boolean algebra_.

819+

695

820

696#### `boolLikeBoolean`

821#### `boolLikeBoolean`

697

822

@@ -707,6 +832,13 @@ class Semigroup a where

707 (<>) :: a -> a -> a

832 (<>) :: a -> a -> a

708```

833```

709

834

835+The `Semigroup` type class identifies an associative operation on a type.

836+

837+`Semigroup` instances are required to satisfy the following law:

838+

839+- Associativity: `(x <> y) <> z = x <> (y <> z)`

840+

841+For example, the `String` type is an instance of `Semigroup`, where `(<>)` is defined to be string concatenation.

710

842

711#### `semigroupUnit`

843#### `semigroupUnit`

712

844

@@ -735,6 +867,7 @@ instance semigroupArr :: (Semigroup s') => Semigroup (s -> s')

735(++) :: forall s. (Semigroup s) => s -> s -> s

867(++) :: forall s. (Semigroup s) => s -> s -> s

736```

868```

737

869

870+`(++)` is an alias for `(<>)`.

738

871

739

872

740## Module Data.Function

873## Module Data.Function

prelude/images/Prelude.png

Binary file not shown.

prelude/prelude.purs+157−24

@@ -79,12 +79,15 @@ module Prelude

79 -- |

80 -- | - Associativity: `p <<< (q <<< r) = (p <<< q) <<< r`

81 -- |

82+ -- | One example of a `Semigroupoid` is the function type constructor `(->)`, with `(<<<)` defined

83+ -- | as function composition.

82 class Semigroupoid a where

84 class Semigroupoid a where

83 (<<<) :: forall b c d. a c d -> a b c -> a b d

85 (<<<) :: forall b c d. a c d -> a b c -> a b d

85 instance semigroupoidArr :: Semigroupoid (->) where

87 instance semigroupoidArr :: Semigroupoid (->) where

86 (<<<) f g x = f (g x)

88 (<<<) f g x = f (g x)

90+ -- | Forwards composition, or `(<<<)` with its arguments reversed.

88 (>>>) :: forall a b c d. (Semigroupoid a) => a b c -> a c d -> a b d

91 (>>>) :: forall a b c d. (Semigroupoid a) => a b c -> a c d -> a b d

89 (>>>) f g = g <<< f

92 (>>>) f g = g <<< f

@@ -143,15 +146,19 @@ module Prelude

143

146

144 infixr 6 :

147 infixr 6 :

145

148

146− -- | Attaches an element to the front of a list.

149+ -- | An infix alias for `cons`.

147− -- |

148− -- | ```purescript

149− -- | 1 : [2, 3, 4] = [1, 2, 3, 4]

150− -- | ```

151 -- |

150 -- |

151+ -- | Note, the running time of this function is `O(n)`.

152 (:) :: forall a. a -> [a] -> [a]

153 (:) = cons

154

155+ -- | Attaches an element to the front of an array, creating a new array.

156+ -- |

157+ -- | ```purescript

158+ -- | cons 1 [2, 3, 4] = [1, 2, 3, 4]

159+ -- | ```

160+ -- |

161+ -- | Note, the running time of this function is `O(n)`.

155 foreign import cons

162 foreign import cons

156 """

163 """

157 function cons(e) {

164 function cons(e) {

@@ -161,6 +168,10 @@ module Prelude

161 }

168 }

162 """ :: forall a. a -> [a] -> [a]

169 """ :: forall a. a -> [a] -> [a]

163

170

171+ -- | The `Show` type class represents those types which can be converted into a human-readable `String` representation.

172+ -- |

173+ -- | While not required, it is recommended that for any expression `x`, the string `show x` be executable PureScript code

174+ -- | which evaluates to the same value as the expression `x`.

164 class Show a where

175 class Show a where

165 show :: a -> String

176 show :: a -> String

166

177

@@ -210,10 +221,12 @@ module Prelude

210 infixl 4 <$>

221 infixl 4 <$>

211 infixl 1 <#>

222 infixl 1 <#>

212

223

213− -- | A `Functor` is intuitively a type which can be mapped over, and more formally a mapping

224+ -- | A `Functor` is a type constructor which supports a mapping operation `(<$>)`.

214− -- | between [`Category`](#category)s that preserves structure.

225+ -- |

226+ -- | `(<$>)` can be used to turn functions `a -> b` into functions `f a -> f b` whose argument and return

227+ -- | types use the type constructor `f` to represent some computational context.

215 -- |

228 -- |

216− -- | `Functor`s should obey the following rules.

229+ -- | `Functor` instances should satisfy the following laws:

217 -- |

230 -- |

218 -- | - Identity: `(<$>) id = id`

231 -- | - Identity: `(<$>) id = id`

219 -- | - Composition: `(<$>) (f <<< g) = (<$> f) <<< (<$> g)`

232 -- | - Composition: `(<$>) (f <<< g) = (<$> f) <<< (<$> g)`

@@ -221,28 +234,58 @@ module Prelude

221 class Functor f where

234 class Functor f where

222 (<$>) :: forall a b. (a -> b) -> f a -> f b

235 (<$>) :: forall a b. (a -> b) -> f a -> f b

223

236

237+ -- | `(<#>)` is `(<$>)` with its arguments flipped. For example:

238+ -- |

239+ -- | ```purescript

240+ -- | [1, 2, 3] <#> \n -> n * n

241+ -- | ```

224 (<#>) :: forall f a b. (Functor f) => f a -> (a -> b) -> f b

242 (<#>) :: forall f a b. (Functor f) => f a -> (a -> b) -> f b

225 (<#>) fa f = f <$> fa

243 (<#>) fa f = f <$> fa

226

244

245+ -- | The `void` function is used to ignore the type wrapped by a [`Functor`](#functor), replacing it with `Unit` and

246+ -- | keeping only the type information provided by the type constructor itself.

247+ -- |

248+ -- | `void` is often useful when using `do` notation to change the return type of a monadic computation:

249+ -- |

250+ -- | ```purescript

251+ -- | main = forE 1 10 \n -> void do

252+ -- | print n

253+ -- | print (n * n)

254+ -- | ```

227 void :: forall f a. (Functor f) => f a -> f Unit

255 void :: forall f a. (Functor f) => f a -> f Unit

228 void fa = const unit <$> fa

256 void fa = const unit <$> fa

229

257

230 infixl 4 <*>

258 infixl 4 <*>

231

259

232− -- | `Apply`s are intuitively [`Applicative`](#applicative)s less `pure`, and more formally a

260+ -- | The `Apply` class provides the `(<*>)` which is used to apply a function to an argument under a type constructor.

233− -- | strong lax semi-monoidal endofunctor.

261+ -- |

262+ -- | `Apply` can be used to lift functions of two or more arguments to work on values wrapped with the type constructor `f`.

263+ -- | It might also be understood in terms of the `lift2` function:

264+ -- |

265+ -- | ```purescript

266+ -- | lift2 :: forall f a b c. (Apply f) => (a -> b -> c) -> f a -> f b -> f c

267+ -- | lift2 f a b = f <$> a <*> b

268+ -- | ```

269+ -- |

270+ -- | `(<*>)` is recovered from `lift2` as `lift2 ($)`. That is, `(<*>)` lifts the function application operator `($)` to arguments

271+ -- | wrapped with the type constructor `f`.

234 -- |

272 -- |

235− -- | `Apply`s should obey the following rule.

273+ -- | `Apply` instances should satisfy the following law:

236 -- |

274 -- |

237 -- | - Associative Composition: `(<<<) <$> f <*> g <*> h = f <*> (g <*> h)`

275 -- | - Associative Composition: `(<<<) <$> f <*> g <*> h = f <*> (g <*> h)`

238 -- |

276 -- |

277+ -- | Formally, `Apply` represents a strong lax semi-monoidal endofunctor.

239 class (Functor f) <= Apply f where

278 class (Functor f) <= Apply f where

240 (<*>) :: forall a b. f (a -> b) -> f a -> f b

279 (<*>) :: forall a b. f (a -> b) -> f a -> f b

241

280

242− -- | `Applicative`s are [`Functor`](#functor)s which can be "applied" by sequencing composition

281+ -- | The `Applicative` type class extends the [`Apply`](#apply) type class with a `pure` function, which can be used to

243− -- | (`<*>`) or embedding pure expressions (`pure`).

282+ -- | create values of type `f a` from values of type `a`.

283+ -- |

284+ -- | Where [`Apply`](#apply) provides the ability to lift functions of two or more arguments to functions whose arguments are wrapped using `f`,

285+ -- | and [`Functor`](#functor) provides the ability to lift functions of one argument, `pure` can be seen as the function which lifts functions of

286+ -- | _zero_ arguments. That is, `Applicative` functors support a lifting operation for any number of function arguments.

244 -- |

287 -- |

245− -- | `Applicative`s should obey the following rules.

288+ -- | `Applicative` instances should satisfy the following laws:

246 -- |

289 -- |

247 -- | - Identity: `(pure id) <*> v = v`

290 -- | - Identity: `(pure id) <*> v = v`

248 -- | - Composition: `(pure <<<) <*> f <*> g <*> h = f <*> (g <*> h)`

291 -- | - Composition: `(pure <<<) <*> f <*> g <*> h = f <*> (g <*> h)`

@@ -252,38 +295,92 @@ module Prelude

252 class (Apply f) <= Applicative f where

295 class (Apply f) <= Applicative f where

253 pure :: forall a. a -> f a

296 pure :: forall a. a -> f a

254

297

298+ -- | `liftA1` provides a default implementation of `(<$>)` for any [`Applicative`](#applicative) functor,

299+ -- | without using `(<$>)` as provided by the [`Functor`](#functor)-[`Applicative`](#applicative) superclass relationship.

300+ -- |

301+ -- | `liftA1` can therefore be used to write [`Functor`](#functor) instances as follows:

302+ -- |

303+ -- | ```purescript

304+ -- | instance functorF :: Functor F where

305+ -- | (<$>) = liftA1

306+ -- | ```

255 liftA1 :: forall f a b. (Applicative f) => (a -> b) -> f a -> f b

307 liftA1 :: forall f a b. (Applicative f) => (a -> b) -> f a -> f b

256 liftA1 f a = pure f <*> a

308 liftA1 f a = pure f <*> a

257

309

258 infixl 1 >>=

310 infixl 1 >>=

259

311

260− -- | A `Bind` is an [`Apply`](#apply) with a bind operation which sequentially composes actions.

312+ -- | The `Bind` type class extends the [`Apply`](#apply) type class with a "bind" operation `(>>=)` which composes computations

313+ -- | in sequence, using the return value of one computation to determine the next computation.

314+ -- |

315+ -- | The `>>=` operator can also be expressed using `do` notation, as follows:

316+ -- |

317+ -- | ```purescript

318+ -- | x >>= f = do y <- x

319+ -- | f y

320+ -- | ```

321+ -- |

322+ -- | where the function argument of `f` is given the name `y`.

261− -- |

323+ -- |

262− -- | `Bind`s should obey the following rule.

324+ -- | `Bind` instances should satisfy the following law:

263 -- |

325 -- |

264− -- | - Associativity: `forall f g x. (x >>= f) >>= g = x >>= (\k => f k >>= g)`

326+ -- | - Associativity: `(x >>= f) >>= g = x >>= (\k => f k >>= g)`

265 -- |

327 -- |

328+ -- | Or, expressed using `do` notation:

329+ -- |

330+ -- | - Associativity: `do { z <- do { y <- x ; f y } ; g z } = do { k <- x ; do { y <- f k ; g y } }`

331+ -- |

332+ -- | Associativity tells us that we can regroup operations which use do-notation, so that we can unambiguously write, for example:

333+ -- |

334+ -- | ```purescript

335+ -- | do x <- m1

336+ -- | y <- m2 x

337+ -- | m3 x y

338+ -- | ```

266 class (Apply m) <= Bind m where

339 class (Apply m) <= Bind m where

267 (>>=) :: forall a b. m a -> (a -> m b) -> m b

340 (>>=) :: forall a b. m a -> (a -> m b) -> m b

268

341

269− -- | `Monad` is a class which can be intuitively thought of as an abstract datatype of actions or

342+ -- | The `Monad` type class combines the operations of the `Bind` and `Applicative` type classes. Therefore, `Monad` instances

270− -- | more formally though of as a monoid in the category of endofunctors.

343+ -- | represent type constructors which support sequential composition, and also lifting of functions of arbitrary arity.

271 -- |

344 -- |

272− -- | `Monad`s should obey the following rules.

345+ -- | `Monad` instances should satisfy the following laws:

273 -- |

346 -- |

274 -- | - Left Identity: `pure x >>= f = f x`

347 -- | - Left Identity: `pure x >>= f = f x`

275 -- | - Right Identity: `x >>= pure = x`

348 -- | - Right Identity: `x >>= pure = x`

276 -- |

349 -- |

350+ -- | Or, expressed using `do` notation:

351+ -- |

352+ -- | - Left Identity: `do { y <- pure x ; f y } = f x`

353+ -- | - Right Identity: `do { y <- x ; pure y } = x`

354+ -- |

277 class (Applicative m, Bind m) <= Monad m

355 class (Applicative m, Bind m) <= Monad m

278

356

357+ -- | `return` is an alias for `pure`.

279 return :: forall m a. (Monad m) => a -> m a

358 return :: forall m a. (Monad m) => a -> m a

280 return = pure

359 return = pure

281

360

361+ -- | `liftM1` provides a default implementation of `(<$>)` for any [`Monad`](#monad),

362+ -- | without using `(<$>)` as provided by the [`Functor`](#functor)-[`Monad`](#monad) superclass relationship.

363+ -- |

364+ -- | `liftM1` can therefore be used to write [`Functor`](#functor) instances as follows:

365+ -- |

366+ -- | ```purescript

367+ -- | instance functorF :: Functor F where

368+ -- | (<$>) = liftM1

369+ -- | ```

282 liftM1 :: forall m a b. (Monad m) => (a -> b) -> m a -> m b

370 liftM1 :: forall m a b. (Monad m) => (a -> b) -> m a -> m b

283 liftM1 f a = do

371 liftM1 f a = do

284 a' <- a

372 a' <- a

285 return (f a')

373 return (f a')

286

374

375+ -- | `ap` provides a default implementation of `(<*>)` for any [`Monad`](#monad),

376+ -- | without using `(<*>)` as provided by the [`Apply`](#apply)-[`Monad`](#monad) superclass relationship.

377+ -- |

378+ -- | `ap` can therefore be used to write [`Apply`](#apply) instances as follows:

379+ -- |

380+ -- | ```purescript

381+ -- | instance applyF :: Apply F where

382+ -- | (<*>) = ap

383+ -- | ```

287 ap :: forall m a b. (Monad m) => m (a -> b) -> m a -> m b

384 ap :: forall m a b. (Monad m) => m (a -> b) -> m a -> m b

288 ap f a = do

385 ap f a = do

289 f' <- f

386 f' <- f

@@ -417,15 +514,29 @@ module Prelude

417

514

418 instance numNumber :: Num Number

515 instance numNumber :: Num Number

419

516

517+ -- | The `Unit` type has a single inhabitant, called `unit`. It represents values with no computational content.

518+ -- |

519+ -- | `Unit` is often used, wrapped in a monadic type constructor, as the return type of a computation where only

520+ -- | the _effects_ are important.

420 newtype Unit = Unit {}

521 newtype Unit = Unit {}

421

522

523+ -- | `unit` is the sole inhabitant of the `Unit` type.

422 unit :: Unit

524 unit :: Unit

423 unit = Unit {}

525 unit = Unit {}

424

526

425 infix 4 ==

527 infix 4 ==

426 infix 4 /=

528 infix 4 /=

427

529

428− -- | Class for types that have an equality comparison.

530+ -- | The `Eq` type class represents types which support decidable equality.

531+ -- |

532+ -- | `Eq` instances should satisfy the following laws:

533+ -- |

534+ -- | - Reflexivity: `x == x = true`

535+ -- | - Symmetry: `x == y = y == x`

536+ -- | - Transitivity: if `x == y` and `y == z` then `x == z`

537+ -- | - Negation: `x /= y = not (x == y)`

538+ -- |

539+ -- | `(/=)` may be implemented in terms of `(==)`, but it might give a performance improvement to implement it separately.

429 class Eq a where

540 class Eq a where

430 (==) :: a -> a -> Boolean

541 (==) :: a -> a -> Boolean

431 (/=) :: a -> a -> Boolean

542 (/=) :: a -> a -> Boolean

@@ -483,6 +594,11 @@ module Prelude

483 (==) xs ys = eqArrayImpl (==) xs ys

594 (==) xs ys = eqArrayImpl (==) xs ys

484 (/=) xs ys = not (xs == ys)

595 (/=) xs ys = not (xs == ys)

485

596

597+ -- | The `Ordering` data type represents the three possible outcomes of comparing two values:

598+ -- |

599+ -- | `LT` - The first value is _less than_ the second.

600+ -- | `GT` - The first value is _greater than_ the second.

601+ -- | `EQ` - The first value is _equal to_ or _incomparable to_ the second.

486 data Ordering = LT | GT | EQ

602 data Ordering = LT | GT | EQ

487

603

488 instance eqOrdering :: Eq Ordering where

604 instance eqOrdering :: Eq Ordering where

@@ -502,9 +618,9 @@ module Prelude

502 (<>) GT _ = GT

618 (<>) GT _ = GT

503 (<>) EQ y = y

619 (<>) EQ y = y

504

620

505− -- | Class for types that have ordered comparisons.

621+ -- | The `Ord` type class represents types which support comparisons.

506 -- |

622 -- |

507− -- | Represents a partially ordered set satisfying the following laws:

623+ -- | `Ord` instances should satisfy the laws of _partially orderings_:

508 -- |

624 -- |

509 -- | - Reflexivity: `a <= a`

625 -- | - Reflexivity: `a <= a`

510 -- | - Antisymmetry: if `a <= b` and `b <= a` then `a = b`

626 -- | - Antisymmetry: if `a <= b` and `b <= a` then `a = b`

@@ -515,6 +631,7 @@ module Prelude

515

631

516 infixl 4 <

632 infixl 4 <

517

633

634+ -- | Test whether one value is _strictly less than_ another.

518 (<) :: forall a. (Ord a) => a -> a -> Boolean

635 (<) :: forall a. (Ord a) => a -> a -> Boolean

519 (<) a1 a2 = case a1 `compare` a2 of

636 (<) a1 a2 = case a1 `compare` a2 of

520 LT -> true

637 LT -> true

@@ -522,6 +639,7 @@ module Prelude

522

639

523 infixl 4 >

640 infixl 4 >

524

641

642+ -- | Test whether one value is _strictly greater than_ another.

525 (>) :: forall a. (Ord a) => a -> a -> Boolean

643 (>) :: forall a. (Ord a) => a -> a -> Boolean

526 (>) a1 a2 = case a1 `compare` a2 of

644 (>) a1 a2 = case a1 `compare` a2 of

527 GT -> true

645 GT -> true

@@ -529,6 +647,7 @@ module Prelude

529

647

530 infixl 4 <=

648 infixl 4 <=

531

649

650+ -- | Test whether one value is _non-strictly less than_ another.

532 (<=) :: forall a. (Ord a) => a -> a -> Boolean

651 (<=) :: forall a. (Ord a) => a -> a -> Boolean

533 (<=) a1 a2 = case a1 `compare` a2 of

652 (<=) a1 a2 = case a1 `compare` a2 of

534 GT -> false

653 GT -> false

@@ -536,6 +655,7 @@ module Prelude

536

655

537 infixl 4 >=

656 infixl 4 >=

538

657

658+ -- | Test whether one value is _non-strictly greater than_ another.

539 (>=) :: forall a. (Ord a) => a -> a -> Boolean

659 (>=) :: forall a. (Ord a) => a -> a -> Boolean

540 (>=) a1 a2 = case a1 `compare` a2 of

660 (>=) a1 a2 = case a1 `compare` a2 of

541 LT -> false

661 LT -> false

@@ -586,6 +706,7 @@ module Prelude

586 infixl 10 .|.

706 infixl 10 .|.

587 infixl 10 .^.

707 infixl 10 .^.

588

708

709+ -- | The `Bits` type class identifies types which support bitwise operations.

589 class Bits b where

710 class Bits b where

590 (.&.) :: b -> b -> b

711 (.&.) :: b -> b -> b

591 (.|.) :: b -> b -> b

712 (.|.) :: b -> b -> b

@@ -668,6 +789,10 @@ module Prelude

668 infixr 2 ||

789 infixr 2 ||

669 infixr 3 &&

790 infixr 3 &&

670

791

792+ -- | The `BoolLike` type class identifies types which support Boolean operations.

793+ -- |

794+ -- | `BoolLike` instances are required to satisfy the laws of a _Boolean algebra_.

795+ -- |

671 class BoolLike b where

796 class BoolLike b where

672 (&&) :: b -> b -> b

797 (&&) :: b -> b -> b

673 (||) :: b -> b -> b

798 (||) :: b -> b -> b

@@ -705,6 +830,13 @@ module Prelude

705

830

706 infixr 5 <>

831 infixr 5 <>

707

832

833+ -- | The `Semigroup` type class identifies an associative operation on a type.

834+ -- |

835+ -- | `Semigroup` instances are required to satisfy the following law:

836+ -- |

837+ -- | - Associativity: `(x <> y) <> z = x <> (y <> z)`

838+ -- |

839+ -- | For example, the `String` type is an instance of `Semigroup`, where `(<>)` is defined to be string concatenation.

708 class Semigroup a where

840 class Semigroup a where

709 (<>) :: a -> a -> a

841 (<>) :: a -> a -> a

710

842

@@ -728,6 +860,7 @@ module Prelude

728

860

729 infixr 5 ++

861 infixr 5 ++

730

862

863+ -- | `(++)` is an alias for `(<>)`.

731 (++) :: forall s. (Semigroup s) => s -> s -> s

864 (++) :: forall s. (Semigroup s) => s -> s -> s

732 (++) = (<>)

865 (++) = (<>)

733

866