From 76dbfc419cfe3b8cf3536942672593c592fcda97 Mon Sep 17 00:00:00 2001
From: SheetJS <dev@sheetjs.com>
Date: Sat, 22 Apr 2023 19:25:24 -0400
Subject: [PATCH] mathematica

---
 .../03-demos/10-extensions/06-mathematica.md  | 114 ++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 docz/docs/03-demos/10-extensions/06-mathematica.md

diff --git a/docz/docs/03-demos/10-extensions/06-mathematica.md b/docz/docs/03-demos/10-extensions/06-mathematica.md
new file mode 100644
index 0000000..0e1729c
--- /dev/null
+++ b/docz/docs/03-demos/10-extensions/06-mathematica.md
@@ -0,0 +1,114 @@
+---
+title: Mathematica
+pagination_prev: demos/cloud/index
+pagination_next: demos/bigdata/index
+---
+
+:::note
+
+This demo was last tested in 2023 April 22 in Mathematica 13.2.1
+
+:::
+
+[The "NodeJS" instructions](/docs/getting-started/installation/frameworks)
+describe installation steps for NodeJS projects.  Mathematica has built-in
+features for external scripting with NodeJS. Helper functions can translate
+between CSV text and Mathematica datasets or arrays.
+
+Mathematica can also use [command-line tools](/docs/demos/desktop/cli)
+
+## Integration Details
+
+:::caution
+
+Mathematica includes `ExternalEvaluate` for running scripts in an external
+engine.  In local testing, there were incompatibilities with recent NodeJS
+versions.  This demo uses the shell integration to call a command-line tool.
+
+:::
+
+### Command-Line Tools
+
+`ExternalEvaluate` can run command-line tools and capture standard output:
+
+```mathematica
+cmd = "/usr/local/bin/xlsx-cli ~/Downloads/pres.numbers"
+csvdata = ExternalEvaluate["Shell" -> "StandardOutput", cmd];
+```
+
+Once evaluated, `ImportString` can interpret the data as a dataset.  Typically
+the first row of the CSV output is the header row.  The `HeaderLines` option
+controls how Mathematica parses the data:
+
+```mathematica
+data = ImportString[csvdata, "Dataset", "HeaderLines" -> 1]
+```
+
+## Complete Demo
+
+:::note
+
+This demo was tested in macOS.  The path names will differ in other platforms.
+
+:::
+
+1) Create the standalone `xlsx-cli` binary:
+
+```bash
+cd /tmp
+npm i --save https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz exit-on-epipe commander@2
+curl -LO https://docs.sheetjs.com/cli/xlsx-cli.js
+npx nexe -t 14.15.3 xlsx-cli.js
+```
+
+This is discussed in ["Command-line Tools"](/docs/demos/desktop/cli)
+
+2) Move the generated `xlsx-cli` to a fixed location in `/usr/local/bin`:
+
+```bash
+mkdir -p /usr/local/bin
+mv xlsx-cli /usr/local/bin/
+```
+
+### Reading a Local File
+
+3) In a new Mathematica notebook, run the following snippet:
+
+```mathematica
+SheetJSImportFile[x_] := ImportString[Block[{Print}, ExternalEvaluate[
+  "Shell" -> "StandardOutput",
+  "/usr/local/bin/xlsx-cli " <> x
+]], "Dataset", "HeaderLines" -> 1]
+```
+
+4) Download <https://sheetjs.com/pres.numbers> and save to Downloads folder.
+
+5) In the Mathematica notebook, run the new function. If the file was saved to
+the Downloads folder, the path will be `"~/Downloads/pres.numbers"` in macOS:
+
+```mathematica
+data = SheetJSImportFile["~/Downloads/pres.numbers"]
+```
+
+The result should be displayed in a concise table.
+
+### Reading from a URL
+
+`FetchURL` downloads a file from a specified URL. This function will be wrapped
+in a new function called `SheetJSImportURL`.
+
+6) In the same notebook, run the following:
+
+```mathematica
+Needs["Utilities`URLTools`"];
+SheetJSImportURL[x_] := Module[{path},(
+  path = FetchURL["https://sheetjs.com/pres.numbers"];
+  SheetJSImportFile[path]
+)];
+```
+
+7) Test by downloading the test file in the notebook:
+
+```mathematica
+data = SheetJSImportURL["https://sheetjs.com/pres.numbers"]
+```