Separate docs

Author: garyb

README.md

@@ -16,4 +16,23 @@ bower install purescript-control
 
 ## Module documentation
 
-[`docs/MODULE.md`](docs/MODULE.md)
+### Functor/Applicative
+- [Control.Functor](docs/Control.Functor.md)
+- [Control.Apply](docs/Control.Apply.md)
+
+### Monad
+- [Control.Bind](docs/Control.Bind.md)
+- [Control.Monad](docs/Control.Monad.md)
+
+### Alternative/MonadPlus
+- [Control.Alt](docs/Control.Alt.md)
+- [Control.Plus](docs/Control.Plus.md)
+- [Control.Alternative](docs/Control.Alternative.md)
+- [Control.MonadPlus](docs/Control.MonadPlus.md)
+
+### Comonads
+- [Control.Extend](docs/Control.Extend.md)
+- [Control.Comonad](docs/Control.Comonad.md)
+
+### Lazy
+- [Control.Lazy](docs/Control.Lazy.md)

docs/Control.Alt.md

@@ -0,0 +1,29 @@
+# Module Documentation
+
+## Module Control.Alt
+
+
+This module defines the `Alt` type class.
+
+#### `Alt`
+
+``` purescript
+class (Functor f) <= Alt f where
+  (<|>) :: forall a. f a -> f a -> f a
+```
+
+The `Alt` type class identifies an associative operation on a type
+constructor.  It is similar to `Semigroup`, except that it applies to
+types of kind `* -> *`, like `Array` or `List`, rather than concrete types
+`String` or `Number`.
+
+`Alt` instances are required to satisfy the following laws:
+
+- Associativity: `(x <|> y) <|> z == x <|> (y <|> z)`
+- Distributivity: `f <$> (x <|> y) == (f <$> x) <|> (f <$> y)`
+
+For example, the `Array` (`[]`) type is an instance of `Alt`, where
+`(<|>)` is defined to be concatenation.
+
+
+

docs/Control.Alternative.md

@@ -0,0 +1,48 @@
+# Module Documentation
+
+## Module Control.Alternative
+
+
+This module defines the `Alternative` type class and associated
+helper functions.
+
+#### `Alternative`
+
+``` purescript
+class (Applicative f, Plus f) <= Alternative f where
+```
+
+The `Alternative` type class has no members of its own; it just specifies
+that the type constructor has both `Applicative` and `Plus` instances.
+
+Types which have `Alternative` instances should also satisfy the following
+laws:
+
+- Distributivity: `(f <|> g) <*> x == (f <*> x) <|> (g <*> x)`
+- Annihilation: `empty <*> f = empty`
+
+#### `some`
+
+``` purescript
+some :: forall f a. (Alternative f, Lazy (f [a])) => f a -> f [a]
+```
+
+Attempt a computation multiple times, requiring at least one success.
+
+The `Lazy` constraint is used to generate the result lazily, to ensure
+termination.
+
+#### `many`
+
+``` purescript
+many :: forall f a. (Alternative f, Lazy (f [a])) => f a -> f [a]
+```
+
+Attempt a computation multiple times, returning as many successful results
+as possible (possibly zero).
+
+The `Lazy` constraint is used to generate the result lazily, to ensure
+termination.
+
+
+

docs/Control.Apply.md

@@ -0,0 +1,61 @@
+# Module Documentation
+
+## Module Control.Apply
+
+
+This module defines helper functions for working with `Apply` instances.
+
+#### `(<*)`
+
+``` purescript
+(<*) :: forall a b f. (Apply f) => f a -> f b -> f a
+```
+
+Combine two effectful actions, keeping only the result of the first.
+
+#### `(*>)`
+
+``` purescript
+(*>) :: forall a b f. (Apply f) => f a -> f b -> f b
+```
+
+Combine two effectful actions, keeping only the result of the second.
+
+#### `lift2`
+
+``` purescript
+lift2 :: forall a b c f. (Apply f) => (a -> b -> c) -> f a -> f b -> f c
+```
+
+Lift a function of two arguments to a function which accepts and returns
+values wrapped with the type constructor `f`.
+
+#### `lift3`
+
+``` purescript
+lift3 :: forall a b c d f. (Apply f) => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
+```
+
+Lift a function of three arguments to a function which accepts and returns
+values wrapped with the type constructor `f`.
+
+#### `lift4`
+
+``` purescript
+lift4 :: forall a b c d e f. (Apply f) => (a -> b -> c -> d -> e) -> f a -> f b -> f c -> f d -> f e
+```
+
+Lift a function of four arguments to a function which accepts and returns
+values wrapped with the type constructor `f`.
+
+#### `lift5`
+
+``` purescript
+lift5 :: forall a b c d e f g. (Apply f) => (a -> b -> c -> d -> e -> g) -> f a -> f b -> f c -> f d -> f e -> f g
+```
+
+Lift a function of five arguments to a function which accepts and returns
+values wrapped with the type constructor `f`.
+
+
+

docs/Control.Bind.md

@@ -0,0 +1,65 @@
+# Module Documentation
+
+## Module Control.Bind
+
+
+This module defines helper functions for working with `Bind` instances.
+
+#### `(=<<)`
+
+``` purescript
+(=<<) :: forall a b m. (Bind m) => (a -> m b) -> m a -> m b
+```
+
+A version of `(>>=)` with its arguments flipped.
+
+#### `(>=>)`
+
+``` purescript
+(>=>) :: forall a b c m. (Bind m) => (a -> m b) -> (b -> m c) -> a -> m c
+```
+
+Forwards Kleisli composition.
+
+For example:
+
+```purescript
+import Data.Array (head, tail)
+
+third = tail >=> tail >=> head
+```
+
+#### `(<=<)`
+
+``` purescript
+(<=<) :: forall a b c m. (Bind m) => (b -> m c) -> (a -> m b) -> a -> m c
+```
+
+Backwards Kleisli composition.
+
+#### `join`
+
+``` purescript
+join :: forall a m. (Bind m) => m (m a) -> m a
+```
+
+Collapse two applications of a monadic type constructor into one.
+
+#### `ifM`
+
+``` purescript
+ifM :: forall a m. (Bind m) => m Boolean -> m a -> m a -> m a
+```
+
+Execute a monadic action if a condition holds. 
+
+For example:
+
+```purescript
+main = ifM ((< 0.5) <$> random)
+         (trace "Heads")
+         (trace "Tails")
+```
+
+
+

docs/Control.Comonad.md

@@ -0,0 +1,27 @@
+# Module Documentation
+
+## Module Control.Comonad
+
+
+This module defines the `Comonad` type class.
+
+#### `Comonad`
+
+``` purescript
+class (Extend w) <= Comonad w where
+  extract :: forall a. w a -> a
+```
+
+`Comonad` extends the `Extend` class with the `extract` function
+which extracts a value, discarding the comonadic context.
+
+`Comonad` is the dual of `Monad`, and `extract` is the dual of 
+`pure` or `return`.
+
+Laws:
+
+- Left Identity: `extract <<= xs = xs`
+- Right Identity: `extract (f <<= xs) = f xs`
+
+
+

docs/Control.Extend.md

@@ -0,0 +1,76 @@
+# Module Documentation
+
+## Module Control.Extend
+
+
+This module defines the `Extend` type class and associated helper functions.
+
+#### `Extend`
+
+``` purescript
+class (Functor w) <= Extend w where
+  (<<=) :: forall b a. (w a -> b) -> w a -> w b
+```
+
+The `Extend` class defines the extension operator `(<<=)`
+which extends a local context-dependent computation to
+a global computation.
+
+`Extend` is the dual of `Bind`, and `(<<=)` is the dual of 
+`(>>=)`.
+
+Laws:
+
+- Associativity: `extend f <<< extend g = extend (f <<< extend g)`
+
+#### `extendArr`
+
+``` purescript
+instance extendArr :: (Semigroup w) => Extend (Prim.Function w)
+```
+
+
+#### `(=>>)`
+
+``` purescript
+(=>>) :: forall b a w. (Extend w) => w a -> (w a -> b) -> w b
+```
+
+A version of `(<<=)` with its arguments flipped.
+
+#### `(=>=)`
+
+``` purescript
+(=>=) :: forall b a w c. (Extend w) => (w a -> b) -> (w b -> c) -> w a -> c
+```
+
+Forwards co-Kleisli composition.
+
+#### `(=<=)`
+
+``` purescript
+(=<=) :: forall b a w c. (Extend w) => (w b -> c) -> (w a -> b) -> w a -> c
+```
+
+Backwards co-Kleisli composition.
+
+#### `extend`
+
+``` purescript
+extend :: forall b a w. (Extend w) => (w a -> b) -> w a -> w b
+```
+
+An alias for `(<<=)`.
+
+#### `duplicate`
+
+``` purescript
+duplicate :: forall a w. (Extend w) => w a -> w (w a)
+```
+
+Duplicate a comonadic context.
+
+`duplicate` is dual to `Control.Bind.join`.
+
+
+

docs/Control.Functor.md

@@ -0,0 +1,25 @@
+# Module Documentation
+
+## Module Control.Functor
+
+
+This module defines helper functions for working with `Functor` instances.
+
+#### `(<$)`
+
+``` purescript
+(<$) :: forall f a b. (Functor f) => a -> f b -> f a
+```
+
+Ignore the return value of a computation, using the specified return value instead.
+
+#### `($>)`
+
+``` purescript
+($>) :: forall f a b. (Functor f) => f a -> b -> f b
+```
+
+A version of `(<$)` with its arguments flipped.
+
+
+

docs/Control.Lazy.md

@@ -0,0 +1,33 @@
+# Module Documentation
+
+## Module Control.Lazy
+
+
+This module defines the `Lazy` type class and associated
+helper functions.
+
+#### `Lazy`
+
+``` purescript
+class Lazy l where
+  defer :: (Unit -> l) -> l
+```
+
+The `Lazy` class represents types which allow evaluation of values
+to be _deferred_.
+
+Usually, this means that a type contains a function arrow which can
+be used to delay evaluation.
+
+#### `fix`
+
+``` purescript
+fix :: forall l a. (Lazy l) => (l -> l) -> l
+```
+
+`fix` defines a value as the fixed point of a function.
+
+The `Lazy` instance allows us to generate the result lazily.
+
+
+