Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

v0.2.2

  • Loading branch information...
commit f915fafdc780a6b98409eeb6e6386a80c16cee97 1 parent f5defc6
Gabriel Llamas authored
1  .gitignore
... ...
@@ -0,0 +1 @@
  1
+node_modules
5  CHANGES
... ...
@@ -1,3 +1,8 @@
  1
+v0.2.2 (10 Dec 2012)
  2
+	Added "mode" and "start" to the "open()" parameters.
  3
+	Added "writeln()".
  4
+	Added "flush()".
  5
+
1 6
 v0.2.1 (09 Dec 2012)
2 7
 	An INVALID_DATA error is emitted if the data to write is invalid.
3 8
 
36  README.md
Source Rendered
@@ -5,7 +5,7 @@ _Node.js project_
5 5
 
6 6
 #### Writes buffered data ####
7 7
 
8  
-Version: 0.2.1
  8
+Version: 0.2.2
9 9
 
10 10
 Node.js streams are not buffered, that is, when you write data to them you're doing multiple I/O calls. This module buffers the data that has to be written to disk and eases the buffer manipulation when you need to write data from different nature (strings, numbers, arrays or buffers).
11 11
 
@@ -38,19 +38,49 @@ When you call to `open()` a stream a `Writer` instance is returned. This object
38 38
 - [bw.open(file[, settings])](#open)
39 39
 - [Writer#close([callback])](#close)
40 40
 - [Writer#line()](#line)
41  
-- [Writer#write(buffer[, offset[, length]])](#write)
  41
+- [Writer#write(data[, offset[, length]])](#write)
  42
+- [Writer#writeln(data[, offset[, length]])](#writeln)
42 43
 
43 44
 <a name="open"></a>
44 45
 __bw.open(file[, settings])__  
  46
+Creates a `Writer` and opens a stream to the given file. If the file doesn't exist it is created. The possible settings are:
45 47
 
  48
+- bufferSize. _Number_. The buffer size. It must be greater than 0. Default is 16KB.
  49
+- encoding. _String_. The file encoding. Is only used when strings are written, that is, this parameter is ignored when arrays, numbers and buffers are written. Default is "utf8". Possible values are: "ascii", "utf8", "utf16le", "ucs2", "base64", "hex".
  50
+- append. _Boolean_. If true appends the date, if false the file is truncated. Default is false.
  51
+
  52
+Returns the new `Writer` instance.
46 53
 
47 54
 <a name="close"></a>
48 55
 __Writer#close([callback])__  
  56
+Flushes the remaining data and closes the `Writer`. The callback doesn't receive any parameter.
  57
+
  58
+<a name="flush"></a>
  59
+__Writer#flush(callback)__  
  60
+Flushes the current data. After the callback is executed it's safe to read back the written data, the data has been stored successfully. The callback doesn't receive any parameter.
49 61
 
  62
+This function is typically used when you need to ensure that the data is flushed to the disk at some point before closing the stream.
50 63
 
51 64
 <a name="line"></a>
52 65
 __Writer#line()__  
  66
+Writes a line, OS dependent, `\r\n` on Windows, `\n` otherwise.
53 67
 
  68
+Returns the `Writer` instance for chaining methods.
54 69
 
55 70
 <a name="write"></a>
56  
-__Writer#write(buffer[, offset[, length]])__  
  71
+__Writer#write(data[, offset[, length]])__  
  72
+Writes data. It's not flushed to the underlying I/O layer, it's queued to a buffer and when it's full it's flushed to the disk.
  73
+
  74
+The data can be a Number, String, Array or Buffer.
  75
+- Number. Is stored in big endian, e.g.: 0x0102  will be stored as [0x01, 0x02], 0x01 in a lower address.
  76
+- String. The `open()`'s encoding parameter is used.
  77
+- Array. An array of numbers. They are stored in the same order.
  78
+- Buffer. The Node.js built-in Buffer.
  79
+
  80
+Returns the `Writer` instance for chaining methods.
  81
+
  82
+<a name="writeln"></a>
  83
+__Writer#writeln(data[, offset[, length]])__  
  84
+Does the same than `write()` but stringifies the data and concatenates an EOL, OS dependent, `\r\n` on Windows, `\n` otherwise.
  85
+
  86
+The offset and length specifies the slice of the given piece of data that will be written. By default offset is 0 and length is the last byte/character. The offset and length are applied to the string characters, not the bytes, for example, `write("↑a", 1)` will write `a` because offset is 1. Take into account that `↑` is encoded with 3 bytes in utf8.
33  buffered-writer.js
@@ -18,6 +18,7 @@ var BUFFER_SIZE = 16384;
18 18
 var EOL = process.platform === "win32"
19 19
 		? new Buffer ([0x0d, 0x0a])
20 20
 		: new Buffer ([0x0a]);
  21
+var strEOL = EOL.toString ();
21 22
 
22 23
 var bw = module.exports = {};
23 24
 
@@ -39,13 +40,21 @@ var Writer = function (file, args){
39 40
 	this._buffer = null;
40 41
 	this._offset = 0;
41 42
 	this._closed = false;
  43
+	this._flushCallback;
42 44
 	
43 45
 	var me = this;
44 46
 	this._stream = FS.createWriteStream (file, {
45 47
 		flags: args.append ? "a" : "w",
46  
-		encoding: args.encoding
  48
+		encoding: args.encoding,
  49
+		mode: args.mode,
  50
+		start: args.start
47 51
 	}).on ("error", function (error){
48 52
 		me.emit ("error", error);
  53
+	}).on ("drain", function (){
  54
+		if (me._flushCallback){
  55
+			me._flushCallback ();
  56
+			me._flushCallback = null;
  57
+		}
49 58
 	});
50 59
 };
51 60
 
@@ -61,9 +70,12 @@ Writer.prototype._error = function (error){
61 70
 };
62 71
 
63 72
 Writer.prototype._flush = function (){
64  
-	this._stream.write (new Buffer (this._offset !== this._bufferSize ?
65  
-		this._buffer.slice (0, this._offset) : this._buffer));
  73
+	var written = this._stream.write (
  74
+			new Buffer (this._offset !== this._bufferSize
  75
+					? this._buffer.slice (0, this._offset)
  76
+					: this._buffer));
66 77
 	this._offset = 0;
  78
+	return written;
67 79
 };
68 80
 
69 81
 Writer.prototype._write = function (data, offset, length){
@@ -102,10 +114,19 @@ Writer.prototype.close = function (cb){
102 114
 	this._stream.on ("close", function (){
103 115
 		if (cb) cb ();
104 116
 	});
105  
-	this._stream.destroySoon ();
  117
+	this._stream.end ();
106 118
 	this._closed = true;
107 119
 };
108 120
 
  121
+Writer.prototype.flush = function (cb){
  122
+	if (this._offset === 0) return cb ();
  123
+	if (!this._flush ()){
  124
+		this._flushCallback = cb;
  125
+	}else{
  126
+		cb ();
  127
+	}
  128
+};
  129
+
109 130
 Writer.prototype.line = function (){
110 131
 	if (this._closed){
111 132
 		return this._error (errno.get ("STREAM_CLOSED"));
@@ -170,4 +191,8 @@ Writer.prototype.write = function (buffer, offset, length){
170 191
 		this._write (buffer, offset, length);
171 192
 	}
172 193
 	return this;
  194
+};
  195
+
  196
+Writer.prototype.writeln = function (buffer, offset, length){
  197
+	return this.write (buffer + strEOL, offset, length);
173 198
 };
2  package.json
... ...
@@ -1,6 +1,6 @@
1 1
 {
2 2
 	"name": "buffered-writer",
3  
-	"version": "0.2.1",
  3
+	"version": "0.2.2",
4 4
 	"description": "Writes buffered data to files",
5 5
 	"keywords": ["buffer", "write", "stream", "file", "binary", "data"],
6 6
 	"author": {
55  tests/buffered-writer.js
@@ -36,6 +36,36 @@ describe ("buffered-writer", function (){
36 36
 		});
37 37
 	});
38 38
 	
  39
+	describe ("flush", function (){
  40
+		it ("should flush the buffered data to the disk", function (done){
  41
+			var out = bw.open ("file").write ("a");
  42
+			out.flush (function (){
  43
+				FS.readFile ("file", function (error, data){
  44
+					if (error) return done (error);
  45
+					out.close ();
  46
+					ASSERT.equal (data.toString (), "a");
  47
+					done ();
  48
+				});
  49
+			});
  50
+		});
  51
+		
  52
+		it ("shouldn't flush if there's no buffered data", function (done){
  53
+			var out = bw.open ("file");
  54
+			//Hack
  55
+			out._flush = function (){
  56
+				ASSERT.fail ();
  57
+			};
  58
+			out.flush (function (){
  59
+				out.close ();
  60
+				done ();
  61
+			});
  62
+		});
  63
+		
  64
+		afterEach (function (done){
  65
+			FS.unlink ("file", done);
  66
+		});
  67
+	});
  68
+	
39 69
 	describe ("line", function (){
40 70
 		it ("should emit a STREAM_CLOSED error if a line() has been executed " +
41 71
 				"after closing the stream", function (done){
@@ -300,8 +330,7 @@ describe ("buffered-writer", function (){
300 330
 		
301 331
 		it ("should apply offset and length (length not set, String)",
302 332
 				function (done){
303  
-			bw.open ("file").write ("↑sd", 1)
304  
-					.close (function (){
  333
+			bw.open ("file").write ("↑sd", 1).close (function (){
305 334
 				FS.readFile ("file", function (error, data){
306 335
 					if (error) return done (error);
307 336
 					ASSERT.ok (data[0] === 115 && data[1] === 100);
@@ -383,4 +412,26 @@ describe ("buffered-writer", function (){
383 412
 			FS.unlink ("file", done);
384 413
 		});
385 414
 	});
  415
+	
  416
+	describe ("writeln", function (){
  417
+		it ("should write an EOL after the given data (the data is stringified)",
  418
+				function (done){
  419
+			bw.open ("file").writeln ("a").close (function (){
  420
+				FS.readFile ("file", function (error, data){
  421
+					if (error) return done (error);
  422
+					ASSERT.ok (data[0] === 0x61);
  423
+					if (WIN){
  424
+						ASSERT.ok (data[1] === 0x0d && data[2] === 0x0a);
  425
+					}else{
  426
+						ASSERT.ok (data[1] === 0x0a);
  427
+					}
  428
+					done ();
  429
+				});
  430
+			});
  431
+		});
  432
+	
  433
+		after (function (done){
  434
+			FS.unlink ("file", done);
  435
+		});
  436
+	});
386 437
 });

0 notes on commit f915faf

Please sign in to comment.
Something went wrong with that request. Please try again.