Metadata-Version: 2.4
Name: basedpl
Version: 0.1.28
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: fastcore
Requires-Dist: fastship>=0.0.11 ; extra == 'dev'
Requires-Dist: fastws-cli>=0.0.22 ; extra == 'dev'
Requires-Dist: maturin>=1.9.4,<2.0 ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: numpy ; extra == 'dev'
Requires-Dist: pandas ; extra == 'dev'
Requires-Dist: ipython>=9.17.1 ; extra == 'dev'
Requires-Dist: nbdev>=3.3.24 ; extra == 'dev'
Requires-Dist: conkernelclient>=0.0.23 ; extra == 'dev'
Requires-Dist: pillow ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: BasedPL, the Based-array Programming Language, is an APL-derived array language, borrowing ideas from J and BQN, with an emphasis on simple, consistent notation.
Author-email: Jeremy Howard <github@jhoward.fastmail.fm>
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://answerdotai.github.io/basedpl
Project-URL: Homepage, https://github.com/AnswerDotAI/basedpl
Project-URL: Issues, https://github.com/AnswerDotAI/basedpl/issues
Project-URL: Repository, https://github.com/AnswerDotAI/basedpl

# BasedPL


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

BasedPL, the Based-array Programming Language, is an array language derived from APL, with ideas from J and BQN. Its notation aims to be simple and consistent. Most of this documentation calls it BPL. BPL is written in Rust and comes as a native executable, a Jupyter kernel and a Python API.

LLMs: read [llms.txt](https://answerdotai.github.io/basedpl/llms.txt) first. It is the primary reference index and concise overview.

## Install and try it

``` sh
pip install basedpl
bpl
```

Each release also has a standalone `bpl` that needs no Python, for macOS on Apple silicon and for Linux on x86-64 and arm64. On a Mac:

``` sh
curl -Lo bpl https://github.com/AnswerDotAI/basedpl/releases/latest/download/bpl-macos-arm64
chmod +x bpl
```

On Linux, download `bpl-linux-x86_64` or `bpl-linux-arm64` instead.

At the prompt, define a mean and apply it:

``` bpl
avg←+/÷≢
avg 2 4 9
```

    5

Use `bpl -e 'avg←+/÷≢ ⋄ avg 2 4 9'` for a shell command. The [command-line guide](https://answerdotai.github.io/basedpl/cli.html) covers source files and pipes.

## Interactive use

In the REPL, type a backtick followed by a glyph name. For example, `` `iota `` becomes `⍳` when you press Tab or type a non-letter. Abbreviations and Alt-key shortcuts are available. `]help +` shows help for `+`. [`•prefs`](https://answerdotai.github.io/basedpl/system-functions.html#prefs) changes display settings, such as boxes and how much of a large array shows. See [REPL](https://answerdotai.github.io/basedpl/repl.html) and the [glyph reference](https://answerdotai.github.io/basedpl/glyphs.html), which lists each glyph’s key.

In Jupyter, select the installed **BasedPL** kernel. Cells share definitions and support completion, Shift-Tab help and interruption. You can also use `%%bpl` cells in a Python notebook. See [Using BPL notebooks](https://answerdotai.github.io/basedpl/notebooks.html).

## New to APL?

APL is a language built around operations on whole arrays and notation for combining functions. Here is a taste of that style in BPL.

Numbers separated by spaces form a vector. Arithmetic applies to every element:

``` bpl
10+1 2 3
```

    11 12 13

Operators modify or combine functions. Reduce (`/`) turns addition into summation. `⍳10` generates 0…9:

``` bpl
+/⍳10
```

    45

Functions can also be combined without naming their arguments. In `avg←+/÷≢`, sum (`+/`) divided by tally (`≢`) defines the mean:

``` bpl
avg 1 2 3 4
```

    2.5

To see how these ideas express an algorithm, start from “a prime has exactly two positive divisors”. Form all remainders of 1 to 50 (`|⊗⍨1+⍳50`), count the zeros down each column (`+⌿0=`), and find the positions (`⍸`) whose count is two. Positions count from 0. `1+` turns each position back into its number:

``` bpl
1+⍸2=+⌿0=|⊗⍨1+⍳50
```

    2 3 5 7 11 13 17 19 23 29 31 37 41 43 47

[Getting started](https://answerdotai.github.io/basedpl/getting-started.html#example-algorithms) builds a primes function from the same divisor count, step by step, and displays the divisibility matrix along the way.

## What’s distinctive?

For APL users, some key differences are:

- [Based arrays](https://answerdotai.github.io/basedpl/arrays.html), as in BQN: numbers, characters and functions are atoms; enclosure always adds a layer.
- **Vectors in brackets, and grouping by spaces.** `[a b c]` is a vector, and `a+b × c+d` is `(a+b)×(c+d)`. A run that ends in a function is a train. For example, `+/÷≢ x` is the mean of `x`, and `2×` doubles its argument. `0⌷v` and `v₀` both select the first item of `v`.
- **Leading-axis broadcasting**, including expansion of length-1 axes, plus string keys and names on axes.
- **Exact integers and rationals** alongside approximate real and complex numbers.
- Dfns, trains and operators, with additions such as Under, iteration histories, windows and function arrays.

Positions and axes count from 0, as in BQN and Python. Approximate comparisons use tolerance `1E¯14`. See the [language principles](https://answerdotai.github.io/basedpl/principles.html) for why BPL works this way, the [glyph reference](https://answerdotai.github.io/basedpl/glyphs.html) for Dyalog differences and [Arrays](https://answerdotai.github.io/basedpl/arrays.html) for the array model.

### Numbers

Bare numbers are approximate. Use `ₓ` for exact integers and `r` for exact fractions:

``` bpl
1r3+1r6
```

    1ᵣ2

Complex numbers use `j` between real and imaginary parts. Functions such as square root extend into the complex domain:

``` bpl
√¯4
```

    0ⱼ2

See [Numbers](https://answerdotai.github.io/basedpl/numbers.html) for conversion and mixed arithmetic.

### Array literals and broadcasting

Write matrix rows directly in an array literal. Leading-axis agreement lets a vector supply one offset per row:

``` bpl
m←[1 2 3
   4 5 6]
m+10 20
```

    11 12 13
    24 25 26

See [array notation](https://answerdotai.github.io/basedpl/glyphs/brackets.html) and [broadcasting](https://answerdotai.github.io/basedpl/evaluation.html#agreement-and-pervasion).

### Keys and named axes

Axes can have names, and positions along them can have string keys. Describe the axes once, then select by key or reduce by axis name:

``` bpl
axes←["city":["NY" "LA"] "month":["Jan" "Feb" "Mar"]]
sales←axes:[10 20 30 ⋄ 40 50 60]
"LA" "Feb"⌷sales
+/⍠"month" sales
```

    50

    ["city":2]⍴["NY":60 "LA":150]

Keys and names travel with axes through operations such as transpose. Arithmetic aligns matching names and keys. See [Axis keys](https://answerdotai.github.io/basedpl/keyed.html).

### Function operators

A vector of counts keeps the history: one state for each count, where count 0 is the initial value. Here, double up to four times:

``` bpl
2×⍣(⍳5) 1
```

    1 2 4 8 16

Under (`⌾`) transforms the argument, applies a function, then reverses the transformation. Scale by ten, floor, and scale back to round down to tenths:

``` bpl
⌊⌾ 10× 1.25 2.78
```

    1.2 2.7

Explore [iteration and inverses](https://answerdotai.github.io/basedpl/glyphs/power.html), [Under](https://answerdotai.github.io/basedpl/glyphs/under.html), [windows](https://answerdotai.github.io/basedpl/glyphs/windows.html) and [function selection](https://answerdotai.github.io/basedpl/glyphs/agenda.html).

### Mathematical tools

[Primes](https://answerdotai.github.io/basedpl/glyphs/prime.html) and [factorisation](https://answerdotai.github.io/basedpl/glyphs/factor.html) are built in:

``` bpl
⨸360ₓ
```

    [2 2 2 3 3 5]ₓ

[Polynomials](https://answerdotai.github.io/basedpl/glyphs/polynomial.html) support coefficients, roots and evaluation. Polynomial functions can be [differentiated](https://answerdotai.github.io/basedpl/glyphs/derivative.html): for f(x) = 1 + 2x + 3x², f′(2) = 14.

``` bpl
f←[1 2 3]ₓ⌻ ⋄ f∂2ₓ
```

    14ₓ

[Probability distributions](https://answerdotai.github.io/basedpl/distributions.html) provide sampling, density, CDF and quantiles. Two fair coin tosses give these probabilities for 0, 1 and 2 heads:

``` bpl
coin←2 0.5 •distribution "binomial"
coin.density 0 1 2
```

    0.25 0.5 0.25

[Matrix division](https://answerdotai.github.io/basedpl/glyphs/domino.html) handles linear systems and least squares.

### Data and text

JSON objects become keyed arrays, with dot access to their fields:

``` bpl
order←•json "{""price"":10.5,""qty"":2}"
order.price×order.qty
```

    21

CSV headers likewise name column vectors. [Files, CSV and JSON](https://answerdotai.github.io/basedpl/data.html) covers reading, transforming and writing data. [Regex](https://answerdotai.github.io/basedpl/regex.html) supplies matching, captures and replacement through Rust’s regex engine.

### Drawing

`•plot` draws charts from arrays. Keys label the axes and name the lines. See [Plots](https://answerdotai.github.io/basedpl/plot.html).

``` bpl
["legend":"end"]•plot sales
```

![](index_files/figure-commonmark/cell-17-output-1.svg)

Build SVG from element functions and keyed attributes. Notebooks display the picture directly. The same element trees serialize to XML. See [XML and SVG](https://answerdotai.github.io/basedpl/xml.html).

``` bpl
circle←•element "circle"
text←•element "text"
c←["cx":50 "cy":40 "r":25 "fill":"orange"]circle ""
t←["x":50 "y":85 "text-anchor":"middle"]text "Hello, SVG"
["width":240 "height":240]•svg [c t]
```

![](index_files/figure-commonmark/cell-18-output-1.svg)

## Python

BPL functions are Python callables:

``` python
from basedpl import fn

mean = fn('+/÷≢')
mean([1, 2, 3])
```

Arrays have `.py`, `.np` and `.df` conversions for Python values, NumPy and pandas. Functions also have Python names and composition operators. See the [Python tutorial](https://answerdotai.github.io/basedpl/python.html).

For other frontends, the [process interfaces](https://answerdotai.github.io/basedpl/processes.html) provide JSON messages and interruptible workers. The [BPL library](https://github.com/AnswerDotAI/basedpl/tree/main/lib) contains more algorithms, codecs, interpreters and puzzles.

