update doc

Author: noogen

bin/text-file-diff

@@ -18,10 +18,10 @@ const lfd = new LargeFileDiff({
 });
 
 lfd.on('+', line => {
-  console.log('+' + line);
+  console.log('+|' + line);
 });
 
 lfd.on('-', line => {
-  console.log('-' + line);
+  console.log('-|' + line);
 });
 lfd.diff(file1, file2);

index.js

@@ -15,8 +15,8 @@ function defaultLineComparer(line1, line2) {
 
 /**
  * custom line reader for better control of file
- * @param  {[type]} file [description]
- * @return {[type]}      [description]
+ * @param  String file path of file
+ * @return Object      custom linereader
  */
 function myLineReader(file) {
   const rst = new ReadlinesSync(file);
@@ -40,10 +40,6 @@ function myLineReader(file) {
 
 /**
  * line by line diff of two files
- * 1.  foreach line of file1, compare each line of file2
- *  equal: incr both files to next line
- *  line1 > line2: must be new line in file2, inc file2 to next line
- *  line1 < line2: must be deleted line, inc file1 to next line
  */
 class FileDiffLine extends EventEmitter {
   /**
@@ -66,6 +62,7 @@ class FileDiffLine extends EventEmitter {
     const lineReader1 = myLineReader(file1);
     const lineReader2 = myLineReader(file2);
     const compareFn = this.compareFn || defaultLineComparer;
+    const charset = this.charset || 'utf8';
 
     if (this.skipHeader) {
       lineReader1.moveNext();
@@ -75,8 +72,8 @@ class FileDiffLine extends EventEmitter {
     // while both files has valid val
     while (lineReader1.val || lineReader2.val) {
       // foreach line of file1, compare each line of file2
-      const line1 = lineReader1.val.toString('utf8');
-      const line2 = lineReader2.val.toString('utf8');
+      const line1 = lineReader1.val.toString(charset);
+      const line2 = lineReader2.val.toString(charset);
       const cmp = compareFn(line1, line2);
 
       // emit on compared

package.json

@@ -1,6 +1,6 @@
 {
   "name": "text-file-diff",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "line by line diff of two large files",
   "license": "MIT",
   "repository": "niiknow/text-file-diff",

readme.md

@@ -1,15 +1,22 @@
 [![Build Status](https://travis-ci.org/niiknow/text-file-diff.svg?branch=master)](https://travis-ci.org/niiknow/text-file-diff)
 # text-file-diff
-> line by line diff of two large text files
+> line by line diff of two large (sorted) text files
 
-You need a nodejs tool to diff two large text files.  This is also useful with csv files:
+This is especially useful with csv/tsv/psv files:
 - compare products file for changes to import
 - compare log files 
-- compare database of employee/users 
+- compare database export of large organization employee/users 
 
 ## NOTE
 
-This script expect input of two `sorted` text files.  If the file is not sorted, the unix `sort` command may be of help: https://en.wikipedia.org/wiki/Sort_(Unix)
+This script expect input of two `sorted` text files.  If the files are not sorted, the unix `sort` command may be of help: https://en.wikipedia.org/wiki/Sort_(Unix)
+
+> ForEach line in File1, compare to line in File2
+>   equal: incr both files to next line
+>   line1 > line2: new line detected, incr File2 to next line
+>   line1 < line2: deleted line, incr File1 to next line
+
+Since the list will be `sorted`, the performance of this script is expected to be approximately `O(|A| log |A| + |B| log |B|)`, where A is File1 and B is File2.
 
 ## Install
 
@@ -19,24 +26,28 @@ $ npm install text-file-diff
 
 ## Usage
 ```js
-  import TextFileDiff from 'text-file-diff';
-  const m = new TextFileDiff();
+import TextFileDiff from 'text-file-diff';
+const m = new TextFileDiff();
+m.on('compared', (line1, line2, compareResult, lineReader1, lineReader2) => {
+    // event triggered immediately after line comparison
+    // but before +- event
+  });
 
-  m.on('-', line => {
+m.on('-', line => {
     // when a line is in file1 but not in file2
   });
 
-  m.on('+', line => {
+m.on('+', line => {
     // when a line is in file2 but not in file1
   });
 
-  // run the diff
-  m.diff('tests/file1.txt', 'tests/file2.txt');
+// run the diff
+m.diff('tests/file1.txt', 'tests/file2.txt');
 ```
 
 ## Example
 ```bash
-$ ./bin/text-file-diff tests/file1.txt tests/file2.txt | sed 's/^\(.\{1\}\)/\1|/'
+$ ./bin/text-file-diff tests/file1.txt tests/file2.txt
 ```
 
 ## Point of Interest

test.js

@@ -1,7 +1,7 @@
 import test from 'ava';
 import TextFileDiff from '.';
 
-test('test with headers', t => {
+test('test with header', t => {
   const m = new TextFileDiff();
   const expected = '+Additional\n+Another\n+Lines\n-Some\n-Simple\n+With\n';