Using BPL notebooks

BPL cells, Python magics, glyph entry and help.

BPL kernel

Install with pip install basedpl, then select BasedPL in Jupyter’s kernel menu. Write BPL 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 the source. See Getting started for an executable BPL tutorial.

Python magics

Run %load_ext basedpl.notebooks in a Python notebook to register %bpl and %%bpl. To load the extension automatically in IPython and Jupyter, run bpl-install-magic once.

The magics and Python code that imports bpl share one persistent workspace, basedpl.bpl. %bpl ]clear removes every name.

from basedpl.notebooks import create_magic

Hold the left Alt or Option key and press a key from the glyph reference: Alt-h ←, Alt-m × and Alt-u ÷. Some glyphs take a second key. For example, Alt-Minus then a types ⍶, and Alt-6 then a digit types a superscript. Hold Alt or Option and tap the same dead key twice to type its character: Option-o twice gives ○, and Option-backslash twice gives ⍭. The sequence ends after the second tap. On a UK Mac keyboard, Option-Shift-3 types # through the shared Alt-£ alias. Plain Shift-3 still types £. Right Option keeps its native behavior. Alt keys work in BPL input, including strings and comments. The glyph map is the same as the BPL REPL’s.

The browser Alt handler uses US physical key positions. The native macOS layouts support US, UK, German QWERTZ, French AZERTY and Spanish ISO keyboards. They preserve local typing and move conflicting BPL shortcuts to Option-Shift, then Control-Option or Control-Option-Shift.

Type a backtick followed by a BPL symbol name. For example, `io then Tab inserts ⍳, and 2`times3 becomes 2×3. As you type, suggestions appear beside the cursor, with each glyph’s key shortcut in the REPL’s notation. In that notation, h means Alt-h, and o c means Alt-o then c. Matching prefers exact names, then prefixes, then abbreviations. Click a suggestion or keep typing to resolve an ambiguous name. Names and aliases come from BPL’s REPL catalogue.

Completion is active in %%bpl and %%apl cells, on %bpl lines such as x = %bpl ..., and in Monaco editors configured for BPL. 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 bpl 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 (%%bpl) displays BPL output in Adám’s SAX2 APL font:

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

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

v = %bpl 3×⍳4
v.np
array([0., 3., 6., 9.])
text = %bpl "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 = %bpl m
z.np
array([[0., 1., 2.],
       [3., 4., 5.],
       [6., 7., 8.]])

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

%%bpl
m×10;

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

%%bpl
v←2×⍳5
⎕←v
0 2 4 6 8

Convert to NumPy to use its methods:

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

Names and help

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

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

Calls: f Y or X f Y

Double the argument

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

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

Errors and interruption

BPL errors raise basedpl.BplError. 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 bpl.timeout = seconds. Cancellation preserves the workspace and completed assignments. Native-library calls and individual BigInt operations can delay cancellation.

BPL is an APL-derived array language, borrowing from J and BQN. See the glyph reference for glyphs, System functions for system functions, and Evaluation for how functions apply to arrays.

Other interpreters

Dyalog sessions run an independent reference interpreter.

The magics implementation documents display, completion and workspace handling.