# MARPLE

MARPLE is an experimental APL interpreter that runs on Linux and the Pico 2 microcontroler.
It already has enough features to be usable, though may more are planned.

It was inspired by Rodrigo Girão Serrão's [RGSPL](https://github.com/rodrigogiraoserrao/RGSPL) and Iverson's [Dictionary of APL](https://www.jsoftware.com/papers/APLDictionary.htm). It has taken some additional features from Dyalog APL(TM).

Marple is written in Python! It has acceptable performance due to the use of numpy on Linux and ulab.numpy on the Pico 2.

I designed the interpreter and directed its development, but all the code, all the tests and almost all of the documentation have been generated by Claude code. So far the development has taken 8 days.

While MARPLE has extensive automated tests, it is not and will never be a commercial strength APL.
If that's what you want, get Dyalog APL. Dyalog APL is free for non-commercial work

See the full [feature list](FEATURES.md), [architecture](ARCHITECTURE.md), and [documentation](https://romilly.github.io/marple/).

## Platform support

MARPLE is developed and tested on **Linux** and the **Raspberry Pi Pico 2** (Pimoroni Presto). It does not currently run on Windows or Mac.

## Quick start

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it, then:

```bash
git clone https://github.com/romilly/marple.git
cd marple
uv venv
source venv/bin/activate
uv pip install -r requirements.txt
marple
```

```
MARPLE v0.5.26 - Mini APL in Python
CLEAR WS

      ⍳5
1 2 3 4 5
      +/⍳100
5050
      fact←{⍺←1 ⋄ ⍵=0:⍺ ⋄ (⍺×⍵)∇ ⍵-1}
      fact 20
2432902008176640000
```

### PRIDE Web IDE

From within the virtual environment:

```bash
python -m marple.web.server
```

Open `http://localhost:8888/` in your browser.

PRIDE features 

- a clickable language bar for APL glyph input
- workspace panel,
- session with system commands,
- session save/load, and
- interactive ⎕/⍞ input.

### Jupyter Notebook

```bash
uv pip install marple-lang[jupyter]
marple-jupyter-install
jupyter notebook
```

Select **MARPLE (APL)** as the kernel.

### Running scripts

```bash
marple examples/01_primitives.marple
```

### Pico deployment

MARPLE can be deployed to a **Pimoroni Presto** (Raspberry Pi Pico 2 with 480x480 touchscreen LCD). The REPL session mirrors to the LCD with a custom APL bitmap font. Other Pico boards are not currently supported.

```bash
./scripts/deploy.sh                                        # deploy to connected Presto
python scripts/pico_client.py                              # interactive REPL
python scripts/pico_client.py --script examples/12_life.marple  # run a script
```

To evaluate APL on a connected Presto from the PRIDE web IDE:

```bash
python -m marple.web.server --pico-port /dev/ttyACM0
```

See the [demo videos](https://romilly.github.io/marple/demos/), a demo of Bob Smith's partition functions, `)load part_fns`,  and [Conway's Game of Life example](docs/explanation/life.md).

## APL character input

### Dyalog keyboard layout (recommended)

On Linux with an extended keyboard (with a Windows/Super key), run:

```bash
./scripts/aplkeys.sh
```

This configures the Dyalog APL keyboard layout using `setxkbmap`. Hold the **Windows key** (Super) to type APL glyphs; hold **Shift+Windows** for the extended set. Each key has up to four meanings:

```
┌────────┐
│~ ⌺     │  top-left: Shifted        top-right: Shift+Win
│` ⋄     │  bottom-left: Unshifted   bottom-right: Win
└────────┘
```

Full US layout (see [Dyalog keyboard reference](https://dfns.dyalog.com/n_keyboards.htm) for other layouts):

```
┌────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬─────────┐
│~ ⌺ │! ⌶ │@ ⍫ │# ⍒ │$ ⍋ │% ⌽ │^ ⍉ │& ⊖ │* ⍟ │( ⍱ │) ⍲ │_ ! │+ ⌹ │Backspace│
│` ⋄ │1 ¨ │2 ¯ │3 < │4 ≤ │5 = │6 ≥ │7 > │8 ≠ │9 ∨ │0 ∧ │- × │= ÷ │         │
├────┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬──────┤
│Tab    │Q   │W   │E ⍷ │R   │T ⍨ │Y   │U   │I ⍸ │O ⍥ │P ⍣ │{ ⍞ │} ⍬ │| ⊣   │
│       │q ? │w ⍵ │e ∊ │r ⍴ │t ~ │y ↑ │u ↓ │i ⍳ │o ○ │p * │[ ← │] → │\ ⊢   │
├───────┴┬───┴┬───┴┬───┴┬───┴┬───┴┬───┴┬───┴┬───┴┬───┴┬───┴┬───┴┬───┴──────┤
│Caps    │A   │S   │D   │F ⍛ │G   │H   │J ⍤ │K ⌸ │L ⌷ │: ≡ │" ≢ │Enter     │
│Lock    │a ⍺ │s ⌈ │d ⌊ │f _ │g ∇ │h ∆ │j ∘ │k ' │l ⎕ │; ⍎ │' ⍕ │          │
├────────┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──┬─┴──────────┤
│Shift      │Z ⊆ │X   │C   │V   │B   │N   │M   │< ⍪ │> ⍙ │? ⍠ │Shift       │
│           │z ⊂ │x ⊃ │c ∩ │v ∪ │b ⊥ │n ⊤ │m | │, ⍝ │. ⍀ │/ ⌿ │            │
├───────┬─────┬──────┬──────────────────────────┬──────┬──────┬─────┬──────┤
│Ctrl   │Win  │Alt   │        Space bar         │Alt Gr│Win   │Menu │Ctrl  │
└───────┴─────┴──────┴──────────────────────────┴──────┴──────┴─────┴──────┘
```

### PRIDE language bar

In the PRIDE web IDE, you can click glyphs in the language bar at the top of the screen. No keyboard setup required.

### System commands

| Command | Action |
|---------|--------|
| `)off` | Exit |
| `)clear` | Clear workspace |
| `)wsid [name]` | Show or set workspace ID |
| `)save [name]` | Save workspace |
| `)load name` | Load workspace |
| `)lib` | List saved workspaces |
| `)fns [ns]` | List defined functions |
| `)ops [ns]` | List defined operators |
| `)vars` | List defined variables |

## Development

```bash
uv pip install -r requirements-test.txt
pytest                # fast tests (~1.2s)
pytest -m slow        # PRIDE, WebSocket, deep TCO, ⎕DL tests
pyright src/
```

## References

- [RGSPL](https://github.com/rodrigogiraoserrao/RGSPL) — Rodrigo Girão Serrão's Python APL interpreter (design reference)
- [RGSPL blog series](https://mathspp.com/blog/lsbasi-apl-part1) — step-by-step interpreter build
- [Iverson's Dictionary of APL](https://www.jsoftware.com/papers/APLDictionary.htm) — the rank operator and leading-axis theory
- [Language spec](docs/MARPLE_Language_Reference.md) — full APL reference and roadmap
