x←5
[1 x 3]1 5 3
BasedPL (BPL) keeps APL’s glyphs and its right-to-left evaluation. It changes the notation where APL’s rules make code harder to read or to write. Most of the changes follow from one decision, to write lists in brackets. BasedPL stands for Based-array Programming Language, after the array model it takes from BQN.
Many of the notation choices answer problems that Marshall Lochbaum, BQN’s author, lists in his notes on BQN’s problems and on its first five years. Syntax and Evaluation state the rules without the reasons. BPL, APL and BQN side by side shows the choices on real code.
In APL, arrays written side by side form a list. 1 2 3, a b c and (x+1) y are all vectors. This is called stranding. It’s short, but it gives a space a different job in different places. Between arrays, a space separates the items of a list. Between functions it means nothing: +/÷≢ and + / ÷ ≢ are the same train. Between an operator and an array, it can do either.
That last case causes real trouble. An operator takes the single value to its right as its operand, after stranding has already joined that value to its neighbours. In APL, the operand in f⍤1 M is 1 M. You have to write f⍤1⊢M, where ⊢ is there only to break the strand. BQN’s documentation gives the example a +˝∘×⎉1‿∞ b, a matrix product. No rule decides well which of 1, ∞ and b should strand together. BQN marks its strands with ‿ instead.
In BPL, lists are written in brackets, [a b c], as in Python and JavaScript. Lochbaum notes that new BQN programmers “are always expecting [] to be the list notation, and it’d let you copy-paste JSON too”. You can still omit the brackets around a list of literals, as in 1 2 3 and "no" "yes". Inside brackets, names and literals mix freely:
Outside brackets, arrays side by side form a list too, whatever the names hold. +/x 3 is a two-item list whether x is a vector or a matrix. Each run, a sequence of tokens with no spaces between them, is one item of the list. In a b+1 the items are a and b+1. A bracket list is one run like any other:
A bracket list is a vector, however many items it has. [1] is a one-item vector, not a number:
Parentheses only group, as they do in maths. (1 2) is the same value as 1 2. To make a scalar, enclose with ⊂, as in BQN. ⊂[1 2] is a scalar, an array with no axes, holding a vector:
A function after ⊂ makes a train instead, as in ⊂+. The scalar holding + is written +ˢ.
Array notation extends brackets to higher ranks, as Dyalog’s does. Rows separated by ◇, or written on separate lines, become major cells:
The result has one more axis than each row. When the rows are numbers, which have no axes, the result is a vector. When the rows are one-item vectors, the result is a column:
[a◇b] is the Mix of [a b] when a and b have the same shape.
In parentheses, rows form a new level of nesting instead of a new axis. Each row is one item of a vector, read as if written in brackets. The rows can have different lengths:
A row holding one string is still a vector of one item. ("ab"◇"cd") holds two one-item vectors, while ["ab" "cd"] is the vector of two strings:
Items in brackets can be functions. [+/ ÷ ≢] holds three functions. Without the spaces, [+/÷≢] holds one, the mean:
Writing a function expression in brackets is one way to make it a value. In BQN this takes ⊑⟨Expr⟩ or a name, a problem Lochbaum lists as “Converting a function expression to a subject is tricky”. The other way is fˢ, a scalar holding the function f.
Items in a list are evaluated left to right, as statements are. BQN chose the same order for its lists and strands. Here each item prints as it’s evaluated, before the list itself is displayed:
Outside brackets, literals separated by spaces form a strand, as in 1 2 3. Every other space separates runs. Each run is evaluated first, as if it were in parentheses:
A space can separate a derived function from its argument: +/⍤1 m applies +/⍤1 to m. A run ending in a dyadic operator takes the next run as its operand, as if no space came between them. A literal argument after a space still joins the operand’s strand, as in f⍤1 2 3, whose operand is 1 2 3. The separator ⁝ (Alt-:) keeps tokens apart without ending the run. It separates names that would merge and literals that would strand. All three of these sum each row:
A space after an operator also lets a longer function be its operand without parentheses. ⌊@ 10× rounds down to one decimal place, with 10× as the operand of @:
Lochbaum describes the problem that runs solve, under “Modifiers look looser than trains without spaces”. In BQN’s ⋆∘-ט, the - looks closer to ⋆, but it binds to ט. Writing ⋆∘- ט shows the structure. He calls it “unfortunate that this is something the writer must do rather than something the notation encourages”. In BPL the space is part of the notation.
Under “Long trains are hard for humans to parse”, he notes that readers lose track of a train’s structure after four to eight parts. Runs let spaces show that structure. ⌊ +/÷≢ is the floor of the mean:
Code that is fully spaced, or not spaced at all, groups as in APL. Only mixed spacing changes the grouping. A reader used to APL reads 1+2 × 3 as 7, but here it’s 9:
A tool that normalises spaces would change a program’s meaning. Other languages give spaces meaning too. K reads a -1 differently from a - 1. Nim tried an experimental mode in which the spaces around an operator changed its precedence, and removed it in version 0.20.
A run that ends in a function has no argument yet. It’s a function, built as an APL train with one addition. A subject before a function binds the one part after it, as 2 does in 2×. Here 32+1.8× converts Celsius to Fahrenheit:
The rest follows APL’s train rules. A bound part such as 0.5× forms an atop with the train after it. In 0.5×⊢+÷, that atop gives the same result as Dyalog’s fork, whose left part is the subject 0.5. Binding covers the common case of fixing a left argument, without ↣. K has the same idea, called projection, in which 2* is a function.
+/÷≢ nums and +/÷≢nums differ only in the space before nums. The first applies the train +/÷≢, the mean, to nums. The second is one run ending in a subject, the expression +/(÷(≢nums)):
If both spellings meant the same, the space would mean nothing. In everyday arithmetic, where the functions have arrays between them, as in 32+1.8×, the train gives the same result as the expression. The readings differ only when a fork gets a function as its left part, as in 0.5×⊢+÷. APL has the same split, with nothing in the source to mark it. Removing the argument from APL’s 0.5×⊢+÷ω turns it into a fork with a different meaning. In BPL the space shows which reading you get.
Index ⌷ selects. I⌷Y takes one item of I for each leading axis of Y. In K, v 1 selects, because K treats a list as a function of its positions. In BPL v 1 is a strand, because subjects and functions stay apart. One literal position can be written more briefly as a subscript, as in v₁:
Selecting with a number drops that axis from the result. Selecting with an array of positions puts the array’s shape in place of the axis. [⊂1]⌷v gives a scalar holding the item, [[1]]⌷v a one-item vector, and [[2 0]]⌷v two items:
Dyalog has the same rule, but its v[1] looks like a one-item list and gives a scalar. To get a one-item vector in Dyalog, write v[,1].
Because Index takes its positions on the left, its right argument can be any expression. With sales keyed by city and month, "NY"⌷+/sales selects New York’s total with no parentheses:
Positions and axes count from 0, as in BQN, J, K, Python and NumPy. Negative positions count from the end.
c⌷"no" "yes". With 1-origin, the position would be 1+c.¯n to n-1 with no gap. With 1-origin, position 0 is an error between position 1, the first item, and position ¯1, the last.n|i wraps a position round a vector of length n. ⌊i÷n and n|i give the row and column of a flat position.grade and where. Those positions must agree with Python and NumPy, which count from 0.Here the comparison’s result is used as the position:
To count from 1, use Range: ↦10 is the numbers 1 to 10. Code from APL books and libraries assumes 1-origin and needs converting.
Two rules follow J and BQN where 0-origin left a choice. With a negative length, Iota counts down, as J’s i._3 does:
Interval Index counts the boundaries at or below each value, as BQN’s does. Below the first boundary the count is 0. If it returned a boundary’s position instead, the position below the first boundary would be ¯1, which selects the last item:
A negative position that a program computes also counts from the end. With dot brackets, as in w.[i-1], the position for i=0 is ¯1. w.[i-1] then gives the last item, as w[i-1] does in Python. For a different result at the edge, wrap with n|i-1 or clamp with 0⌈(n-1)⌊i-1:
BPL uses BQN’s based array model. Numbers, characters and functions are atoms. An array is a rectangular collection of values. Atoms are not arrays. Enclosing always adds a layer: ⊂3 is a rank-0 array holding 3, a different value from 3. Enclosing it again gives depth 2:
In APL’s nested array model, enclosing 3 gives 3 again. Under the based model, every value has one representation, whether you pass it to a function, return it, or store it in an array. [+/ ÷ ≢] is a list of three functions. Lochbaum’s page on the model gives the longer argument.
Under static kinds, a number’s type comes from how the program writes or computes it, never from its value. If a number’s type changed with its value, a program that works on one input could behave differently on another. Static kinds are the setting for performance work, such as training neural networks. Performance shows what they speed up. Dynamic kinds, the default, are for convenient interactive analysis. Under dynamic kinds, integers are exact and never wrap, and float comparisons are tolerant. Under dynamic kinds, some results take their type from their values: √¯4 is complex, whereas √4 is a float. Under either setting, BPL doesn’t make a float exact because it happens to be whole: 2.0 is a float, and so is 2.0+1. To get exact integers, use ₓ.
BPL follows BQN’s leading-axis model. A function that works on a whole array acts on its major cells, the cells along its first axis. The last-axis glyphs ⌽ / \ , are the leading-axis functions applied at rank 1. Their first-axis forms ⌽₀ ⌿ ⍀ ⍪ are the leading-axis functions themselves. Every function therefore treats a matrix by the same rule.
Search follows that rule. ι ∊ ~ ∪ ∩ compare the major cells of the searched argument, which for a matrix are its rows. Here ~ removes every row that is 1 2, leaving a one-row matrix:
The other argument is compared in cells of the same rank as those major cells. A unit has no major cells to search. To remove the spaces from a string, give ~ the string " ". Giving it the character ' ', a unit, raises a RANK error:
Partition splits along the first axis too, into blocks of major cells. Here new blocks start at rows 0 and 2:
⊂¹ applies Partition at rank 1, which partitions each row instead, and ⊂₁ applies it along axis 1, which splits a matrix into blocks of columns.
Encode and Decode put digits on the last axis, as J’s #: and #. do. Encode turns each number of a vector into a row of digits. Decode turns the rows back into numbers:
At rank 0, the function gets each atom as itself and each array item enclosed in a scalar. BQN’s ⎉0 encloses atoms as well. The depth of each 0-cell shows the difference:
As a result, ⊢⁰ returns its argument unchanged, even when the argument is nested. At rank 0, a function receives each number as the atom that a literal or selection gives, not enclosed in a scalar. Each ¨ gives the function the items themselves.
Without names, arithmetic pairs axes by position, from the leading axis, as Agreement describes. When axes have names, they pair by name instead. Two axes with the same name pair, whatever their positions. A named axis pairs with an unnamed axis by position, and the result axis keeps the name. Two axes with different names never pair. In arithmetic, axes with different names build a grid, as an outer product does.
Pairing by position can pair the wrong axes. Here r has a row for each item of a batch and a column for each output. bias has a value for each output. By position, bias pairs with the rows instead. Because the number of rows equals the length of bias, no error shows the mistake:
With names on both arrays, bias pairs with the output axis:
Selection also pairs axes by name, so a formula written with named indices reads as index notation, with a name where einsum has a letter. •index gives an index a fresh hidden name, which can’t collide with the names on a caller’s data. An index used twice pairs with itself, so m.[i i] is a diagonal:
No feature requires names. A function written for unnamed axes also runs on arrays with named axes. If it gives different values on arrays with named axes, the difference comes from how the names align the axes. Named axes gives the full rules.
A form that has a reasonable meaning gives a result, not an error. BPL returns a result without error even when that result would be a bug in some programs, if doing so gives useful behaviour or speed. Negative positions are one case, as “Counting from 0” shows. Using ⌈ with NaN is another case. It gives NaN or the other argument, whichever the processor’s fastest instruction gives. The answer can differ between platforms.