Updates for 0.9.1

Author: paf31

learn/eff/index.markdown

@@ -1,7 +1,7 @@
 ---
 title: Handling Native Effects with the Eff Monad
 author: Phil Freeman
-published: 2015-07-16
+published: 2016-05-24
 ---
 
 In this post, I'm going to talk about PureScript's hybrid approach to handling side-effects.
@@ -35,22 +35,22 @@ import Prelude
 
 import Control.Monad.Eff
 import Control.Monad.Eff.Random (random)
-import Control.Monad.Eff.Console (print)
+import Control.Monad.Eff.Console (logShow)
 
 printRandom = do
   n <- random
-  print n
+  logShow n
 ```
 
 This example requires the [`purescript-console`](https://pursuit.purescript.org/packages/purescript-console/) and [`purescript-random`](https://pursuit.purescript.org/packages/purescript-random/) dependencies to be installed:
 
     pulp init
     bower install --save purescript-console purescript-random
 
-If you save this file as `RandomExample.purs`, you will be able to compile and run it using PSCi:
+If you save this file as `src/RandomExample.purs`, you will be able to compile and run it using PSCi:
 
     pulp psci
-    
+
     > import RandomExample
     > printRandom
     ...
@@ -62,8 +62,9 @@ This program uses `do`-notation to combine two types of native effects provided
 #### Extensible Records and Extensible Effects
 
 We can inspect the type of `printRandom` by using the `:type command`
-    
-    > :type RandomExample.main
+
+    > import RandomExample
+    > :type main
 
 The type of `main` will be printed to the console. You should see a type which looks like this:
 
@@ -74,12 +75,12 @@ This type looks quite complicated, but is easily explained by analogy with PureS
 Consider a simple function which uses extensible records:
 
 ``` haskell
-fullName person = person.firstName ++ " " ++ person.lastName
+fullName person = person.firstName <> " " <> person.lastName
 ```
 
 This function creates a full name string from an object containing `firstName` and `lastName` properties. If you find the type of this function in PSCi as before, you will see this:
 
-    forall t. { firstName :: String, lastName :: String | t } -> String 
+    forall t. { firstName :: String, lastName :: String | t } -> String
 
 The readable version of this type is "`fullName` takes an object with `firstName` and `lastName` properties _and any other properties_ and returns a `String`".
 
@@ -90,7 +91,7 @@ That is, `fullName` does not care if you pass an object with _more_ properties,
 Phil Freeman
 ```
 
-Similarly, the type of `printRandom` above can be interpreted as follows: "`printRandom` is a side-effecting computation, which can be run in any environment which supports random number generation and console IO, _and any other types of side effect_, and which yields a value of type `Unit`".
+Similarly, the type of `printRandom` above can be interpreted as follows: "`printRandom` is an effectful computation, which can be run in any environment which supports random number generation and console IO, _and any other types of side effect_, and which yields a value of type `Unit`".
 
 This is the origin of the name "extensible effects": we can always _extend_ the set of side-effects, as long as we can support the set of effects that we need.
 
@@ -106,21 +107,21 @@ which is _not_ the same as the type of `main`.
 
 However, we can instantiate the polymorphic type variable in such a way that the types do match. If we choose `e1 ~ (console :: CONSOLE | e)`, then the two rows are equal, up to reordering.
 
-Similarly, `print` has a type which can be instantiated to match the type of `printRandom`:
+Similarly, `logShow` has a type which can be instantiated to match the type of `printRandom`:
 
-    forall a e2. (Show a) => a -> Eff (console :: CONSOLE | e2) Unit
+    forall a e2. Show a => a -> Eff (console :: CONSOLE | e2) Unit
 
 This time we have to choose `e2 ~ random :: RANDOM | e`.
 
-The key is that we don't have to give a type for `printRandom` in order to be able to find these substitutions. `psc` will find a most general type for `printRandom` given the polymorphic types of `random` and `print`.
+The key is that we don't have to give a type for `printRandom` in order to be able to find these substitutions. `psc` will find a most general type for `printRandom` given the polymorphic types of `random` and `logShow`.
 
 #### Aside: The Kind of Eff
 
 Looking at the [source code](https://github.com/purescript/purescript-eff/blob/master/src/Control/Monad/Eff.purs), you will see the following definition for `Eff`:
 
 ```
 foreign import Eff :: # ! -> * -> *
-``` 
+```
 
 `*` is the usual kind of types, and `!` is the kind of effects. The `#` kind constructor is used to construct kinds for _rows_, i.e. unordered, labelled collections.
 
@@ -138,23 +139,25 @@ If we annotate the previous example with a _closed_ row of effects:
 main :: Eff (console :: CONSOLE, random :: RANDOM) Unit
 main = do
   n <- random
-  print n
+  logShow n
 ```
 
 (note the lack of a type variable here), then we cannot accidentally include a subcomputation which makes use of a different type of effect. This is an advantage of `Eff` over Haskell's more coarsely-grained `IO` monad.
 
 #### Handlers and Actions
 
-Rows of effects can also appear on the left-hand side of a function arrow. This is what differentiates actions like `print` and `random` from effect _handlers_.
+Rows of effects can also appear on the left-hand side of a function arrow. This is what differentiates actions like `logShow` and `random` from effect _handlers_.
 
 While actions _add_ to the set of required effects, a handler `subtracts` effects from the set.
 
 Consider `catchException` from the [`purescript-exceptions`](https://pursuit.purescript.org/packages/purescript-exceptions/) package:
 
 ``` haskell
-catchException :: forall a e. (Error -> Eff e a) -> 
-                              Eff (err :: EXCEPTION | e) a -> 
-                              Eff e a
+catchException
+  :: forall a e
+   . (Error -> Eff e a)
+  -> Eff (err :: EXCEPTION | e) a
+  -> Eff e a
 ```
 
 Note that the type of the effect on the right of the final function arrow requires _fewer_ effects than the effect to its left. Namely, `catchException` _removes_ the `EXCEPTION` effect from the set of required effects.
@@ -165,8 +168,8 @@ For example, we can write a piece of code which uses exceptions, then wrap that
 
 `purescript-eff` also defines the handler `runPure`, which takes a computation with _no_ side-effects, and safely evaluates it as a pure value:
 
-    type Pure a = forall e. Eff e a
-	
+    type Pure a = Eff () a
+
     runPure :: forall a. Pure a -> a
 
 For example, we can define a version of the division function for which division by zero results in an exception:
@@ -175,12 +178,12 @@ For example, we can define a version of the division function for which division
 module ErrorsExample where
 
 import Prelude
-import Control.Monad.Eff
-import Control.Monad.Eff.Exception
+import Control.Monad.Eff (Eff)
+import Control.Monad.Eff.Exception (EXCEPTION, throw)
 
 divide :: forall e. Int -> Int -> Eff (err :: EXCEPTION | e) Int
 divide _ 0 = throw "Division by zero"
-divide n m = return (n / m)
+divide n m = pure (n / m)
 ```
 
 If we have already defined this function, we can use the `runPure` and `catchException` handlers to define a version of `divide` which reports its errors using `Either`:
@@ -198,7 +201,7 @@ Note that _after_ we use `catchException` to remove the `EXCEPTION` effect, ther
 
 New effects can be defined using `foreign import data` just as in the case of types.
 
-Suppose we wanted to define an effect for incrementing a single shared global counter. We simply declare the kind of our new type constructor to be `!`: 
+Suppose we wanted to define an effect for incrementing a single shared global counter. We simply declare the kind of our new type constructor to be `!`:
 
 ```
 foreign import data COUNTER :: !
@@ -240,17 +243,17 @@ exports.unsafeRunCounter = function(f) {
 
 #### The Eff Monad is Magic
 
-The `psc` compiler has special support for the `Eff` monad. Ordinarily, a chain of monadic binds might result in poor performance when executed in `nodejs` or in the browser. However, the compiler can generate code for the `Eff` monad without explicit calls to the monadic bind function `>>=`.
+The `psc` compiler has special support for the `Eff` monad. Ordinarily, a chain of monadic binds might result in poor performance when executed in Node or in the browser. However, the compiler can generate code for the `Eff` monad without explicit calls to the monadic bind function `>>=`.
 
 Take the random number generation from the start of the post. If we compile this example without optimizations, we end up the following Javascript:
 
 ``` javascript
-var main = 
+var main =
   Prelude[">>="]
     (Control_Monad_Eff.monadEff())
 	(Control_Monad_Eff_Random.random)
 	(function (n) {
-      return Control_Monad_Eff_Console.print(Prelude.showNumber())(n);
+      return Control_Monad_Eff_Console.logShow(Prelude.showNumber())(n);
     });
 ```
 
@@ -259,7 +262,7 @@ However, if we use the default optimizations, the calls to `Eff`'s monadic bind
 ``` javascript
 var main = function __do() {
   var n = Control_Monad_Eff_Random.random();
-  return Control_Monad_Eff_Console.print(Prelude.showNumber())(n)();
+  return Control_Monad_Eff_Console.logShow(Prelude.showNumber())(n)();
 };
 ```
 
@@ -269,7 +272,7 @@ The improvement is even more marked when optimizations are used in conjunction w
 
 ``` haskell
 go n = do
-  print n
+  logShow n
   go (n + 1)
 
 main = go 1
@@ -278,10 +281,10 @@ main = go 1
 Without optimizations, the compiler generates the following Javascript, which fails after a few iterations with a stack overflow:
 
 ``` javascript
-var go = 
+var go =
   Prelude[">>="]
     (Control_Monad_Eff.monadEff())
-	(Control_Monad_Eff_Console.print(Prelude.showNumber())(n))
+	(Control_Monad_Eff_Console.logShow(Prelude.showNumber())(n))
 	(function (_) {
       return go(n + 1);
     });
@@ -294,7 +297,7 @@ var go = function (__copy_n) {
   return function __do() {
     var n = __copy_n;
     tco: while (true) {
-      Control_Monad_Eff_Console.print(Prelude.showNumber())(n)();
+      Control_Monad_Eff_Console.logShow(Prelude.showNumber())(n)();
       var __tco_n = n + 1;
       n = __tco_n;
       continue tco;
@@ -314,11 +317,11 @@ collatz :: Int -> Int
 collatz n = pureST do
   r <- newSTRef n
   count <- newSTRef 0
-  untilE $ do
-    modifySTRef count $ (+) 1
+  untilE do
+    modifySTRef count (_ + 1)
     m <- readSTRef r
     writeSTRef r $ if m `mod` 2 == 0 then m / 2 else 3 * m + 1
-    return $ m == 1
+    pure (m == 1)
   readSTRef count
 ```
 
@@ -337,14 +340,13 @@ var collatz = function (n) {
         var m = r;
         r = (m % 2 === 0) ? m / 2 : 3 * m + 1;
         return m === 1;
-      })()) {
-	  };
+      })()) { };
       return {};
     })();
     return count;
   });
 };
-``` 
+```
 
 #### Conclusion
 

learn/ffi/index.markdown

@@ -19,6 +19,8 @@ Let's take the following simple module as an example:
 ``` haskell
 module Test where
 
+import Prelude
+
 gcd :: Int -> Int -> Int
 gcd n m | n == 0 = m
 gcd n m | m == 0 = n
@@ -72,18 +74,6 @@ generates the following Javascript:
 var example$prime = 100;
 ```
 
-This scheme also applies to names of infix operators:
-
-``` haskell
-(%) a b = ...
-```
-
-generates
-
-``` javascript
-var $percent = function(a) { ... }
-```
-
 #### Calling Javascript from PureScript
 
 Javascript values and functions can be used from PureScript by using the FFI. The problem becomes how to choose suitable types for values originating in Javascript.
@@ -94,22 +84,20 @@ The general rule regarding types is that you can enforce as little or as much ty
 
 In PureScript, JavaScript code is wrapped using a _foreign module_. A foreign module is just a CommonJS module which is associated with a PureScript module. Foreign modules are required to adhere to certain conventions:
 
-- The module must contain a comment of the form `// module ModuleName`, which associates the foreign module with its companion PureScript module. 
+- The name of the foreign module must be the same as its companion PureScript module, with its extension changed to `.js`. This associates the foreign module with the PureScript module.
 - All exports must be of the form `exports.name = value;`, specified at the top level.
 
 Here is an example, where we export a function which computes interest amounts from a foreign module:
 
 ```javascript
 "use strict";
 
-// module Interest
-
 exports.calculateInterest = function(amount) {
   return amount * 0.1;
 };
 ```
 
-This file should be saved as `src/Interest.js`. The corresponding PureScript module `Interest` will be saved in `src/Interest.purs` (these filenames are merely conventions, but are used by certain tools, such as the Pulp build tool), and will look like this:
+This file should be saved as `src/Interest.js`. The corresponding PureScript module `Interest` will be saved in `src/Interest.purs`, and will look like this:
 
 ```purescript
 module Interest where
@@ -128,18 +116,18 @@ Suppose we wanted to modify our `calculateInterest` function to take a second ar
 ```javascript
 "use strict";
 
-// module Interest
-
 exports.calculateInterest = function(amount, months) {
   return amount * Math.exp(0.1, months);
 };
 ```
 
-A correct `foreign import` declaration now should use a foreign type whose runtime representation correctly handles functions of multiple arguments. The `purescript-functions` package provides a collection of such types for function arities from 0 to 10: 
+A correct `foreign import` declaration now should use a foreign type whose runtime representation correctly handles functions of multiple arguments. The `purescript-functions` package provides a collection of such types for function arities from 0 to 10:
 
 ```purescript
 module Interest where
 
+import Data.Function (Fn2)
+
 foreign import calculateInterest :: Fn2 Number Number Number
 ```
 
@@ -155,8 +143,6 @@ An alternative is to use curried functions in the native module, using multiple
 ```javascript
 "use strict";
 
-// module Interest
-
 exports.calculateInterest = function(amount) {
   return function(months) {
     return amount * Math.exp(0.1, months);
@@ -179,9 +165,10 @@ For example, let's write a simple PureScript function with a constrained type, a
 ``` haskell
 module Test where
 
-import Data.Tuple
+import Prelude
+import Data.Tuple (Tuple(..))
 
-inOrder :: forall a. (Ord a) => a -> a -> Tuple a a
+inOrder :: forall a. Ord a => a -> a -> Tuple a a
 inOrder a1 a2 | a1 < a2 = Tuple a1 a2
 inOrder a1 a2 = Tuple a2 a1
 ```

learn/generic/index.markdown

@@ -13,8 +13,8 @@ PureScript's generics are supported by the `purescript-generics` library, and in
 ``` haskell
 class Generic a where
   toSignature :: Proxy a -> GenericSignature
-  toSpine :: a -> GenericSpine
-  fromSpine :: GenericSpine -> Maybe a
+  toSpine     :: a -> GenericSpine
+  fromSpine   :: GenericSpine -> Maybe a
 ```
 
 `Generic` defines three functions:
@@ -80,7 +80,7 @@ This is not too bad, but real-world records often contain many more fields. Let'
 The `purescript-foreign-generic` library defines a function `readGeneric`, with the following type:
 
 ``` haskell
-readGeneric :: forall a. (Generic a) => Options -> Foreign -> F a
+readGeneric :: forall a. Generic a => Options -> Foreign -> F a
 ```
 
 The `Options` type here is based on the options record from Haskell's `aeson` library. For our purposes, the default options will work, but we need to turn on the `unwrapNewtypes` option, so that our `newtype` constructor gets ignored during serialization: