# Using bAsedPL notebooks


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

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

``` apl
v←⍳5
+/v
```

Shift-Tab inspects names and glyphs. `]help name` shows help;
`]help name -source` shows source. See [Getting
started](getting-started.ipynb) 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.

``` python
from basedpl.notebooks import create_magic
```

Hold **left Alt/Option** for [bAsedPL’s glyph keyboard](keyboard.qmd):
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](https://abrudz.github.io/lb/apl). 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](https://github.com/abrudz/SAX2) APL font:

``` python
%%apl
m←3 3⍴⍳9
m×10
```

<pre class="aplnb_out sax2">10 20 30
40 50 60
70 80 90</pre>

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

``` python
v = %apl 3×⍳4
v.np
```

    array([ 3.,  6.,  9., 12.])

``` python
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:

``` python
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 `;`:

``` python
%%apl
m×10;
```

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

``` python
%%apl
v←2×⍳5
⎕←v
```

<pre class="aplnb_out sax2">2 4 6 8 10</pre>

Convert to NumPy to use its methods:

``` python
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:

``` python
%%apl
double←{⍝ Double the argument
2×⍵}
```

``` python
%apl ]help double
```

Double the argument

``` python
%apl ]help double -source
```

``` apl
{⍝ Double the argument
2×⍵}
```

Python function objects support `f?` and `f??`. See
[Python](python.ipynb#names-and-help) and [Help and
introspection](introspection.ipynb).

## 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](dyalog.ipynb) run an independent reference
interpreter. [J](j.ipynb) runs the J language, with a session class,
`%%j` magics and a Jupyter kernel.

The [magics implementation](magics.ipynb) documents display, completion
and workspace handling.