Improve from and to documentations

doc/from.md

@@ -2,7 +2,7 @@
 language: en
 layout: page
 title: "Reading data from a source"
-date: 2013-03-31T21:12:03.752Z
+date: 2013-04-27T09:38:47.376Z
 comments: false
 sharing: false
 footer: false
@@ -109,18 +109,40 @@ csv()
 
 
 
+<a name="from.stream"></a>
+`from.stream(stream, [options])`
+--------------------------------
+
+Read from a stream. Take a readable stream as first argument and optionally 
+an object of options as a second argument.
+
+Additionnal options may be defined. See the [`readable.pipe` 
+documentation][srpdo] for additionnal information.
+
+[srpdo]: http://www.nodejs.org/api/stream.html#stream_readable_pipe_destination_options
+
+
 <a name="from.path"></a>
 `from.path(path, [options])`
 ----------------------------
 
 Read from a file path. Take a file path as first argument and optionally an object 
 of options as a second argument.
 
+Additionnal options may be defined with the following default:
 
-<a name="from.stream"></a>
-`from.stream(stream, [options])`
---------------------------------
+```javascript
 
-Read from a stream. Take a readable stream as first argument and optionally 
-an object of options as a second argument.
+{ flags: 'r',
+  encoding: null,
+  fd: null,
+  mode: 0666,
+  bufferSize: 64 * 1024,
+  autoClose: true }
+
+```
+
+See the [`fs.createReadStream` documentation][fscpo] for additionnal information.
+
+[fscpo]: http://www.nodejs.org/api/fs.html#fs_fs_createreadstream_path_options
 

doc/to.md

@@ -2,7 +2,7 @@
 language: en
 layout: page
 title: "Writing data to a destination"
-date: 2013-01-27T18:19:43.154Z
+date: 2013-04-27T09:38:47.377Z
 comments: false
 sharing: false
 footer: false
@@ -107,6 +107,11 @@ Callback is called with 2 arguments:
 Write to a stream. Take a writable stream as first argument and  
 optionally an object of options as a second argument.
 
+Additionnal options may be defined. See the [`readable.pipe` 
+documentation][srpdo] for additionnal information.
+
+[srpdo]: http://www.nodejs.org/api/stream.html#stream_readable_pipe_destination_options
+
 
 <a name="to.path"></a>
 `to.path(path, [options])`
@@ -117,6 +122,31 @@ options as a second argument. The `close` event is sent after the file is writte
 Relying on the `end` event is incorrect because it is sent when parsing is done 
 but before the file is written.
 
+Additionnal options may be defined with the following default:
+
+```javascript
+
+{ flags: 'w',
+  encoding: null,
+  mode: 0666 }
+
+```
+
+See the [`fs.createReadStream` documentation][fscpo] for additionnal information.
+
+[fscpo]: http://www.nodejs.org/api/fs.html#fs_fs_createwritestream_path_options
+
+Example to modify a file rather than replacing it:
+
+```javascript
+
+csv()
+.to.file('my.csv', {flags:'r+'})
+.write(['hello', 'node'])
+.end()
+```
+
+
 
 <a name="to.array"></a>
 `to.array(path, [options])`

src/from.coffee

@@ -150,32 +150,50 @@ module.exports = (csv) ->
 
   ###
   
-  `from.path(path, [options])`
-  ----------------------------
-  
-  Read from a file path. Take a file path as first argument and optionally an object 
-  of options as a second argument.
-  
-  ###
-  from.path = (path, options) ->
-    @options options
-    stream = fs.createReadStream path, csv.from.options()
-    csv.from.stream stream
-
-  ###
-  
   `from.stream(stream, [options])`
   --------------------------------
   
   Read from a stream. Take a readable stream as first argument and optionally 
   an object of options as a second argument.
+
+  Additionnal options may be defined. See the [`readable.pipe` 
+  documentation][srpdo] for additionnal information.
   
+  [srpdo]: http://www.nodejs.org/api/stream.html#stream_readable_pipe_destination_options
+
   ###
   from.stream = (stream, options) ->
     @options options if options
     stream.setEncoding csv.from.options().encoding if stream.setEncoding
     stream.pipe csv, csv.from.options()
     csv
+
+  ###
+  
+  `from.path(path, [options])`
+  ----------------------------
+  
+  Read from a file path. Take a file path as first argument and optionally an object 
+  of options as a second argument.
+
+  Additionnal options may be defined with the following default:
+
+      { flags: 'r',
+        encoding: null,
+        fd: null,
+        mode: 0666,
+        bufferSize: 64 * 1024,
+        autoClose: true }
+
+  See the [`fs.createReadStream` documentation][fscpo] for additionnal information.
+  
+  [fscpo]: http://www.nodejs.org/api/fs.html#fs_fs_createreadstream_path_options
+
+  ###
+  from.path = (path, options) ->
+    @options options
+    stream = fs.createReadStream path, csv.from.options()
+    csv.from.stream stream
 
   from
 

src/to.coffee

@@ -147,6 +147,11 @@ module.exports = (csv) ->
 
   Write to a stream. Take a writable stream as first argument and  
   optionally an object of options as a second argument.
+
+  Additionnal options may be defined. See the [`readable.pipe` 
+  documentation][srpdo] for additionnal information.
+  
+  [srpdo]: http://www.nodejs.org/api/stream.html#stream_readable_pipe_destination_options
   
   ###
   to.stream = (stream, options) ->
@@ -167,7 +172,24 @@ module.exports = (csv) ->
   options as a second argument. The `close` event is sent after the file is written. 
   Relying on the `end` event is incorrect because it is sent when parsing is done 
   but before the file is written.
+
+  Additionnal options may be defined with the following default:
+
+      { flags: 'w',
+        encoding: null,
+        mode: 0666 }
+
+  See the [`fs.createReadStream` documentation][fscpo] for additionnal information.
   
+  [fscpo]: http://www.nodejs.org/api/fs.html#fs_fs_createwritestream_path_options
+  
+  Example to modify a file rather than replacing it:
+
+      csv()
+      .to.file('my.csv', {flags:'r+'})
+      .write(['hello', 'node'])
+      .end()
+
   ###
   to.path = (path, options) ->
     # Merge user provided options

test/columns.coffee

@@ -24,7 +24,7 @@ describe 'columns', ->
         record.should.be.a 'object'
         record.should.not.be.an.instanceof Array
         if index is 0
-          record.FIELD_1.should.eql '20322051544'
+          record.should.eql FIELD_1: '20322051544', FIELD_2: '1979', FIELD_3: '8.8017226E7', FIELD_4: 'ABC', FIELD_5: '45', FIELD_6: '2000-01-01'
         else if index is 1
           record.FIELD_4.should.eql 'DEF'
         record
@@ -33,7 +33,7 @@ describe 'columns', ->
         record.should.not.be.an.instanceof Array
         index.should.eql count
         if index is 0
-          record.FIELD_1.should.eql '20322051544'
+          record.should.eql FIELD_1: '20322051544', FIELD_2: '1979', FIELD_3: '8.8017226E7', FIELD_4: 'ABC', FIELD_5: '45', FIELD_6: '2000-01-01'
         else if index is 1
           record.FIELD_4.should.eql 'DEF'
         count++