01 One sentence, one value
J has no operator precedence. A sentence is evaluated strictly from right to left, so the rightmost verb takes the noun to its right, and the result becomes the right argument of the next verb. Parentheses are the only way to group.
2 * 3 + 4 NB. 14 10 - 3 - 2 NB. 9 - 2 + 3 NB. _5
A sentence produces either a noun or a verb. Nouns are printed in J's display
format. A verb value is printed as its spelling, so entering + alone
shows +.
+ +/ (+/ % #)
02 Everything is an array
There is one noun type. An atom is a rank-0 array; a list is rank 1; a
table is rank 2. The $ verb reports shape, # reports
tally (the number of items), and $ with a left argument reshapes.
Scalar extension is not special-cased: an atom has an empty frame, so it broadcasts
against any array.
i. 5 NB. 0 1 2 3 4 i. 3 4 NB. a 3x4 table 2 3 $ i. 6 NB. 0 1 2 / 3 4 5 $ i. 3 4 NB. 3 4 # i. 3 4 NB. 3
Literals cover characters, exact integers, rationals and complex numbers:
| Written | Meaning |
|---|---|
42 _3 | integer; a leading _ is the minus sign |
2.5 1e6 1e_5 | floating point |
_ __ _. | positive infinity, negative infinity, NaN |
123x | extended integer, promoted past the native range |
1r2 | exact rational, one half |
3j4 | complex number, 3 + 4i |
'text' | character vector; '' inside a string is one quote |
1 2 3 | a strand: juxtaposed nouns form one array |
Display follows J's conventions. Negative numbers use _, floats keep
five significant digits, numeric tables align each column, character arrays print
as text, and boxed arrays are drawn as bordered cells.
% 3 2 % 3 1 % 0 0 % 0 1r2 + 1r3 'hello' < 1 2 3
03 Verbs read in two directions
Every verb has a monadic meaning (one argument, on its right) and a dyadic meaning
(a noun on each side). The sentence decides which applies: - 5 is
negation, while 10 - 5 is subtraction. A verb that has no definition
for the valence being asked reports valence error.
| Verb | Monadic | Dyadic |
|---|---|---|
+ | conjugate | addition |
- | negate | subtract |
* | signum | multiply |
% | reciprocal | divide |
^ | exponential | power |
= | self-classify | equal |
~: | nub sieve | not equal |
< | box | less than |
> | open one level | greater than |
<: | decrement | less or equal |
>: | increment | greater or equal |
i. | integers 0..n-1 | index of |
$ | shape | reshape |
# | tally | copy |
, | ravel | catenate |
|. | reverse | rotate |
{. | head | take, with fill |
}. | behead | drop |
{ | catalog | index |
|: | transpose | permute axes |
$. | make sparse | toggle sparse/dense |
Arithmetic and comparison verbs have rank 0: they see atoms, and the rank machinery
iterates the surrounding frames. That is why a scalar extends across a list, and why
mismatched frames report length error.
1 2 3 + 10 NB. 11 12 13 1 2 3 + 1 2 NB. length error 1 2 3 = 2 NB. 0 1 0 = 1 2 1 3 NB. a 3x4 classification table ~: 1 2 1 3 NB. 1 1 0 1
Characters compare with characters, boxes compare for equality, and numeric types
promote along INT → BIGINT → RATIONAL → FLOAT → COMPLEX. Mixing a
character with a number is a domain error.
04 Adverbs derive new verbs
An adverb takes a verb and produces another verb. / inserts the verb
between the items of its argument, folding from the right; \ applies it
to each prefix; ~ makes a monad apply its dyad to the same argument
twice, and makes a dyad swap its arguments.
+/ 1 2 3 NB. 1 + (2 + 3) -/ 1 2 3 NB. 1 - (2 - 3) +/\ 1 2 3 NB. 1 3 6 +~ 1 2 3 NB. 2 4 6 3 +~ 10 NB. 13
Insert needs an identity for an empty argument. The implemented identities are
0 for + - < > ~: and 1 for
* % ^ = <: >:, so +/ i. 0 is 0 and
%/ i. 0 is 1.
+/ is two words: the verb + and the adverb
/. The derived verb is an ordinary value, so it can be assigned and
passed around.
f =: +/ f 1 2 3 4 NB. 10 f 2 3 4 NB. 9
05 Rank chooses the cell
The rank conjunction " says how much of each argument a verb should see
at once. u"r applies u to rank-r cells,
iterating over the leading frame and assembling the results. A negative rank counts
down from the argument's rank, so _1 means “whole argument minus one
axis”.
+/ i. 3 4 NB. whole table: 12 15 18 21 +/"1 i. 3 4 NB. each row: 6 22 38 +/"_1 i. 3 4 NB. same, expressed negatively (<"0) 1 2 3 NB. box every atom
A one-number spec sets all three ranks. A two-number spec is
left right, with the monadic rank taken from the right; three numbers
are monadic, left and right.
+/"0 1 i. 3 4 NB. 6 22 38 (+ -) 5 NB. 0
06 Trains have no nouns
A phrase made only of verbs is itself a verb. Two verbs form a hook and three form a fork; longer trains group from the right. This is how J writes a mean without ever naming an argument.
| Train | Monadic | Dyadic |
|---|---|---|
f g | y f (g y) | x f (g y) |
f g h | (f y) g (h y) | (x f y) g (x h y) |
(+/ % #) 1 2 3 4 NB. sum divided by tally: 2.5 (+/ % #) i. 3 4 NB. means of the columns: 4 5 6 7 (+ -) 5 NB. 5 + (-5): 0
Without parentheses, - - 5 is two monads, not a hook, because the noun
is present. A train must be a verb phrase.
07 Names and definitions
=: assigns in the session table, =. assigns locally
inside an explicit verb. At top level both write the same table. Assignment prints
nothing, and chains right-associatively. A name's part of speech — noun or verb —
comes from the value assigned, and the parser uses that class in later sentences.
a =: 6 a * 7 NB. 42 b =: a =: 7 b NB. 7 (c =. 3) + 2 NB. 5, and c is bound
An inline {{ ... }} definition holds one expression and binds
x and y on call. A definition started with
name =: {{ or name =: 3 : 0 is collected until
}} or ), and uses the same statement parser, so control
words work in either form.
inc =: {{ y + 1 }}
inc 41 NB. 42
plus =: {{ x + y }}
20 plus 22 NB. 42
| Control word | Form |
|---|---|
if. | if. cond do. ... else. ... end. |
while. | while. cond do. ... end. |
for_i. | for_i. values do. ... end., binding i and i_index |
return. | return. value, or bare return. |
sumto =: 3 : 0 total =. 0 i =. 1 while. i <: y do. total =. total + i i =. i + 1 end. total ) sumto 10 NB. 55
The value of the last statement executed is the result when no
return. fires. In a for. loop the variable is
i by default, or the name after for_.
squares =: 3 : 0 out =. 0 $ 0 for_i. i. y do. out =. out , i * i end. out ) squares 5 NB. 0 1 4 9 16
08 When something is wrong
An error aborts the sentence but not the session. The REPL prints the J phrase after a vertical bar and waits for the next input.
| Message | Usually means |
|---|---|
spelling error | a malformed literal, unknown character, or unterminated string |
syntax error | the words do not form a sentence |
value error | a name has not been assigned |
domain error | the wrong type or kind of argument, such as 1 + 'a' |
length error | two argument frames do not agree |
rank error | a structural verb was given the wrong rank |
index error | an index is outside the array |
valence error | the verb has no definition for that valence |
limit error | the requested result is too large to build |
1 2 3 + 1 2 NB. length error
1 2 3 { 1 2 NB. index error
foo NB. value error
09 Sparse arrays
$. converts a dense array to sparse storage: a fill atom plus the
non-fill positions that are actually stored. Monadic $. always makes an
array sparse, 0 $. toggles between the two representations, and
$.^:_1 densifies.
$. 3 4 $ 0 75 0 53 0 0 67 67 93 0 51 83
Sparse display prints the flat index coordinates of each stored value. Structural verbs remap the stored entries instead of expanding the array, and reductions and prefixes assemble sparse results without densifying. Boxed sparse arrays use an empty box as their fill.
0 $. $. 2 2 $ 1 0 0 2 NB. dense again $.^:_1 $. 2 2 $ 1 0 0 2 NB. the same, by inverse 2 # $. 3 $ 1 0 2 NB. copy keeps sparse storage
10 What is left out
This is a teaching subset, ported from the Java project in this repository, not a replacement for a full J implementation. It is deliberately conservative:
- No locales, system facilities, or file and foreign conjunctions.
- No
@,&, bond, or inner product+/ .*. - No fit conjunction
#!.f; copy uses the type's default fill. - Only
if.,while.,for.andreturn.— noselect.,try.orthrow. - Five significant digits for floats, with approximate tie rounding and exponent cutovers.
- Integer arithmetic promotes to extended integers on overflow; the browser build uses JavaScript numbers up to the safe-integer range, then BigInt.
- An inline
{{ ... }}holds one expression; multi-line definitions are collected by the REPL.
Within those bounds the array model, the parser, rank, adverbs, trains, explicit definitions and sparse storage all behave as described above.