Using bAsedPL notebooks

APL cells, Python magics, glyph entry and help.

bAsedPL kernel

Install with pip install basedpl, then select bAsedPL in Jupyter’s kernel menu. Write APL directly in each code cell. Names persist between cells.

v←⍳5
+/v

Shift-Tab inspects names and glyphs. ]help name shows help; ]help name -source shows source. See Getting started for an executable APL tutorial.

Python magics

Run %load_ext basedpl.notebooks in a Python notebook to register %apl and %%apl. Both share a persistent APL workspace. To load the extension automatically in IPython and Jupyter, run bapl-install-magic once.

The magics evaluate in basedpl.apl, so Python code that imports apl shares their workspace. %apl ]clear removes every name.

from basedpl.notebooks import create_magic

Hold left Alt/Option for bAsedPL’s glyph keyboard: Alt-h ←, Alt-minus ×, Alt-equals ÷, Alt-Shift-a ⍶. Right Option keeps its native behavior. Chords work in APL input, including strings and comments.

Type a backtick followed by a bAsedPL symbol name: `io then Tab inserts ⍳, and 2`times3 becomes 2×3. Suggestions appear beside the cursor as you type, including the REPL’s shortcut notation: h means Alt-h, Sa means Alt-Shift-a. Click a suggestion or keep typing to resolve an ambiguous name. Names and aliases come from bAsedPL’s REPL catalogue.

Completion is active in %%apl cells and on %apl lines, including x = %apl .... Ordinary Python and Markdown input is unchanged. Strings, comments and pasted text are not expanded. Tab explicitly completes an existing name. Enter accepts a unique match before the notebook’s normal newline or execution action. Escape or cursor movement cancels automatic expansion.

The first apl magic also adds a clickable symbol bar, based on Adám Brudzewsky’s APL language bar. Hover over a glyph to see its names and shortcut. The ▲/▼ button switches between pushing the page down and overlaying it. This choice is remembered per site.

The cell magic (%%apl) displays bAsedPL output in Adám’s SAX2 APL font:

%%apl
m←3 3⍴⍳9
m×10
10 20 30
40 50 60
70 80 90

Assignments are shy: the m← line printed nothing. The line magic returns a native array. Use .np to copy its values to NumPy:

v = %apl 3×⍳4
v.np
array([ 3.,  6.,  9., 12.])
text = %apl 'APL in Python'
text.py
'APL in Python'

.py converts numeric atoms to Python numbers and character vectors to strings. Unkeyed numeric arrays become NumPy arrays, keyed vectors become dictionaries, and higher-rank keyed arrays become pandas DataFrames. Numeric scalars (rank-0 arrays) become zero-dimensional NumPy arrays. .np copies values to NumPy without labels:

z = %apl m
z.np
array([[1., 2., 3.],
       [4., 5., 6.],
       [7., 8., 9.]])

To suppress a cell’s output, end the last line with a ;:

%%apl
m×10;

⎕← displays a value explicitly, which is how you show something that would otherwise be shy:

%%apl
v←2×⍳5
⎕←v
2 4 6 8 10

Convert to NumPy to use its methods:

a = %apl m
a.np.sum(axis=0)
array([12., 15., 18.])

Names and help

Tab completes user and system names in APL input. Use ]help name for comment help and ]help name -source for APL source:

%%apl
double←{⍝ Double the argument
2×⍵}
%apl ]help double

Double the argument

%apl ]help double -source
{⍝ Double the argument
2×⍵}

Python function objects support f? and f??. See Python and Help and introspection.

Errors and interruption

APL errors raise basedpl.AplError. The magics display output produced before the error. Incomplete input raises a syntax error without resetting the workspace.

Interrupt a calculation with the notebook’s stop button. Set a per-evaluation deadline with apl.timeout = seconds. Cancellation preserves the workspace and completed assignments. Native-library calls and individual BigInt operations can delay cancellation.

bAsedPL is an APL-derived array language, borrowing from J and BQN. See its language guide for glyphs, array rules and system functions.

Other interpreters

Dyalog sessions run an independent reference interpreter. J runs the J language, with a session class, %%j magics and a Jupyter kernel.

The magics implementation documents display, completion and workspace handling.