Metadata-Version: 2.4
Name: marple-lang
Version: 0.8.39
Summary: Mini APL in Python Language Experiment. Uses numpy arrays.
Author-email: Romilly Cocking <romilly.cocking@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/romilly/marple
Project-URL: Repository, https://github.com/romilly/marple.git
Project-URL: Issues, https://github.com/romilly/marple/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp==3.13.3
Requires-Dist: numpy==2.4.3
Provides-Extra: jupyter
Requires-Dist: ipykernel==7.2.0; extra == "jupyter"
Requires-Dist: jupyter_client==8.8.0; extra == "jupyter"
Provides-Extra: test
Requires-Dist: pytest==9.0.2; extra == "test"
Requires-Dist: pytest-cov==7.0.0; extra == "test"
Requires-Dist: pyright==1.1.408; extra == "test"
Requires-Dist: PyHamcrest==2.1.0; extra == "test"
Requires-Dist: pytest-asyncio==1.3.0; extra == "test"
Dynamic: license-file

# MARPLE

MARPLE is an experimental APL interpreter that runs on Linux.
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 and uses numpy for array operations.

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.

> **Project status (April 2026):** MARPLE is in the middle of a
> substantial internal cleanup. The scalar storage convention was
> migrated to align numpy data shape with APL shape, and the
> post-char-migration primitive sweep — decode (`⊥`), encode (`⊤`),
> monadic and dyadic transpose (`⍉`) — has just been completed,
> along with several missing pieces (zilde `⍬`, commute `⍨`).
> Ongoing work includes other missing operators (`⍥`, `@`, `⌸`,
> `⌺`) and test file reorganisation. See
> [`plan/post-scalar-cleanup.md`](plan/post-scalar-cleanup.md) for
> the open TODO list and the latest `plan/progress-*.md` file for
> recent activity. Expect the API surface to be stable but the
> internals to keep moving for a while yet.

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**. 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.6.17 - 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
marple-server                     # default: http://0.0.0.0:8888/ (LAN-accessible)
marple-server --port 9000
marple-server --host 127.0.0.1    # localhost only
```

The startup banner prints both a `localhost:` URL and a LAN URL using
the machine's hostname. Open either in a browser.

PRIDE features

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

#### Running PRIDE on one machine, browsing from another

MARPLE's web server binds to all network interfaces by default, so you
can run the interpreter on a Raspberry Pi (or any other machine on
your home network) and connect from your desktop browser:

```bash
# On the Pi:
marple-server

# On your workstation, in a browser:
http://pi.local:8888/
# …or whatever the Pi's hostname or IP is
```

This is the simplest way to develop MARPLE on a Pi from a workstation,
and it lets you use MARPLE from Windows or Mac machines that don't
have the Python environment installed locally.

**Security note:** the server has no authentication. Only run it on
networks where you trust every device — a home LAN is fine, a
coffee-shop WiFi is not. For anything beyond a trusted LAN, put PRIDE
behind an authenticating reverse proxy (Caddy, nginx + basic auth,
Tailscale, etc.).

### 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
```

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 |
| `)drop name` | Delete a saved workspace |
| `)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
