(_NB: we will talk more about the shorthand type aliases and macros in scope later in this essay_)

## 💭 on brevity; readability depends on who is reading

thus, array programming languages are somewhat notorious for their terseness. this terseness often
extends to the underlying implementation of these languages as well. before we continue any
further, i'd like to cite a snippet from `@xpqz`'s excellent introduction to the K programming
language:

> K, like its Iversonian siblings APL and J, values conciseness, or perhaps we should say
> terseness, of representation and speed of execution.
>
> [A]ccusations of “unreadable”, “write-only” and “impossible to learn” are leveled at all
> Iversonian languages, k included. [..] **Readability is a property of the reader, not the
> language.**

- [_"Why k?"_][why-k] _(emphasis added)_

to restate this point bluntly, we will not spend time in this essay humoring questions about the
aesthetic or practical validity of these languages. real people wake up, and solve real problems
with array programming languages. whether this is the right paradigm for you is not dependent on
your first impression, but upon what problems you are trying to solve, and whom you communicate
with when solving them.

## 🌈 how broad is our imagination?

programming languages used in industry today are descendents of a few shared ancestors, most
commonly C. exceptions may draw from other languages such as ML, Lisp, Smalltalk, or Fortran, but
even these all share some unspoken consensus regarding whitespace, loop indentation, symbol names,
and the like.

many readers approach array languages with some preconceptions of what code should look like.
we as software engineers today have conservative ideas of what programming languages
can look like, compared to the variety found in written languages around the world.

### ➰ compute a cumulative sum in imperative programming languages

let's find the sum of integers `1..100` in a few programming languages.

**note** source for these can all be found in the `sums/` directory of this repository. we will exclude
unrelated syntactic overhead such as defining a `main` function, in order to focus on the core
logic of computing this sum.

**C**

```c
int sum = 0;
for (int i = 0; i <= 100; i++)
{
sum += i;
}
printf("%d", sum);
```

**POSIX Shell**

```sh
SUM=0
for i in $(seq 100);
do
SUM=$(expr $SUM + $i)
done
echo $SUM
```

**Julia**

```julia
sum = 0
for i=1:100
global sum = sum + i
end
print(sum)
```

**Rust**

```rust
let mut sum = 0;
for i in 1..=100 {
sum += i;
}
println!("{sum}");
```

these are strikingly similar! consider that Julia appeared roughly 40 years after C, or that the
Bourne shell is a command-line interpreter rather than a programming language. despite that,
most of the differences between these examples are syntactic minutia:
* in C, we must declare the type of the variable, an `int`
* in a shell script, we must perform our arithmetic inside of a subshell, using the `expr` builtin
* in Julia, we must specify that our assignment refers to the global `sum` variable
* in C and Rust, loops are wrapped within `{` and `}` curly braces; in Julia and sh, `end` and
`done` keywords are used.

otherwise, all of these programs share a common backbone, expressed in the following pseudocode:

```
sum = 0
for i in 1..100:
sum += i
print sum
```

#### λ find a cumulative sum in a functional language

this exercise could be repeated with a collection of various functional languages, but a similar
pattern can be found. programs declare a sequence or iterator and use a "fold" operation to find
the sum.

at its most explicit, this would look something like the following Rust program:

```rust
fn main() {
let sum = (1..=100).fold(0, std::ops::Add::add);
println!("{sum}");
}
```

or, using the `Iterator::sum` helper:

```rust
fn main() {
let sum: u32 = (1..=100).sum();
println!("{sum}");
}
```

**⤆ a refresher on function composition: you are used to reading from right to left**

suppose we have a value `x`, and two functions, `f(x)` and `g(x)`. "function composition" refers
to the act of finding the resulting value when `g` is provided the output of `f(x)`. this may be
written out as `g(f(x))`.

this notation represents the precedence of functions such that you would read this expression
from right to left. `x` is first provided to `f`, whose output is subsequently passed to `g`.

mathemeticians alternately use the `∘` operator to represent this. this composition of `f` and
`g` can also be written out as `f ∘ g`. some languages such as F# or Elixir provide a "pipeline"
operator to facilitate this style, and other languages like Haskell may be written in "point-free"
syntax such as this. Rust's `.` operator functions are similar sugar, passing its left-hand side
as the first parameter to the associated method named in the right-hand side.

functional languages' solutions to this problem will fit into one of two syntactic structures,
shown in pseudo-code below:

```
sum(seq(100))
```

```
100 |> seq |> sum
```

neither of these approaches are incorrect, but it is worth pointing out that many programmers are
already quite familiar with the experience of reading expressions from right to left! additionally,
many are also familiar with the idea of programming _tacitly,_ wherein variable names are not
assigned to intermediate values (_the `i` in the for-loops above_).

#### 󰘨 find a cumulative sum in an array language

here are two solutions to the same problem in J, and its related cousin K.

**K**

```
+/1+!100
```

**J**

```
+/1+i.100
```

_(NB: the "increment" operator is implemented later in this essay.)_

**🎳 breaking it down**

the K solution performs this same computation in 8 characters. let's break down how this works
bit-by-bit, starting with the lattermost 6 characters `1+!100`.

here are the definitions for the `!` and `+` verbs, from the `kona` K interpreter's help pages:

```
! monadic enumerate. !4 yields 0 1 2 3
+ dyadic plus. add numbers together
```

taken together, the expression `1+i.4` adds `1` to each element of the array `0 1 2 3`, yielding
`1 2 3 4`.

`/` is a kind of "adverb." in traditional human languages, an adverb is a part of speech used to
apply an adjective to a verb. or in other words, it describes how a verb is/was performed. this
same concept holds roughly true for J and K's adverbs.

adverbs and [gerunds][j-gerunds] are very similar to higher-order functions. a higher-order
function is a function that either accepts as an argument, or returns, another function. these
constructs provide a way for programmers to abbreviate or abstract over common control flow
patterns. J refers to the `/` adverb in this statement as "insert".

the "insert" adverb places the provided dyadic (`+`) operator between the elements of its argument.
thus, `+ / 1 2 3` is equivalent to `1+2+3`. notice that this is, syntax notwithstanding, the same
idea as saying `fold()`

so, the expression above has the following structure:

```
+ / 1 + ! 100
┝┳┥
┗━━━━━ the number 100
┝━┳━┥
┗━━━━━━ the sequence of numbers 0 through 99
┝━━━┳━━━┥
┗━━━━━━━━ the sequence of numbers 1 through 100
┝┳┥
┗━━━━━━━━━━━━━━━ find the sum of the given argument
┝━━━┳━━━━━━━┥
┗━━━━━━━━━━━━ add each of the numbers from 1 through 100
```

these programs share the same structure, save that `i.` is the verb for generating sequences,
rather than K's `!`. importantly, we can see a shared syntactic lineage here.

###  language categories

the united states government groups languages into categories from 1-5, ranking how difficult they
are to learn. category 1 languages are considered "easy" to learn, while a category 5 language
will take many hours before a student is considered fluent.

there is a catch: this scale measures the perceived difficulty for _native English speakers_.

the true difficulty of learning a new language is fundamentally entangled with what languages a
student is previously familiar with. A Spanish speaker may be able to quickly learn Portuguese,
but a language like Cantonese might include novel concepts such as semantically meaningful tone
that would trip up such a student. in much the same way, J would be rather easy for a K programmer
to learn and vice-versa.

in truth, i think that the difficulty of learning array languages is overestimated. while this may
seem to stem from incongruities in notation, i think this reputation is ultimately about larger
differences in people's philosophies and preconceptions about human-computer interfaces.

so, why _do_ so many programming languages look so similar?

#### 🤨 "strangeness budget"

we can find an illustrative story in the development of Rust's syntax for asynchrony. to briefly
summarize, Rust opted to use "postfix" notation when awaiting a `Future`. this results in code
that looks like:

```rust
let bytes = client
.send(request)
.await
.map(Response::into_body)?;
```

in other languages that use a traditional `await` keyword such as JavaScript, this might look
something like:

```javascript
let bytes = (await client.send(request)).into_body();
```

many discussions about the validity of this approach have already been borne out at
[great][rust-57640] [length][rust-50547]. i'll point to [this][ceej-postfix] excellent write-up
about the benefits of postfix `await` if you are interested in reading further. suffice to say,
this decision was controversial, because it strayed outside of what some people considered
reasonable syntax for asynchrony.

Steve Klabnik [wrote][klabnik-budget] about this phenomenon:

> [I]t’s important to be considerate of how many things in your language will be strange for your
> target audience, because if you put too many strange things in, they won’t give it a try.
>
> You can see us avoiding blowing the budget in Rust with many of our syntactic choices. We chose
> to stick with curly braces, for example, because one of our major target audiences, systems
> programmers, is currently using a curly brace language. Instead, we spend this strangeness
> budget on our major, core feature: ownership and borrowing.

in other words, in order to define and manage a strangeness budget, as with the idea of
"categories" for human languages, you must identify who your prospective students are. as Steve
noted, it was pragmatic and reasonable for Rust to focus on this demographic because many of its
early adopters would be C or C++ programmers.

our summing exercise above illustrated how similar different programming languages' looping
constructs are. ultimately, each new programming language is incentivized _not_ to challenge
people's notions of loops.

Aaron Hsu has remarked in his [talks][hsu-apl] about APL that the people who have the most
trouble learning languages like APL are often _computer science students_. we learn more than
syntax or grammer when studying computer science: for better and for worse, we also internalize
conventions of _thought._

readability is a property of the reader, indeed!

## 🍄 my experience

so, you ask, how was it?

hopefully at this point i've convinced you that this is an internally consistent programming
paradigm, even if it does not seem like your personal cup of tea. i'll be honest, at the outset
of this project it did not seem like my cup of tea either.

after spending time building a piece of software in this style however, i grew to like it
far more than i expected i would. in no particular order, let's gloss through some thoughts about
this experience.

### 🌐 brevity amplifies local reasoning

codebases for real-world production software are often quite large. most include tens of thousands
lines of code, and it is not uncommon for this number to reach the hundreds of thousands, or even
millions.

**lexical sprawl introduces a high amount of non-local reasoning into our systems.** with that,
we introduce a need for other specialized tooling: text editors with the ability to "fold"
sections of text out of view, terminal multiplexers with tab and window management facilities,
language servers to help find references to a given variable, formatting tools to maintain a
consistent syntactic style, the list goes on.

when working on j, i found that i spent about the same amount of time reading
through my existing code to introduce a new feature, but reading became a passive activity. i
no longer needed to scroll up and down, or jump to function definitions elsewhere. **my cognitive
function was no longer divided between reading and traversal.** i could instead open a
file, lean back, and read through the entirety of a subsystem without needing to manually interact
further.

in contrast, concise code has the effect of maximizing the amount of code that may be included in
local reasoning.

### 🐘 sufficient brevity implies a DSL

software written in this style includes a "_prelude_" of sorts, defining various shorthand forms.
these preludes go beyond just type aliases like `typedef char C` or `typedef long I`, however.
C's preprocessor is often leveraged to provide abstractions for keywords, function signatures,
or even **control flow**.

the Incunabulum's prelude is shown below. it defines an `R` shorthand for `return`ing a value,
`DO` to perform an operation across the length of an array.

```c
#define P printf
#define R return
#define V1(f) A f(w)A w;
#define V2(f) A f(a,w)A a,w;
#define DO(n,x) {I i=0,_n=(n);for(;i<_n;++i){x;}}
```

Kona, an open-source implementation of the k3 programming language, includes an almost verbatim
copy of this same macro:

```c
#define DO(n,x) {I i=0,_i=(n);for(;i<_i;++i){x;}}
#define DO2(n,x){I j=0,_j=(n);for(;j<_j;++j){x;}}
#define DO3(n,x){I k=0,_k=(n);for(;k<_k;++k){x;}}
```

as another example, Kona defines some control-flow macros for early returns, based on some predicate
condition.

```c
#define R return
#define P(x,y) {if(x)R(y);}
#define U(x) P(!(x),0)
```

shorthand for common control-flow like early returns is tremendously useful. Rust has the `?`
operator for this very reason! the next snippet shows some ngn k's equivalent shorthand notation
for loops, conditional statements, and switch statements.

```c
#define W(x,a...) while(x){a;}
#define B(x,a...) I(x,a;break)
#define P(x,a...) I(x,_(a))
#define I(x,a...) if(x){a;}
#define J(a...) else I(a)
#define E(a...) else{a;}
#define SW(x,a...) switch(x){a}
```

Rust was just as capable of defining such a prelude: `r!()` could be used to perform early
returns, `b!()` could perform heap allocations, `R` served as a shorthand for a fallible
operation resulting in `T`, and similar type aliases `C` or `I` were defined for characters and
integers.

j's prelude looks like this:

```rs
//! prelude; shorthand aliases for common types and traits, macros for common patterns.
pub(crate)use{Box as B,char as C,u32 as I,usize as U,Option as O,String as S,TryFrom as TF,TryInto as TI,Vec as V};
pub(crate)use{std::{alloc::Layout as L,clone::Clone as CL,cmp::{PartialEq as PE,PartialOrd as PO},
collections::{BTreeMap as BM,VecDeque as VD},fmt::{Debug as DBG,Display as DS,Formatter as FMT,Result as FR},
iter::{FromIterator as FI,IntoIterator as IIT,Iterator as IT},io::stdin,
slice::{from_raw_parts,from_raw_parts_mut},str::FromStr as FS}};
pub(crate)use{anyhow::{Context,Error as E,anyhow as err,bail}};
#[macro_export] /**`return`*/ macro_rules! r {()=>{return};($e:expr)=>{return $e};}
#[macro_export] /**`return Ok(Some(..))`*/ macro_rules! rro {($e:expr)=>{r!(Ok(Some($e)))}}
#[macro_export] /**`Ok(())`*/ macro_rules! ok {()=>{Ok(())}}
#[macro_export] /**`Box::new(..)`*/ macro_rules! b {($e:expr)=>{B::new($e)};}
#[macro_export] /**`unreachable!()`*/ macro_rules! ur {()=>{unreachable!()}}
/**`Result`*/ pub type R = Result;
#[cfg(test)]/**test prelude*/pub(crate) mod tp{
pub(crate) use{assert_eq as eq,assert_ne as neq,assert as is};
}
```

in my practical experience, this was also a pleasant toolbox to maintain. "Don't Repeat Yourself"
is an old adage among programmers, and this worked well to that effect. when i began to recognize
a pattern of some sort, i could define a shorthand for it.

LISP programmers have a mantra that code is data, and data is code; indeed, Kona's README notes
that LISP was an important influence on the K language. along the same lines, this style puts a
heavy emphasis on metaprogramming facilities. code is also syntax, and syntax is code.

**brevity mandates the construction of a domain-specific language (DSL) in which a piece of
software can then be written.** this style of hyper-succint code is ultimately a dialect to be
embedded _within_ a "host" language.

### 🦀 brevity is not a mutually exclusive property

writing concise Rust code did not detract from the traditional benefits of the language.

rather than writing this as a 1:1 direct translation of the [Incunabulum][incunabulum], i was
able to follow familiar idioms when implementing j, and found myself enjoying the usual benefits
of writing software in Rust.

**NB:** this next section assumes some previous familiarity with Rust's type system.

**🌳 abstract syntax tree**

as a straightforward example, this snippet of `src/r.rs` shows the definition of j's abstract
syntax tree (AST). an AST is the structured representation of statements in a language, which
most compilers and interpreters implement in some form or another.

`SY` is a newtype wrapper around a `String`. they're tremendously useful. see
["New Type Idiom"][api-guidelines-newtype] in the Rust API guidelines for more information on this
pattern.
the `D` and `M` structures represent dyadic and monadic verbs: `+`, `*`, `i.`, and so forth.
the `Yd` and `Ym` are structures are monadic and dyadic adverbs, `/` and `\`.

`N` is a recursive structure that uses these to represent a statement in j.

```rust
/**symbol */pub struct SY(S);
/**dyadic verb */pub enum D {Plus,Mul, Left, Right }
/**monadic verb */pub enum M {Idot,Shape,Tally,Transpose,Same,Inc}
/**dyadic adverb */pub enum Yd{/**dyadic `/` */ Table ,
/**dyadic `\` */ Infix }
/**monadic adverb */pub enum Ym{/**monadic `/`*/ Insert,
/**monadic `\`*/ Prefix}
/**ast node */pub enum N {/**array literal*/ A{a:A},
/**dyadic verb*/ D{d:D,l:B,r:B},
/**monadic verb*/ M{m:M,o:B},
/**dyadic adverb*/ Yd{yd:Yd,d:D,l:B,r:B},
/**monadic adverb*/ Ym{ym:Ym,d:D,o:B},
/**symbol*/ S{sy:SY},
/**symbol assignment*/E{sy:SY,e:B}}
```

while the monadic and dyadic verbs are simple enumerations, notice that the the `N` node contains
heterogenous payloads for each variant. outlining the benefits of pattern matching and algebraic
data types (ADTs) is out-of-scope for this essay, but in short: this approach helps prevent
invalid fields from being accessed or written to. interacting with the `l` and `r` fields will
cause a compilation failure, _unless_ we are within a block of code that has properly matched
against an `A::N` value.

**🔐 interfaces with guardrails**

here are some abbreviated snippets of `src/a.rs`. first, we define a collection of "marker"
types, to indicate whether the memory of an array has been initialized yet. this uses a "sealed"
trait; see the [API Guidelines][api-guidelines-futureproof] for more information on this pattern.

```rust
// src/a.rs
/**sealed trait, memory markers*/pub trait MX{} impl MX for MU {} impl MX for MI {}
/**marker: memory uninitialized*/#[derive(CL,DBG)]pub struct MU;
/**marker: memory initialized*/ #[derive(CL,DBG)]pub struct MI;
```

next, we use these marker types and `PhantomData` to mark an array as having memory that is either
initialized (`MI`), or uninitialized (`MU`). if no generic is given to `A`, i.e. `A`, it will
use `MI` by default.

```rust
use super::*; use std::marker::PhantomData as PD;
#[derive(DBG)]pub struct A{/**columns*/ pub m:U, /**rows*/ pub n:U,
/**data*/ d:*mut u8,/**layout*/ l:L,
/**memory state*/i:PD, }
```

now, what benefits does this provide?

it means that we can use `impl A{}` blocks to "gate" public interfaces, so that array access
cannot be performed until an array has been initialized. `impl A` may in turn be used to
provide interfaces that apply to _both_ uninitialized and initialized arrays.

```rust
impl A{
pub fn get(&self,i:U,j:U)->R{Ok(unsafe{self.ptr_at(i,j)?.read()})}
}
impl A{
pub fn set(&mut self,i:U,j:U,v:I)->R<()>{unsafe{self.ptr_at(i,j)?.write(v);}Ok(())}
pub(crate)fn ptr_at(&self,i:U,j:U)->R<*mut I>{self.ptr_at_impl(i,j,Self::index)}
}
```