Merge pull request #4 from purescript-node/change-types

Remove the last parameter to Stream

Author: hdgarrood

.jshintrc

@@ -0,0 +1,20 @@
+{
+  "bitwise": true,
+  "eqeqeq": true,
+  "forin": true,
+  "freeze": true,
+  "funcscope": true,
+  "futurehostile": true,
+  "globalstrict": true,
+  "latedef": true,
+  "maxparams": 1,
+  "noarg": true,
+  "nocomma": true,
+  "nonew": true,
+  "notypeof": true,
+  "singleGroups": true,
+  "undef": true,
+  "unused": true,
+  "eqnull": true
+}
+

.travis.yml

@@ -0,0 +1,15 @@
+language: node_js
+sudo: false
+node_js:
+  - 4.2
+  - 5.2
+env:
+  - PATH=$HOME/purescript:$PATH
+install:
+  - TAG=$(wget -q -O - https://github.com/purescript/purescript/releases/latest --server-response --max-redirect 0 2>&1 | sed -n -e 's/.*Location:.*tag\///p')
+  - wget -O $HOME/purescript.tar.gz https://github.com/purescript/purescript/releases/download/$TAG/linux64.tar.gz
+  - tar -xvf $HOME/purescript.tar.gz -C $HOME/
+  - chmod a+x $HOME/purescript
+  - npm install
+script:
+  - npm run build

README.md

@@ -3,4 +3,4 @@
 A wrapper for Node's Stream API
 
 - [Module Documentation](docs/)
-- [Example](test/Main.purs)
+- [Example](example/Gzip.purs)

bower.json

@@ -14,11 +14,14 @@
     "url": "git://github.com/purescript-node/purescript-node-streams.git"
   },
   "devDependencies": {
-    "purescript-console": "^0.1.0"
+    "purescript-console": "^0.1.0",
+    "purescript-assert": "~0.1.1"
   },
   "dependencies": {
     "purescript-eff": "~0.1.1",
     "purescript-node-buffer": "~0.2.0",
-    "purescript-prelude": "~0.1.2"
+    "purescript-prelude": "~0.1.2",
+    "purescript-either": "~0.2.3",
+    "purescript-exceptions": "~0.3.3"
   }
 }

docs/Node/Stream.md

@@ -5,7 +5,7 @@ This module provides a low-level wrapper for the Node Stream API.
 #### `Stream`
 
 ``` purescript
-data Stream :: # * -> # ! -> * -> *
+data Stream :: # * -> # ! -> *
 ```
 
 A stream.
@@ -14,7 +14,6 @@ The type arguments track, in order:
 
 - Whether reading and/or writing from/to the stream are allowed.
 - Effects associated with reading/writing from/to this stream.
-- The type of chunks which will be read from/written to this stream (`String` or `Buffer`).
 
 #### `Read`
 
@@ -56,122 +55,152 @@ type Duplex = Stream (read :: Read, write :: Write)
 
 A duplex (readable _and_ writable stream)
 
-#### `setEncoding`
+#### `onData`
 
 ``` purescript
-setEncoding :: forall w eff. Readable w eff String -> Encoding -> Eff eff Unit
+onData :: forall w eff. Readable w (err :: EXCEPTION | eff) -> (Buffer -> Eff (err :: EXCEPTION | eff) Unit) -> Eff (err :: EXCEPTION | eff) Unit
 ```
 
-Set the encoding used to read chunks from the stream.
+Listen for `data` events, returning data in a Buffer. Note that this will fail
+if `setEncoding` has been called on the stream.
 
-#### `onData`
+#### `onDataString`
+
+``` purescript
+onDataString :: forall w eff. Readable w (err :: EXCEPTION | eff) -> Encoding -> (String -> Eff (err :: EXCEPTION | eff) Unit) -> Eff (err :: EXCEPTION | eff) Unit
+```
+
+Listen for `data` events, returning data in a String, which will be
+decoded using the given encoding. Note that this will fail if `setEncoding`
+has been called on the stream.
+
+#### `onDataEither`
 
 ``` purescript
-onData :: forall w eff a. Readable w eff a -> (a -> Eff eff Unit) -> Eff eff Unit
+onDataEither :: forall w eff. Readable w eff -> (Either String Buffer -> Eff eff Unit) -> Eff eff Unit
 ```
 
-Listen for `data` events.
+Listen for `data` events, returning data in an `Either String Buffer`. This
+function is provided for the (hopefully rare) case that `setEncoding` has
+been called on the stream.
+
+#### `setEncoding`
+
+``` purescript
+setEncoding :: forall w eff. Readable w eff -> Encoding -> Eff eff Unit
+```
+
+Set the encoding used to read chunks as strings from the stream. This
+function may be useful when you are passing a readable stream to some other
+JavaScript library, which already expects an encoding to be set.
+
+Where possible, you should try to use `onDataString` instead of this
+function.
 
 #### `onEnd`
 
 ``` purescript
-onEnd :: forall w eff a. Readable w eff a -> Eff eff Unit -> Eff eff Unit
+onEnd :: forall w eff. Readable w eff -> Eff eff Unit -> Eff eff Unit
 ```
 
 Listen for `end` events.
 
 #### `onClose`
 
 ``` purescript
-onClose :: forall w eff a. Readable w eff a -> Eff eff Unit -> Eff eff Unit
+onClose :: forall w eff. Readable w eff -> Eff eff Unit -> Eff eff Unit
 ```
 
 Listen for `close` events.
 
 #### `onError`
 
 ``` purescript
-onError :: forall w eff a. Readable w eff a -> Eff eff Unit -> Eff eff Unit
+onError :: forall w eff. Readable w eff -> Eff eff Unit -> Eff eff Unit
 ```
 
 Listen for `error` events.
 
 #### `resume`
 
 ``` purescript
-resume :: forall w eff a. Readable w eff a -> Eff eff Unit
+resume :: forall w eff. Readable w eff -> Eff eff Unit
 ```
 
 Resume reading from the stream.
 
 #### `pause`
 
 ``` purescript
-pause :: forall w eff a. Readable w eff a -> Eff eff Unit
+pause :: forall w eff. Readable w eff -> Eff eff Unit
 ```
 
 Pause reading from the stream.
 
 #### `isPaused`
 
 ``` purescript
-isPaused :: forall w eff a. Readable w eff a -> Eff eff Boolean
+isPaused :: forall w eff. Readable w eff -> Eff eff Boolean
 ```
 
 Check whether or not a stream is paused for reading.
 
 #### `pipe`
 
 ``` purescript
-pipe :: forall r w eff a. Readable w eff a -> Writable r eff a -> Eff eff (Writable r eff a)
+pipe :: forall r w eff. Readable w eff -> Writable r eff -> Eff eff (Writable r eff)
 ```
 
 Read chunks from a readable stream and write them to a writable stream.
 
 #### `write`
 
 ``` purescript
-write :: forall r eff a. Writable r eff String -> a -> Eff eff Unit -> Eff eff Boolean
+write :: forall r eff. Writable r eff -> Buffer -> Eff eff Unit -> Eff eff Boolean
 ```
 
-Write a chunk to a writable stream.
+Write a Buffer to a writable stream.
 
 #### `writeString`
 
 ``` purescript
-writeString :: forall r eff. Writable r eff String -> Encoding -> String -> Eff eff Unit -> Eff eff Boolean
+writeString :: forall r eff. Writable r eff -> Encoding -> String -> Eff eff Unit -> Eff eff Boolean
 ```
 
 Write a string in the specified encoding to a writable stream.
 
 #### `cork`
 
 ``` purescript
-cork :: forall r eff a. Writable r eff a -> Eff eff Unit
+cork :: forall r eff. Writable r eff -> Eff eff Unit
 ```
 
 Force buffering of writes.
 
 #### `uncork`
 
 ``` purescript
-uncork :: forall r eff a. Writable r eff a -> Eff eff Unit
+uncork :: forall r eff. Writable r eff -> Eff eff Unit
 ```
 
 Flush buffered data.
 
 #### `setDefaultEncoding`
 
 ``` purescript
-setDefaultEncoding :: forall r eff. Writable r eff String -> Encoding -> Eff eff Unit
+setDefaultEncoding :: forall r eff. Writable r eff -> Encoding -> Eff eff Unit
 ```
 
-Set the default encoding used to write chunks to the stream.
+Set the default encoding used to write strings to the stream. This function
+is useful when you are passing a writable stream to some other JavaScript
+library, which already expects a default encoding to be set. It has no
+effect on the behaviour of the `writeString` function (because that
+function ensures that the encoding is always supplied explicitly).
 
 #### `end`
 
 ``` purescript
-end :: forall r eff a. Writable r eff a -> Eff eff Unit -> Eff eff Unit
+end :: forall r eff. Writable r eff -> Eff eff Unit -> Eff eff Unit
 ```
 
 End writing data to the stream.

example/Gzip.js

@@ -0,0 +1,9 @@
+/* global exports */
+/* global require */
+"use strict";
+
+// module Gzip
+
+exports.gzip = require('zlib').createGzip;
+exports.stdout = process.stdout;
+exports.stdin = process.stdin;

example/Gzip.purs

@@ -0,0 +1,19 @@
+module Gzip where
+
+import Prelude
+
+import Node.Stream
+
+import Control.Monad.Eff
+import Control.Monad.Eff.Console
+
+foreign import data GZIP :: !
+
+foreign import gzip :: forall eff. Eff (gzip :: GZIP | eff) (Duplex (gzip :: GZIP | eff))
+foreign import stdin :: forall eff. Readable () (console :: CONSOLE | eff)
+foreign import stdout :: forall eff. Writable () (console :: CONSOLE | eff)
+
+main = do
+  z <- gzip
+  stdin `pipe` z
+  z     `pipe` stdout

package.json

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "scripts": {
+    "postinstall": "pulp dep install",
+    "build": "jshint src && pulp build && rimraf docs && pulp docs"
+  },
+  "devDependencies": {
+    "jshint": "^2.8.0",
+    "pulp": "^4.0.2",
+    "rimraf": "^2.4.1",
+    "stream-buffers": "^3.0.0"
+  }
+}

src/Node/Stream.js

@@ -1,3 +1,5 @@
+/* global exports */
+/* global Buffer */
 "use strict";
 
 // module Node.Stream
@@ -10,12 +12,27 @@ exports.setEncodingImpl = function(s) {
     };
 };
 
-exports.onData = function(s) {
-    return function(f) {
-        return function() {
-            s.on('data', function(chunk) {
-                f(chunk)();
-            });
+exports.onDataEitherImpl = function(left){
+    return function(right){
+        return function(s) {
+            return function(f) {
+                return function() {
+                    s.on('data', function(chunk) {
+                        if (chunk instanceof Buffer) {
+                            f(right(chunk))();
+                        }
+                        else if (typeof chunk === "string") {
+                            f(left(chunk))();
+                        }
+                        else {
+                            throw new Error(
+                                "Node.Stream.onDataEitherImpl: Unrecognised" +
+                                "chunk type; expected String or Buffer, got:" +
+                                chunk);
+                        }
+                    });
+                };
+            };
         };
     };
 };