add some examples and update comments and README

.travis.yml

@@ -14,6 +14,7 @@ install:
   - bower install
 script:
   - npm run -s build
+  - npm test
 after_success:
 - >-
   test $TRAVIS_TAG &&

README.md

@@ -3,14 +3,44 @@
 [![Latest release](http://img.shields.io/github/release/purescript/purescript-refs.svg)](https://github.com/purescript/purescript-refs/releases)
 [![Build status](https://travis-ci.org/purescript/purescript-refs.svg?branch=master)](https://travis-ci.org/purescript/purescript-refs)
 
-Mutable value references.
+This module defines functions for working with mutable value references.
+
+_Note_: [`Control.Monad.ST`](https://pursuit.purescript.org/packages/purescript-st/4.0.0/docs/Control.Monad.ST) provides a _safe_ alternative to `Ref` when mutation is restricted to a local scope.
 
 ## Installation
 
 ```
 bower install purescript-refs
 ```
 
+## Example
+
+```purs
+main = do
+  -- initialize a new Ref with the value 0
+  ref <- Ref.new 0
+
+  -- read from it and check it
+  curr1 <- Ref.read ref
+  assertEqual { actual: curr1, expected: 0 }
+
+  -- write over the ref with 1
+  Ref.write 1 ref
+
+  -- now it is 1 when we read out the value
+  curr2 <- Ref.read ref
+  assertEqual { actual: curr2, expected: 1 }
+
+  -- modify it by adding 1 to the current state
+  Ref.modify_ (\s -> s + 1) ref
+
+  -- now it is 2 when we read out the value
+  curr3 <- Ref.read ref
+  assertEqual { actual: curr3, expected: 2 }
+```
+
+See [tests](test/Main.purs) to see usages.
+
 ## Documentation
 
 Module documentation is [published on Pursuit](http://pursuit.purescript.org/packages/purescript-refs).

bower.json

@@ -18,5 +18,8 @@
   "dependencies": {
     "purescript-effect": "^2.0.0",
     "purescript-prelude": "^4.0.0"
+  },
+  "devDependencies": {
+    "purescript-assert": "^4.0.0"
   }
 }

package.json

@@ -2,6 +2,7 @@
   "private": true,
   "scripts": {
     "clean": "rimraf output && rimraf .pulp-cache",
+    "test": "pulp test",
     "build": "eslint src && pulp build -- --censor-lib --strict"
   },
   "devDependencies": {

src/Effect/Ref.purs

@@ -1,9 +1,7 @@
--- | This module defines an effect and actions for working with
--- | global mutable variables.
+-- | This module defines actions for working with mutable value references.
 -- |
--- | _Note_: `Control.Monad.ST` provides a _safe_ alternative
--- | to global mutable variables when mutation is restricted to a
--- | local scope.
+-- | _Note_: `Control.Monad.ST` provides a _safe_ alternative to `Ref` when
+-- | mutation is restricted to a local scope.
 module Effect.Ref where
 
 import Prelude

test/Main.purs

@@ -0,0 +1,30 @@
+module Test.Main where
+
+import Prelude
+
+import Effect (Effect)
+import Effect.Ref as Ref
+import Test.Assert (assertEqual)
+
+main :: Effect Unit
+main = do
+  -- initialize a new Ref with the value 0
+  ref <- Ref.new 0
+
+  -- read from it and check it
+  curr1 <- Ref.read ref
+  assertEqual { actual: curr1, expected: 0 }
+
+  -- write over the ref with 1
+  Ref.write 1 ref
+
+  -- now it is 1 when we read out the value
+  curr2 <- Ref.read ref
+  assertEqual { actual: curr2, expected: 1 }
+
+  -- modify it by adding 1 to the current state
+  Ref.modify_ (\s -> s + 1) ref
+
+  -- now it is 2 when we read out the value
+  curr3 <- Ref.read ref
+  assertEqual { actual: curr3, expected: 2 }