This commit is contained in:
SheetJS 2022-05-16 23:19:39 -04:00
parent 9865fa0037
commit 35a04a6dcf
5 changed files with 200 additions and 115 deletions

2
.gitignore vendored

@ -1 +1,3 @@
*.bak
package-lock.json
pnpm-lock.yaml

@ -1,6 +1,6 @@
.PHONY: build
build:
cd docz; pnpm build; cd ..
cd docz; npx -y pnpm build; cd ..
rm -rf docs
mv docz/build/ docs
cp CNAME docs

@ -262,61 +262,6 @@ stream.pipe(conv); conv.pipe(process.stdout);
</details>
<details>
<summary><b>Exporting NUMBERS files</b> (click to show)</summary>
The NUMBERS writer requires a fairly large base. The supplementary `xlsx.zahl`
scripts provide support. `xlsx.zahl.js` is designed for standalone and NodeJS
use, while `xlsx.zahl.mjs` is suitable for ESM.
_Browser_
```html
<meta charset="utf8">
<script src="xlsx.full.min.js"></script>
<script src="xlsx.zahl.js"></script>
<script>
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
["SheetJS", "<3","ிிள்"],
[72,,"Arbeitsblätter"],
[,62,"数据"],
[true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL, compression: true});
</script>
```
_Node_
```js
var XLSX = require("./xlsx.flow");
var XLSX_ZAHL = require("./dist/xlsx.zahl");
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
["SheetJS", "<3","ிிள்"],
[72,,"Arbeitsblätter"],
[,62,"数据"],
[true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL, compression: true});
```
_Deno_
```ts
import * as XLSX from './xlsx.mjs';
import XLSX_ZAHL from './dist/xlsx.zahl.mjs';
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
["SheetJS", "<3","ிிள்"],
[72,,"Arbeitsblätter"],
[,62,"数据"],
[true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textports.numbers", {numbers: XLSX_ZAHL, compression: true});
```
</details>
<https://github.com/sheetjs/sheetaki> pipes write streams to nodejs response.
### Generating JSON and JS Data

@ -4,8 +4,13 @@ hide_table_of_contents: true
title: Writing Files
---
import current from '/version.js';
# Writing Options
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
`XLSX.write(wb, write_opts)` attempts to write the workbook `wb`
`XLSX.writeFile(wb, filename, write_opts)` attempts to write `wb` to `filename`.
@ -43,8 +48,88 @@ The write functions accept an options argument:
- Due to a bug in the program, some features like "Text to Columns" will crash
Excel on worksheets where error conditions are ignored. The writer will mark
files to ignore the error by default. Set `ignoreEC` to `false` to suppress.
- Due to the size of the data, the NUMBERS data is not included by default. The
included `xlsx.zahl.js` and `xlsx.zahl.mjs` scripts include the data.
<details open>
<summary><b>Exporting NUMBERS files</b> (click to show)</summary>
The NUMBERS writer requires a fairly large base. The supplementary `xlsx.zahl`
scripts provide support. `xlsx.zahl.js` is designed for standalone and NodeJS
use, while `xlsx.zahl.mjs` is suitable for ESM.
Adding NUMBERS export support involves two steps:
1) Load the `xlsx.zahl` script
2) Pass the payload into the `numbers` option to `write` or `writeFile`.
<Tabs>
<TabItem value="browser" label="Browser">
<div><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.zahl.js`}>https://cdn.sheetjs.com/xlsx-{current}/package/dist/xlsx.zahl.js</a> is the URL for {current}</div>
<pre><code parentName="pre" {...{"className": "language-html"}}>{`\
<meta charset="utf8">\n\
<body>\n\
<script src="https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"></script>\n\
<script src="https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.zahl.js"></script>\n\
<script>\n\
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([\n\
["SheetJS", "<3","ிிள்"],\n\
[72,,"Arbeitsblätter"],\n\
[,62,"数据"],\n\
[true,false,],\n\
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");\n\
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL_PAYLOAD, compression: true});\n\
</script>\n\
</body>`}</code></pre>
</TabItem>
<TabItem value="nodejs" label="NodeJS">
After installing the package:
<pre><code parentName="pre" {...{"className": "language-bash"}}>{`\
$ npm install --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
</code></pre>
The scripts will be available at `xlsx/dist/xlsx.zahl` (CommonJS) and
`xlsx/dist/xlsx.zahl.mjs` (ESM).
```js
var XLSX = require("xlsx");
var XLSX_ZAHL_PAYLOAD = require("xlsx/dist/xlsx.zahl");
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([
["SheetJS", "<3","ிிள்"],
[72,,"Arbeitsblätter"],
[,62,"数据"],
[true,false,],
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL_PAYLOAD, compression: true});
```
</TabItem>
<TabItem value="deno" label="Deno">
<div><a href={`https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.zahl.mjs`}>https://cdn.sheetjs.com/xlsx-{current}/package/dist/xlsx.zahl.mjs</a> is the URL for {current}</div>
<pre><code parentName="pre" {...{"className": "language-ts"}}>{`\
import * as XLSX from 'https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs';\n\
import XLSX_ZAHL_PAYLOAD from 'https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.zahl.mjs';\n\
var wb = XLSX.utils.book_new(); var ws = XLSX.utils.aoa_to_sheet([\n\
["SheetJS", "<3","ிிள்"],\n\
[72,,"Arbeitsblätter"],\n\
[,62,"数据"],\n\
[true,false,],\n\
]); XLSX.utils.book_append_sheet(wb, ws, "Sheet1");\n\
XLSX.writeFile(wb, "textport.numbers", {numbers: XLSX_ZAHL_PAYLOAD, compression: true});\n\
`}</code></pre>
</TabItem>
</Tabs>
</details>
## Supported Output Formats

@ -1,6 +1,5 @@
---
sidebar_position: 7
hide_table_of_contents: true
---
# Contributing
@ -32,81 +31,135 @@ Folders:
After cloning the repo, running `make help` will display a list of commands.
## Platform-Specific Details
## Platform-Specific Setup
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="osx" label="OSX/Linux">
<TabItem value="wsl" label="Windows WSL">
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 add the script:
The OSX/Linux workflow works in WSL. Initial setup is involved:
```bash
$ git add xlsx.js
$ make clean
$ make
$ 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*.
</TabItem>
<TabItem value="win" label="Windows">
The included `make.cmd` script will build `xlsx.js` from the `bits` directory.
Building is as simple as:
```cmd
> make
```
To prepare development environment:
```cmd
> make init
```
The full list of commands available in Windows are displayed in `make help`:
```
make init -- install deps and global modules
make lint -- run eslint linter
make test -- run mocha test suite
make misc -- run smaller test suite
make book -- rebuild README and summary
make help -- display this message
```
As explained in [Test Files](./testing#test-files), on Windows the release ZIP file must
be downloaded and extracted. If Bash on Windows is available, it is possible
to run the OSX/Linux workflow. The following steps prepares the environment:
1) Install mercurial and subversion.
```bash
# Install support programs for the build and test commands
sudo apt-get install make git subversion mercurial
sudo add-apt-repository ppa:mercurial-ppa/releases
sudo apt-get update
sudo apt-get install mercurial subversion
sudo add-apt-repository --remove ppa:mercurial-ppa/releases
```
# Install nodejs and NPM within the WSL
wget -qO- https://deb.nodesource.com/setup_8.x | sudo bash
sudo apt-get install nodejs
2) Install NodeJS
```bash
# Install bootstrap NodeJS and NPM within the WSL
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs
# CLOSE AND REOPEN SHELL BEFORE CONTINUING
# Switch to `n`-managed NodeJS
sudo npm i -g n
sudo n 16
```
3) follow <https://github.com/paul-nelson-baker/git-openssl-shellscript> to
build and install a version of Git with OpenSSL:
```bash
# Git does not support OpenSSL out of the box, must do this
curl -LO https://github.com/paul-nelson-baker/git-openssl-shellscript/raw/main/compile-git-with-openssl.sh
chmod +x compile-git-with-openssl.sh
./compile-git-with-openssl.sh
```
4) (For deno testing) Install deno:
```bash
curl -fsSL https://deno.land/install.sh | sh
```
(instructions continued in the OSX/Linux part)
</TabItem>
<TabItem value="osx" label="OSX/Linux">
Initial setup:
0) Ensure mercurial, subversion, and NodeJS are installed. The WSL instructions
will have installed these dependencies, so WSL users can skip to step 1.
On Linux:
```bash
sudo apt-get install mercurial subversion
```
On MacOS, install using [Homebrew](https://brew.sh/):
```bash
brew install mercurial subversion
```
NodeJS installers can be found at <https://nodejs.org/en/download/>
1) Install NodeJS modules for building the scripts
```bash
# Install dev dependencies
sudo npm install -g mocha voc blanket xlsjs
npm install
# Install global dependencies
sudo npm install -g mocha@2.5.3 voc @sheetjs/uglify-js
```
2) Initialize the test files:
```bash
make init
```
This step may take a while as it will be downloading a number of test files.
3) Run a short test, then run a build
```bash
# Short test
make test_misc
# Full Build
cd modules; make; cd ..
make dist
```
</TabItem>
</Tabs>
### Tests
The `test_misc` target (`make test_misc` on Linux/OSX / `make misc` on Windows)
runs the targeted feature tests. It should take 5-10 seconds to perform feature
tests without testing against the entire test battery. New features should be
accompanied with tests for the relevant file formats and features.
## Development
The `xlsx.js` and `xlsx.mjs` files are constructed from the files in the `bits`
subdirectory. The build script (run `make`) will concatenate the individual
bits to produce the scripts.
To produce the dist files, run `make dist`. The dist files are updated in each
version release and *should not be committed between versions*.
**A note on Older Versions**
Some of the dependencies are wildly out of date. While SheetJS aims to run in
older versions of NodeJS and browsers, some libraries have chosen to break
backwards compatibility. The specific versions are used because they are known
to work and known to produce consistent results.
## Tests
The `test_misc` target runs the targeted feature tests. It should take 5-10
seconds to perform feature tests without testing against the full test battery.
New features should be accompanied with tests for the relevant file formats.
For tests involving the read side, an appropriate feature test would involve
reading an existing file and checking the resulting workbook object. If a