spectral-m2 1.2.0

A syntax-aware terminal shell for Macaulay2
spectral-m2-1.2.0 is not a library.

Spectral M2

crates.io license

Spectral M2 is a syntax-aware terminal shell for Macaulay2. It combines a real M2 session with local m2-syn parsing, structured output, multiline editing, selectable transcripts, preview modes, and two independent workspaces.

R = QQ[x, y]
I = ideal(x^2, x*y, y^2)
betti res I

Features

  • immediate syntax highlighting and local source-ranged diagnostics;
  • optional semantic colors from m2-ls across live input, session code, and previews;
  • immediate pending cells with spinner and queued states during evaluation;
  • structured values, types, printed text, warnings, and errors;
  • persistent multiline history and keyboard or mouse selection;
  • code, output, and syntax-tree previews with independent navigation;
  • views of the session opened beside it, including one-at-a-time narrow layouts;
  • command, settings, keymap, and highlight-debug pickers;
  • ordered native colorscheme variants with opaque or transparent canvas modes.

Requirements

  • Macaulay2 available as M2 on PATH;
  • a terminal with mouse events and OSC 52 clipboard support for the complete interface.

Optional semantic highlighting uses m2-ls 2.0 or later on PATH, installed with cargo install m2-ls. The shell also works without it.

Install

Install the released package through Cargo:

cargo install spectral-m2 --locked
sp2

The package is named spectral-m2; its executable is sp2. Give it a file to run as the session starts, or pick up where the last session ended:

sp2 ring.m2      # run ring.m2 cell by cell, then keep going
sp2 --resume     # run the previous session's code
sp2 --help

M2 startup options can be combined with a file or --resume, for example sp2 --no-debug --print-width 100 -e 'R = QQ[x]' ring.m2. Use -E for expressions before initialization and -e for expressions after it; both can be repeated. The same configuration is applied when the session restarts. sp2 --help lists all supported options.

Run the current checkout without installing it:

cargo run --release

Press Ctrl+C during a computation to cancel it and discard queued work while keeping the Macaulay2 session. When idle, Ctrl+C quits. The cancel execution binding can be changed in /keymaps; its hint appears in the status line after three seconds. Macaulay2 commands that exit the process also close the shell.

Type / for the filtered command picker, Ctrl+/ for all commands, or Ctrl+O for settings. Views open beside the session.

Configuration

Spectral preserves normal Macaulay2 initialization, including ~/.Macaulay2/init.m2 and packages installed in your home directory. It then reads its own init.m2 and materializes its generated backend.m2 in $XDG_CONFIG_HOME/spectral-m2, falling back to ~/.config/spectral-m2. The persistent backend source lets Macaulay2's code inspect Spectral's hooks; it is replaced whenever the backend embedded in the binary changes.

Documentation

The mdBook describes editing, commands, workspaces, previews, styles, and every default key. Its Macaulay2 examples are highlighted by mdbook-tsitter using a Cargo-built parser. From a source checkout:

cargo install mdbook --version 0.5.3 --locked
cargo install mdbook-tsitter
cargo build --release --locked \
    --manifest-path docs/parser/Cargo.toml \
    --target-dir target/docs-parser
mdbook serve docs --hostname 127.0.0.1 --port 3000

License

Spectral M2 is licensed under either of

at your option.