simplify effect types, add a bunch of instances

Author: jdegoes

MODULES.md

@@ -5,32 +5,29 @@
 #### `Async`
 
 ``` purescript
-data Async :: # ! -> !
+data Async :: !
 ```
 
-An effect constructor which accepts a row of effects. `Async e` 
-represents the effect of asynchronous computations which perform effects 
-`e` at some indeterminate point in the future.
+The effect of being asynchronous.
 
 #### `EffA`
 
 ``` purescript
-type EffA e1 e2 a = Eff (async :: Async e1 | e2) a
+type EffA e a = Eff (async :: Async | e) a
 ```
 
-The `Eff` type for a computation which has asynchronous effects `e1` and
-synchronous effects `e2`.
+The `Eff` type for a computation which has asynchronous effects.
 
 #### `Aff`
 
 ``` purescript
-data Aff e1 e2 a
+data Aff e a
 ```
 
-A computation with asynchronous effects `e1` and synchronous effects 
-`e2`. The computation either errors or produces a value of type `a`.
+A computation with effects `e`. The computation either errors or 
+produces a value of type `a`.
 
-This is moral equivalent of `ErrorT (ContT Unit (EffA e1 e2)) a`.
+This is moral equivalent of `ErrorT (ContT Unit (EffA e)) a`.
 
 The type implements `MonadEff` so it's easy to lift synchronous `Eff` 
 computations into this type. As a result, there's basically no reason to
@@ -39,14 +36,14 @@ use `Eff` in a program that has some asynchronous computations.
 #### `PureAff`
 
 ``` purescript
-type PureAff a = forall e1 e2. Aff e1 e2 a
+type PureAff a = forall e. Aff e a
 ```
 
 
 #### `launchAff`
 
 ``` purescript
-launchAff :: forall e1 e2 a. Aff e1 e2 a -> EffA e1 e2 Unit
+launchAff :: forall e a. Aff e a -> EffA e Unit
 ```
 
 Converts the asynchronous effect into a synchronous one. All values and
@@ -55,7 +52,7 @@ errors are ignored.
 #### `runAff`
 
 ``` purescript
-runAff :: forall e1 e2 a. (Error -> Eff e1 Unit) -> (a -> Eff e1 Unit) -> Aff e1 e2 a -> EffA e1 e2 Unit
+runAff :: forall e a. (Error -> Eff e Unit) -> (a -> Eff e Unit) -> Aff e a -> EffA e Unit
 ```
 
 Runs the asynchronous effect. You must supply an error callback and a 
@@ -64,7 +61,7 @@ success callback.
 #### `makeAff`
 
 ``` purescript
-makeAff :: forall e1 e2 a. ((Error -> Eff e1 Unit) -> (a -> Eff e1 Unit) -> EffA e1 e2 Unit) -> Aff e1 e2 a
+makeAff :: forall e a. ((Error -> Eff e Unit) -> (a -> Eff e Unit) -> EffA e Unit) -> Aff e a
 ```
 
 Creates an asynchronous effect from a function that accepts error and 
@@ -73,80 +70,107 @@ success callbacks.
 #### `attempt`
 
 ``` purescript
-attempt :: forall e1 e2 a. Aff e1 e2 a -> Aff e1 e2 (Either Error a)
+attempt :: forall e a. Aff e a -> Aff e (Either Error a)
 ```
 
 Promotes any error to the value level of the asynchronous monad.
 
 #### `liftEff'`
 
 ``` purescript
-liftEff' :: forall e1 e2 a. Eff (err :: Exception | e2) a -> Aff e1 e2 (Either Error a)
+liftEff' :: forall e a. Eff (err :: Exception | e) a -> Aff e (Either Error a)
 ```
 
 Lifts a synchronous computation and makes explicit any failure from exceptions.
 
 #### `semigroupAff`
 
 ``` purescript
-instance semigroupAff :: (Semigroup a) => Semigroup (Aff e1 e2 a)
+instance semigroupAff :: (Semigroup a) => Semigroup (Aff e a)
 ```
 
 
 #### `monoidAff`
 
 ``` purescript
-instance monoidAff :: (Monoid a) => Monoid (Aff e1 e2 a)
+instance monoidAff :: (Monoid a) => Monoid (Aff e a)
 ```
 
 
 #### `functorAff`
 
 ``` purescript
-instance functorAff :: Functor (Aff e1 e2)
+instance functorAff :: Functor (Aff e)
 ```
 
 
 #### `applyAff`
 
 ``` purescript
-instance applyAff :: Apply (Aff e1 e2)
+instance applyAff :: Apply (Aff e)
 ```
 
 
 #### `applicativeAff`
 
 ``` purescript
-instance applicativeAff :: Applicative (Aff e1 e2)
+instance applicativeAff :: Applicative (Aff e)
 ```
 
 
 #### `bindAff`
 
 ``` purescript
-instance bindAff :: Bind (Aff e1 e2)
+instance bindAff :: Bind (Aff e)
 ```
 
 
 #### `monadAff`
 
 ``` purescript
-instance monadAff :: Monad (Aff e1 e2)
+instance monadAff :: Monad (Aff e)
 ```
 
 
 #### `monadEffAff`
 
 ``` purescript
-instance monadEffAff :: MonadEff e2 (Aff e1 e2)
+instance monadEffAff :: MonadEff e (Aff e)
 ```
 
 
 #### `monadErrorAff`
 
 ``` purescript
-instance monadErrorAff :: MonadError Error (Aff e1 e2)
+instance monadErrorAff :: MonadError Error (Aff e)
 ```
 
 Allows users to catch and throw errors on the error channel of the 
-asynchronous computation. See documentation in `purescript-transformers`.
+asynchronous computation. See documentation in `purescript-transformers`.
+
+#### `altAff`
+
+``` purescript
+instance altAff :: Alt (Aff e)
+```
+
+
+#### `plusAff`
+
+``` purescript
+instance plusAff :: Plus (Aff e)
+```
+
+
+#### `alternativeAff`
+
+``` purescript
+instance alternativeAff :: Alternative (Aff e)
+```
+
+
+#### `monadPlusAff`
+
+``` purescript
+instance monadPlusAff :: MonadPlus (Aff e)
+```

README.md

@@ -2,9 +2,9 @@
 
 An asynchronous effect monad for PureScript.
 
-The moral equivalent of `ErrorT (ContT Unit (Eff (async :: Async e1 | e2)) a`, for synchronous effects `e2`, asynchronous effects `e1`, and value `a`.
+The moral equivalent of `ErrorT (ContT Unit (Eff (async :: Async | e)) a`, for effects `e`.
 
-`Aff` lets you say goodbyte to monad transformers and callback hell!
+`Aff` lets you say goodbye to monad transformers and callback hell!
 
 # Example
 
@@ -35,13 +35,7 @@ deleteBlankLines path =
 
 This looks like ordinary, synchronous, imperative code, but actually operates asynchronously without any callbacks (error handling is baked in so you only deal with it when you want to).
 
-`Aff` represents a computation with a synchronous component (for example, initiating an AJAX request), as well as an asynchronous component (retrieving an error or success response).
-
-For maximum type safety, `Aff` separates the effects of the synchronous part from the asynchronous part. That is, an `Aff` computation may have one set of effects for its synchronous part, and another set for its asynchronous part. 
-
-Asynchronous effects are represented with an `async :: Async e1` effect label, where `e1` is the row of effects for actions that will occur at some indefinite point in the future.
-
-The library contains instances for `Semigroup`, `Monoid`, `Apply`, `Applicative`, `Bind`, `Monad`, `MonadEff`, and `MonadError`. These instances allow you to compose `Aff`-ectful code as easily as `Eff`, as well as interop with existing `Eff` code.
+The library contains instances for `Semigroup`, `Monoid`, `Apply`, `Applicative`, `Bind`, `Monad`, `Alt`, `Plus`, `MonadPlus`, `MonadEff`, and `MonadError`. These instances allow you to compose `Aff`-ectful code as easily as `Eff`, as well as interop with existing `Eff` code.
 
 ## Escaping Callback Hell
 
@@ -50,7 +44,7 @@ Hopefully, you're using libraries that already use the `Aff` type, so you don't
 If you're building your own library, or you have to interact with some native code that expects callbacks, then *purescript-aff* provides a `makeAff` function you can use:
 
 ```purescript
-makeAff :: forall e1 e2 a. ((Error -> Eff e1 Unit) -> (a -> Eff e1 Unit) -> EffA e1 e2 Unit) -> Aff e1 e2 a
+makeAff :: forall e a. ((Error -> Eff e Unit) -> (a -> Eff e Unit) -> EffA e Unit) -> Aff e a
 ```
 
 This function expects you to provide a handler, which should call a user-supplied error callback or success callback with the result of the asynchronous computation.
@@ -68,13 +62,13 @@ function ajaxGet(callback) { // accepts a callback
     }
   }
 }
-""" :: forall e1 e2. (Response -> Eff e1 Unit) -> Request -> EffA e1 (ajax :: Ajax | e2) Unit
+""" :: forall e. (Response -> Eff e Unit) -> Request -> EffA e Unit
 ```
 
 We can wrap this into an asynchronous computation like so:
 
 ```purescript
-ajaxGet' :: forall e1 e2. Request -> Aff e1 (ajax :: Ajax | e2) Response
+ajaxGet' :: forall e. Request -> Aff e Response
 ajaxGet' req = makeAff (\error success -> ajaxGet success req)
 ```
 
@@ -105,23 +99,34 @@ do e <- liftEff' myExcFunc
    liftEff $ either (const $ trace "Oh noes!") (const $ trace "Yays!") e
 ```
 
-## Exceptions
+## Failure
 
 The `Aff` monad has error handling baked in, so ordinarily you don't have to worry about it.
 
 If you want to attempt a computation but recover from failure, you can use the `attempt` function:
 
 ```purescript
-attempt :: forall e1 e2 a. Aff e1 e2 a -> Aff e1 e2 (Either Error a)
+attempt :: forall e a. Aff e a -> Aff e (Either Error a)
 ```
 
-This returns an `Either Error a` you can use to recover gracefully from failure.
+This returns an `Either Error a` that you can use to recover from failure.
 
 ```purescript
 do e <- attempt $ Ajax.get "http://foo.com"
    liftEff $ either (const $ trace "Oh noes!") (const $ trace "Yays!") e
 ```
 
+### Alt
+
+Because `Aff` has an `Alt` instance, you may also use the operator `<|>` to provide an alternative computation in the event of failure:
+
+```purescript
+do result <- Ajax.get "http://foo.com" <|> Ajax.get "http://bar.com"
+   return result
+```
+
+### MonadError
+
 `Aff` has a `MonadError` instance, which comes with two functions: `catchError`, and `throwError`.
 
 These are defined in [purescript-transformers](http://github.com/purescript/purescript-transformers).