version bump 0.9.1: cpexcel update

- codepage upgraded to 1.7.0
- remove require dark pattern (closes #554 h/t @keyiis)
- test for JSON header disambiguation
- utility functions documentation (fixes #424 h/t @dskrvk)

README.md

@@ -336,12 +336,16 @@ Complete examples:
 
 `XLSX.readFile(filename, read_opts)` attempts to read `filename` and parse.
 
+Parse options are described in the [Parsing Options](#parsing-options) section.
+
 ### Writing functions
 
 `XLSX.write(wb, write_opts)` attempts to write the workbook `wb`
 
 `XLSX.writeFile(wb, filename, write_opts)` attempts to write `wb` to `filename`
 
+Write options are described in the [Writing Options](#writing-options) section.
+
 ### Utilities
 
 Utilities are available in the `XLSX.utils` object:
@@ -353,7 +357,8 @@ Exporting:
 - `sheet_to_csv` generates delimiter-separated-values output.
 - `sheet_to_formulae` generates a list of the formulae (with value fallbacks).
 
-The `sheet_to_*` functions accept a worksheet and an optional options object.
+Exporters are described in the [Utility Functions](#utility-functions) section.
+
 
 Cell and cell address manipulation:
 
@@ -623,6 +628,130 @@ The `type` argument for `write` mirrors the `type` argument for `read`:
 | `"file"`   | string: name of file to be written (nodejs only)                |
 
 
+## Utility Functions
+
+The `sheet_to_*` functions accept a worksheet and an optional options object.
+
+The examples are based on the following worksheet:
+
+```
+XXX| A | B | C | D | E | F | G |
+---+---+---+---+---+---+---+---+
+ 1 | S | h | e | e | t | J | S |
+ 2 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+ 3 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
+```
+
+### Formulae Output
+
+`XLSX.utils.sheet_to_formulae` generates an array of commands that represent
+how a person would enter data into an application.  Each entry is of the form
+`A1-cell-address=formula-or-value`.  String literals are prefixed with a `'` in
+accordance with Excel.  For the example sheet:
+
+```js
+> var o = XLSX.utils.sheet_to_formulae(ws);
+> o.filter(function(v, i) { return i % 5 === 0; });
+[ 'A1=\'S', 'F1=\'J', 'D2=4', 'B3=3', 'G3=8' ]
+```
+
+### CSV and general DSV Output
+
+As an alternative to the `writeFile` CSV type, `XLSX.utils.sheet_to_csv` also
+produces CSV output.  The function takes an options argument:
+
+| Option Name |  Default | Description                                         |
+| :---------- | :------: | :-------------------------------------------------- |
+| FS          |  `","`   | "Field Separator"  delimiter between fields         |
+| RS          |  `"\n"`  | "Record Separator" delimiter between rows           |
+
+For the example sheet:
+
+```js
+> console.log(XLSX.utils.sheet_to_csv(ws));
+S,h,e,e,t,J,S
+1,2,3,4,5,6,7
+2,3,4,5,6,7,8
+> console.log(XLSX.utils.sheet_to_csv(ws, {FS:"\t"}));
+S	h	e	e	t	J	S
+1	2	3	4	5	6	7
+2	3	4	5	6	7	8
+> console.log(X.utils.sheet_to_csv(_ws,{FS:":",RS:"|"}));
+S:h:e:e:t:J:S|1:2:3:4:5:6:7|2:3:4:5:6:7:8|
+```
+
+### JSON
+
+`XLSX.utils.sheet_to_json` and the alias `XLSX.utils.sheet_to_row_object_array`
+generate different types of JS objects.  The function takes an options argument:
+
+| Option Name |  Default | Description                                         |
+| :---------- | :------: | :-------------------------------------------------- |
+| raw         | `false`  | Use raw values (true) or formatted strings (false)  |
+| range       | from WS  | Override Range (see table below)                    |
+| header      |          | Control output format (see table below)             |
+
+- `raw` only affects cells which have a format code (`.z`) field or a formatted
+  text (`.w`) field.
+- If `header` is specified, the first row is considered a data row; if `header`
+  is not specified, the first row is the header row and not considered data.
+- When `header` is not specified, the conversion will automatically disambiguate
+  header entries by affixing `_` and a count starting at `1`.  For example, if
+  three columns have header `foo` the output fields are `foo`, `foo_1`, `foo_2`
+
+`range` is expected to be one of:
+
+| `range`          | Description                                               |
+| :--------------- | :-------------------------------------------------------- |
+| (number)         | Use worksheet range but set starting row to the value     |
+| (string)         | Use specified range (A1-style bounded range string)       |
+| (default)        | Use worksheet range (`ws['!ref']`)                        |
+
+`header` is expected to be one of:
+
+| `header`         | Description                                               |
+| :--------------- | :-------------------------------------------------------- |
+| `1`              | Generate an array of arrays                               |
+| `"A"`            | Row object keys are literal column labels                 |
+| array of strings | Use specified strings as keys in row objects              |
+| (default)        | Read and disambiguate first row as keys                   |
+
+For the example sheet:
+
+```js
+> console.log(X.utils.sheet_to_json(_ws));
+[ { S: 1, h: 2, e: 3, e_1: 4, t: 5, J: 6, S_1: 7 },
+  { S: 2, h: 3, e: 4, e_1: 5, t: 6, J: 7, S_1: 8 } ]
+
+> console.log(X.utils.sheet_to_json(_ws, {header:1}));
+[ [ 'S', 'h', 'e', 'e', 't', 'J', 'S' ],
+  [ 1, 2, 3, 4, 5, 6, 7 ],
+  [ 2, 3, 4, 5, 6, 7, 8 ] ]
+
+> console.log(X.utils.sheet_to_json(_ws, {header:"A"}));
+[ { A: 'S', B: 'h', C: 'e', D: 'e', E: 't', F: 'J', G: 'S' },
+  { A: 1, B: 2, C: 3, D: 4, E: 5, F: 6, G: 7 },
+  { A: 2, B: 3, C: 4, D: 5, E: 6, F: 7, G: 8 } ]
+> console.log(X.utils.sheet_to_json(_ws, {header:["A","E","I","O","U","6","9"]}));
+[ { '6': 'J', '9': 'S', A: 'S', E: 'h', I: 'e', O: 'e', U: 't' },
+  { '6': 6, '9': 7, A: 1, E: 2, I: 3, O: 4, U: 5 },
+  { '6': 7, '9': 8, A: 2, E: 3, I: 4, O: 5, U: 6 } ]
+```
+
+Example showing the effect of `raw`:
+
+```js
+> _ws['A2'].w = "1";                         // set A2 formatted string value
+> console.log(X.utils.sheet_to_json(_ws, {header:1}));
+[ [ 'S', 'h', 'e', 'e', 't', 'J', 'S' ],
+  [ '1', 2, 3, 4, 5, 6, 7 ],                 // <-- A2 uses the formatted string
+  [ 2, 3, 4, 5, 6, 7, 8 ] ]
+> console.log(X.utils.sheet_to_json(_ws, {header:1, raw:true}));
+[ [ 'S', 'h', 'e', 'e', 't', 'J', 'S' ],
+  [ 1, 2, 3, 4, 5, 6, 7 ],                   // <-- A2 uses the raw value
+  [ 2, 3, 4, 5, 6, 7, 8 ] ]
+```
+
 ## File Formats
 
 Despite the fact that the name of the library is `xlsx`, it supports numerous

bits/01_version.js

-XLSX.version = '0.9.0';
+XLSX.version = '0.9.1';

bits/75_xlml.js

@@ -162,6 +162,7 @@ var xlmlregex = /<(\/?)([^\s?>!\/:]*:|)([^\s?>]*[^\s?>\/])[^>]*>/mg;
 //var xlmlregex = /<(\/?)([a-z0-9]*:|)(\w+)[^>]*>/mg;
 function parse_xlml_xml(d, opts)/*:Workbook*/ {
 	var str = debom(xlml_normalize(d));
+	if(opts && opts.type == 'binary' && typeof cptable !== 'undefined') str = cptable.utils.decode(65001, char_codes(str));
 	if(str.substr(0,1000).indexOf("<html") >= 0) return parse_html(str, opts);
 	var Rn;
 	var state = [], tmp;

demos/webpack/webpack.config.js

@@ -9,10 +9,5 @@ module.exports = {
 	node: {
 		fs: false,
 		Buffer: false
-	},
-	externals: [
-		{
-			'./cptable': 'var cptable'
-		}
-	]
+	}
 }

package.json

 {
 	"name": "xlsx",
-	"version": "0.9.0",
+	"version": "0.9.1",
 	"author": "sheetjs",
 	"description": "Excel (XLSB/XLSX/XLSM/XLS/XML) and ODS (ODS/FODS/UOS) spreadsheet parser and writer",
 	"keywords": [ "excel", "xls", "xlsx", "xlsb", "xlsm", "ods", "office", "spreadsheet" ],
@@ -16,7 +16,7 @@
 	"dependencies": {
 		"exit-on-epipe":"",
 		"ssf":"~0.8.1",
-		"codepage":"",
+		"codepage":"~1.7.0",
 		"cfb":"~0.11.0",
 		"crc-32":"",
 		"adler-32":"",

test.js

@@ -1064,6 +1064,20 @@ describe('json output', function() {
 			assert.throws(function() { seeker(json, [0,1,2], "baz"); });
 		});
 	});
+	it('should disambiguate headers', function() {
+		var _data = [["S","h","e","e","t","J","S"],[1,2,3,4,5,6,7],[2,3,4,5,6,7,8]];
+		var _ws = sheet_from_array_of_arrays(_data);
+		var json = X.utils.sheet_to_json(_ws);
+		for(var i = 0; i < json.length; ++i) {
+			assert.equal(json[i].S,   1 + i);
+			assert.equal(json[i].h,   2 + i);
+			assert.equal(json[i].e,   3 + i);
+			assert.equal(json[i].e_1, 4 + i);
+			assert.equal(json[i].t,   5 + i);
+			assert.equal(json[i].J,   6 + i);
+			assert.equal(json[i].S_1, 7 + i);
+		}
+	});
 });
 
 describe('js -> file -> js', function() {

xlsx.flow.js

@@ -5,7 +5,7 @@
 /*exported XLSX */
 var XLSX = {};
 (function make_xlsx(XLSX){
-XLSX.version = '0.9.0';
+XLSX.version = '0.9.1';
 var current_codepage = 1200, current_cptable;
 if(typeof module !== "undefined" && typeof require !== 'undefined') {
 	if(typeof cptable === 'undefined') cptable = require('./dist/cpexcel.js');
@@ -9724,6 +9724,7 @@ var xlmlregex = /<(\/?)([^\s?>!\/:]*:|)([^\s?>]*[^\s?>\/])[^>]*>/mg;
 //var xlmlregex = /<(\/?)([a-z0-9]*:|)(\w+)[^>]*>/mg;
 function parse_xlml_xml(d, opts)/*:Workbook*/ {
 	var str = debom(xlml_normalize(d));
+	if(opts && opts.type == 'binary' && typeof cptable !== 'undefined') str = cptable.utils.decode(65001, char_codes(str));
 	if(str.substr(0,1000).indexOf("<html") >= 0) return parse_html(str, opts);
 	var Rn;
 	var state = [], tmp;