diff --git a/.gitignore b/.gitignore index 751553b..60d61c8 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ *.bak +package-lock.json +pnpm-lock.yaml diff --git a/Makefile b/Makefile index 65987f2..52cbdd1 100644 --- a/Makefile +++ b/Makefile @@ -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 diff --git a/docz/docs/06-solutions/05-output.md b/docz/docs/06-solutions/05-output.md index de35e6a..10cde1c 100644 --- a/docz/docs/06-solutions/05-output.md +++ b/docz/docs/06-solutions/05-output.md @@ -262,61 +262,6 @@ stream.pipe(conv); conv.pipe(process.stdout); -
- Exporting NUMBERS files (click to show) - -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 - - - - -``` - -_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}); -``` - -
- pipes write streams to nodejs response. ### Generating JSON and JS Data diff --git a/docz/docs/08-api/07-write-options.md b/docz/docs/08-api/07-write-options.md index 5103e65..9ff3570 100644 --- a/docz/docs/08-api/07-write-options.md +++ b/docz/docs/08-api/07-write-options.md @@ -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. + +
+ Exporting NUMBERS files (click to show) + +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`. + + + + +
https://cdn.sheetjs.com/xlsx-{current}/package/dist/xlsx.zahl.js is the URL for {current}
+ +
{`\
+\n\
+\n\
+\n\
+\n\
+\n\
+`}
+ + + + +After installing the package: + +
{`\
+$ npm install --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
+
+ +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}); +``` + + + + +
https://cdn.sheetjs.com/xlsx-{current}/package/dist/xlsx.zahl.mjs is the URL for {current}
+ +
{`\
+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\
+`}
+ + + + + +
## Supported Output Formats diff --git a/docz/docs/09-miscellany/07-contributing.md b/docz/docs/09-miscellany/07-contributing.md index 81105a2..d230e2a 100644 --- a/docz/docs/09-miscellany/07-contributing.md +++ b/docz/docs/09-miscellany/07-contributing.md @@ -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'; - + -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*. - - - - -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 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) + + + + +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 + +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 ``` -### 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