README [ci skip]

This commit is contained in:
SheetJS 2017-03-10 12:33:08 -05:00
parent 4880e9219f
commit ba1d2ea2be
4 changed files with 109 additions and 35 deletions

@ -69,10 +69,15 @@ dist-deps: ## Copy dependencies for distribution
.PHONY: aux
aux: $(AUXTARGETS)
.PHONY: nexe
nexe: xlsx.exe
.PHONY: graph
graph: formats.png ## Rebuild format conversion graph
formats.png: formats.dot
circo -Tpng -o$@ $<
xlsx.exe: bin/xlsx.js xlsx.js
.PHONY: nexe
nexe: xlsx.exe ## Build nexe standalone executable
xlsx.exe: bin/xlsx.njs xlsx.js
nexe -i $< -o $@ --flags
## Testing

@ -27,6 +27,8 @@ File format support for known spreadsheet data formats:
| **Other Common Spreadsheet Output Formats** |:-----:|:-----:|
| HTML Tables | :o: | |
![circo graph of format support](formats.png)
Demo: <http://oss.sheetjs.com/js-xlsx>
Source: <http://git.io/xlsx>
@ -57,6 +59,14 @@ $ bower install js-xlsx
CDNjs automatically pulls the latest version and makes all versions available at
<http://cdnjs.com/libraries/xlsx>
### JS Ecosystem Demos
The `demos` directory includes sample projects for:
- [`browserify`](http://browserify.org/)
- [`requirejs`](http://requirejs.org/)
- [`webpack`](https://webpack.js.org/)
### Optional Modules
The node version automatically requires modules for additional features. Some
@ -73,14 +83,6 @@ An appropriate version for each dependency is included in the dist/ directory.
The complete single-file version is generated at `dist/xlsx.full.min.js`
### JS Ecosystem Demos
The `demos` directory includes sample projects for:
- [`browserify`](http://browserify.org/)
- [`requirejs`](http://requirejs.org/)
- [`webpack`](https://webpack.js.org/)
### ECMAScript 5 Compatibility
Since xlsx.js uses ES5 functions like `Array#forEach`, older browsers require
@ -411,20 +413,20 @@ array range. Other cells in the range will omit the `f` field.
The raw value is stored in the `v` field, interpreted based on the `t` field.
Type `b` is the Boolean type. `v` is interpreted according to JS truth tables
Type `b` is the Boolean type. `v` is interpreted according to JS truth tables.
Type `e` is the Error type. `v` holds the number and `w` holds the common name:
| Value | Error Meaning |
| ----: | :------------- |
| 0x00 | #NULL! |
| 0x07 | #DIV/0! |
| 0x0F | #VALUE! |
| 0x17 | #REF! |
| 0x1D | #NAME? |
| 0x24 | #NUM! |
| 0x2A | #N/A |
| 0x2B | #GETTING\_DATA |
| Value | Error Meaning |
| -----: | :-------------- |
| `0x00` | `#NULL!` |
| `0x07` | `#DIV/0!` |
| `0x0F` | `#VALUE!` |
| `0x17` | `#REF!` |
| `0x1D` | `#NAME?` |
| `0x24` | `#NUM!` |
| `0x2A` | `#N/A` |
| `0x2B` | `#GETTING_DATA` |
Type `n` is the Number type. This includes all forms of data that Excel stores
as numbers, such as dates/times and Boolean fields. Excel exclusively uses data
@ -707,8 +709,28 @@ Running `make init` will refresh the `test_files` submodule and get the files.
## Testing
`make test` will run the node-based tests. To run the in-browser tests, clone
[the oss.sheetjs.com repo](https://github.com/SheetJS/SheetJS.github.io) and
`make test` will run the node-based tests. By default it runs tests on files in
every supported format. To test a specific file type, set `FMTS` to the format
you want to test. Feature-specific tests are avaialble with `make test_misc`
```bash
$ make test # run full tests
$ make test_xls # only use the XLS test files
$ make test_xlsx # only use the XLSX test files
$ make test_xlsb # only use the XLSB test files
$ make test_xml # only use the XLSB test files
$ make test_ods # only use the XLSB test files
```
To enable all errors, set the environment variable `WTF=1`:
```bash
$ make test # run full tests
$ WTF=1 make test # enable all error messages
```
To run the in-browser tests, clone
[The oss.sheetjs.com repo](https://github.com/SheetJS/SheetJS.github.io) and
replace the xlsx.js file (then fire up the browser and go to `stress.html`):
```bash
@ -718,7 +740,6 @@ $ simplehttpserver # or "python -mSimpleHTTPServer" or "serve"
$ open -a Chromium.app http://localhost:8000/stress.html
```
For a much smaller test, run `make test_misc`.
## Contributing
@ -728,28 +749,24 @@ important to ensure code is cleanroom. Consult CONTRIBUTING.md
The xlsx.js file is constructed from the files in the `bits` subdirectory. The
build script (run `make`) will concatenate the individual bits to produce the
script. Before submitting a contribution, ensure that running make will produce
the xlsx.js file exactly. The simplest way to test is to move the script:
the xlsx.js file exactly. The simplest way to test is to add the script:
```bash
$ mv xlsx.js xlsx.new.js
$ git add xlsx.js
$ make clean
$ make
$ diff xlsx.js xlsx.new.js
$ git diff xlsx.js
```
To produce the dist files, run `make dist`. The dist files are updated in each
version release and should not be committed between versions.
version release and *should not be committed between versions*.
## License
Please consult the attached LICENSE file for details. All rights not explicitly
granted by the Apache 2.0 License are reserved by the Original Author.
It is the opinion of the Original Author that this code conforms to the terms of
the Microsoft Open Specifications Promise, falling under the same terms as
OpenOffice (which is governed by the Apache License v2). Given the vagaries of
the promise, the Original Author makes no legal claim that in fact end users are
protected from future actions. It is highly recommended that, for commercial
uses, you consult a lawyer before proceeding.
## References
@ -777,6 +794,8 @@ OSP-covered specifications:
Open Document Format for Office Applications Version 1.2 (29 September 2011)
Worksheet File Format (From Lotus) December 1984
## Badges

50
formats.dot Normal file

@ -0,0 +1,50 @@
digraph G {
graph [mindist=0.1];
csf [shape=doublecircle,label="Common\nSpreadsheet\nFormat\n(JS Object)"];
subgraph XL {
node [style=filled,color=green];
xlsx [label="XLSX\nXLSM"];
xlsb [label="XLSB\nBIFF12"];
xlml [label="SSML\n(2003/4)"];
xls2 [label="XLS\nBIFF2"];
xls3 [label="XLS\nBIFF3"];
xls4 [label="XLS\nBIFF4"];
xls5 [label="XLS\nBIFF5"];
xls8 [label="XLS\nBIFF8"];
}
subgraph OD {
node [style=filled,color=yellow];
ods [label="ODS"];
fods [label="Flat\nODS"];
uos [label="UOS\n标文通"];
}
subgraph OLD {
node [style=filled,color=cyan];
html [label="HTML\nTable"];
csv [label="CSV"];
}
subgraph JSXLSX {
edge [color=blue];
csf -> xlsx
xlsx -> csf
csf -> xlsb
xlsb -> csf
xlml -> csf
xls2 -> csf
csf -> xls2
xls3 -> csf
xls4 -> csf
xls5 -> csf
xls8 -> csf
csf -> csv
ods -> csf
csf -> ods
fods -> csf
csf -> fods
uos -> csf
html -> csf
}
}

BIN
formats.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 77 KiB