Woxi
An interpreter for the Wolfram Language powered by Rust.
You can find the official documentation at
woxi.ad-si.com/docs.
Features
The initial focus is to implement a subset of the Wolfram Language
so that it can be used for CLI scripting and notebooks.
For example:
#!/usr/bin/env woxi
(* Print the square of 5 random integers between 1 and 9 *)
RandomInteger[{1, 9}, 5] // Map[#^2&] // Map[Print]
It has full support for Jupyter Notebooks including graphical output:
[!TIP]
Try it out yourself in our
JupyterLite instance!
Check out the CLI tests directory
to see all currently supported commands and their expected output.
All tests must pass with Woxi and WolframScript.
Also check out the functions.csv file
for a list of all Wolfram Language functions and their implementation status.
Woxi runs faster than WolframScript as there is no overhead of starting a kernel
and verifying its license.
Installation
You can easily install it with Rust’s cargo:
cargo install woxi
Prebuilt Binaries
Every GitHub release ships archives
of the woxi CLI and the Woxi Studio notebook editor for
Linux, macOS, and Windows (x86-64 and arm64),
alongside a SHA256SUMS.txt to verify them against.
The macOS build of Woxi Studio comes as a Woxi Studio.app bundle.
It is not notarized, so macOS quarantines it after the download —
remove the flag once after unzipping:
xattr -dr com.apple.quarantine "Woxi Studio.app"
JavaScript / Node.js
Woxi is also available on npm as woxi-wasm
as a WebAssembly build with JavaScript bindings (see npm/):
npm install woxi-wasm
import { evaluate } from "woxi-wasm"
evaluate("Plus[1, 2]")
Python
Woxi is also available on PyPI
as a Python package with pre-built wheels:
pip install woxi
import woxi
woxi.interpret("Plus[1, 2]") # => '3'
See woxi-py/readme.md for the full Python API.
From Source
If you want to build Woxi from source, you need to have Rust installed.
You can get it from rust-lang.org.
Clone the repository, build the project, and install it:
git clone https://github.com/ad-si/Woxi
cd Woxi
make install
On macOS, make install additionally builds the Woxi Studio notebook editor
and installs it as a .app bundle at /Applications/Woxi Studio.app,
registered with Launch Services so that .nb, .wl, and .wls files appear
under Finder’s “Open With…” menu.
On Linux, make install-linux-desktop installs Woxi Studio together with
a desktop entry and icon under ~/.local/share.
Its windows use woxi-studio as X11 WM_CLASS and Wayland app id,
so docks and launchers can associate them with the desktop entry.
Usage
You can use the interpreter directly from the command line:
woxi eval "1 + 2"
# 3
woxi eval 'StringJoin["Hello", " ", "World!"]'
# Hello World!
Or you can run a script:
woxi run tests/scripts/hello_world.wls
Or start an interactive REPL, where definitions and % / Out[] history
persist across inputs:
woxi repl
# In[1]:= x = 5
# Out[1]= 5
# In[2]:= x^2
# Out[2]= 25
Jupyter Notebook
You can also use Woxi in Jupyter notebooks.
Install the kernel with:
woxi install-kernel
The kernelspec is embedded in the woxi binary,
so this works from any directory and with any installation method.
It is registered with jupyter kernelspec install when the jupyter command
is available, and written to Jupyter’s kernels directory directly otherwise.
Use --system to install it for all users instead of only the current one.
Then start the Jupyter server:
cd examples && jupyter lab
Or simply use our
JupyterLite instance.
It runs fully self-contained in your browser and no data is send to the cloud.
Presentations
Woxi Studio presents notebooks as slideshows, like the FrontEnd’s
SlideShow environment.
Insert a “Slide Break” cell (SlideShowNavigationBar style) where each slide
starts and press the presentation button in the toolbar (or F5).
The arrow keys, Page Up/Page Down, and Space
turn the slides, and Esc ends the slideshow.
Notebooks saved with ScreenStyleEnvironment -> "SlideShow" open as
slideshows, and the Markdown, LaTeX, Typst, and Jupyter exports keep the slide
breaks.
Inside a notebook, SlideView[{slide1, slide2, …}] is an interactive slide
viewer.
Editor Integration
Woxi ships a Language Server Protocol server for the Wolfram Language:
woxi lsp
It speaks LSP over stdin/stdout, which is how editors start it, and
provides
- Diagnostics — syntax errors, plus warnings on the symbols this
interpreter does not implement, so you see what a script will not do
before running it
- Hover documentation and completion for every built-in symbol,
from the same registry the interpreter uses, and for the symbols the
edited file defines itself
- Go to definition, find references, occurrence highlighting and
the document outline, computed from the file’s assignments
Configure your editor to run woxi lsp for .wl, .wls, .m and .nb
files. For Neovim’s built-in client that is:
vim.lsp.config.woxi = {
cmd = { "woxi", "lsp" },
filetypes = { "wolfram" },
root_markers = { ".git" },
}
vim.lsp.enable("woxi")
| Woxi |
WolframScript |
woxi eval "1 + 2" |
wolframscript -code "1 + 2" |
woxi run script.wls |
wolframscript script.wls |
woxi run notebook.nb |
not supported (can’t run .nb files directly) |
woxi repl |
wolframscript (no arguments) |
woxi lsp |
not supported (no language server) |
Contributing
Contributions are very welcome!
Please feel free to submit a Pull Request.
Testing
To run the test suite:
make test
评论