5+12

18÷3
108÷11

4×7
3.893×7.6

Use - for subtraction, and ¯ for negative signal.

100-95
8-16

3+2 4 11 7 5

Spot the difference on applying a sum to each element and applying a sum on two numbers:

1+2 3 4
1+234

Lists can be on either side of the sign.

6 3 8 1+3
2.5 33.7 12 8÷15
9.8 11.2 17 1.2×1.175

It is possible to perform arithmetic between two lists in a per-element basis, but only if their length matches.

12 3 29 4×1 3 5 2

APL runs stuff from right to left, since there are so many functions on the language.

3×3-1

That is because APL groups things from right to left as well.

2 3 1+8÷2 2 2

If you need to make things unambiguous, use parentheses.

(2 3 1+8)÷2 2 2

Remember again the difference between - and ¯!

1985 - 1066       ⍝ Difference of two numbers
3 ¯1 ¯7 + ¯4 ¯1 2 ⍝ Sum between two lists with negative numbers

2-3+5             ⍝ This does 3+5, then does 2-8
2 ¯3+5            ⍝ This adds 5 to the number list 2 ¯3

Some functions can be used for more than one purpose.

When used in infix notation, ordinary operations have their intended effect:

5+4
1 3 4+3 1 6

You can, however, use the functions in prefix notation, which will change their effect.

+ appears to do nothing. Its true usage happens for assignment, which we'll see next.

+12

- inverts the signal of al numbers on the list.

- 3 ¯6 ¯8 4 12 ¯9

÷ takes the reciprocal of all numbers (divides 1 by them).

÷1 2 4 10 100

× takes the sign of each number from the list. Yields 1 for positive numbers, ¯1 for negative, and 0 for zero.

×8 0 ¯3 ¯7 0 4

There is no definition for postfix operators; that would be a syntax error.

• ⌈ rounds a number up;
• ⌊ rounds a number down.

To perform accurate rounding, you may want to use one of the following patterns:

⌈120.11 12.32 65.01 13.52 - 0.5
⌊99.99 12.82 15.39 48.90 + 0.5

When using those operators under an infix form, ⌈ selects the greatest number, while ⌊ selects the smallest number.

2 ⌈ 6
2 ⌊ 6

One can also use these operations to perform comparisions between lists of numbers.

6 8 1 ⌈ 3 5 9
6 8 1 ⌊ 3 5 9

If you want to end a session, use

)OFF

This will not be tangled.

An assignment can be done with a variable name and a ← symbol.

A ← .175

This enables A to be used in expressions.

200×A
A×30.50 12.25 60.30 15.00
⌈ A×30.50 12.25 60.30 15.00

C is the conversion factor for fonverting pounds to kilograms.

C ← .45359237
17 × C        ⍝ Convert 17 lbs into Kg
⌈C×11×14      ⍝ How many Kgs are there in 11 stones,
              ⍝ then round up

To keep a calculation, we then use variables.

JOE ← ⌈C×11×14

Valid statements:

AAA ← 4
ab ← 1
C9999 ← 0
Jack_Smith ← 100

Which denotes that APL is case sensitive.

Also, APL doesn't have bare words as variable names:

JOHN SMITH ← 100

However, using parentheses will create two identical variables with the same value. This happens in both GNU APL and Dyalog.

(JOHN SMITH) ← 100 ⍝ Creates JOHN with value 100
                   ⍝ and SMITH with value 100

And if you start a variable name with a single number, the number will be printed right after the value, which is assigned to the variable name that follows:

5B ← 12

PRICE ← 12.45 5.60 5.99 7.75
+VAT   ← PRICE × A ⍝ A was assigned earlier

The + operator, when put before an assignment, forces a declarative behaviour on the assigned variable – in other words, forces the variable to be displayed.

Using an unassigned variable causes a VALUE ERROR.

The )OFF command has already been presented earlier.

)VARS lists all variables in the workspace.

)VARS

)WSID shows the identity of the current workspace, which defaults to CLEAR WS.

)WSID

This command can also be used to change the identity of the workspace; we change its name to NEW. The variables in it won't change.

)WSID NEW

To remove the variables (and the name), we can use )CLEAR.

)CLEAR

APL doesn't only deals with numbers, it can also deal with text. Just apply quotes.

A ← 'APL WILL PROCESS TEXT'
C ← 'CHARACTERS'

To insert quotes inside the text, use ''.

NAME ← 'WHAT''S IN A NAME? '

Other way to do that is by using double quotes around the characters.

NAME ← "WHAT'S IN A NAME? "

Consider the following variables.

N ← 'NET PRICE'
QTY ← '230'

Attempting to perform arithmetic on text generates a DOMAIN ERROR:

N×10
QTY+5

One can assign one value to multiple variables at the same time:

(ZAK YAK) ← 5

Or assign many values to many variables at the same time too:

(YEN MARK BUCK) ← 10 20 30

This part is straightforward.

N 10
NAME C

X ← 18
Y ← 3 1985
X Y

NAME X C

'NET PRICE: ' 10

When writing X Y, these values were joined in a list of two elements. The first element was the number in X, the second was the two-element list in Y.

Let's store this result.

Z ← X Y

Operations done in Z will not affect X and Y (also notice how +10 maps elegantly into sublists!!!):

Z ← Z+10

Example with characters.

CNAME ← 'BASIL '
SNAME ← 'BRUSH'
NAME  ← CNAME SNAME

Notice, though, that NAME is a list of two elements, each being a list of characters; this is called a nested variable.

The comma (,) allows APL to catenate lists.

NAME ← CNAME,SNAME

One can see that the variable indeed became a non-nested list of 11 characters.

⍴NAME

Single numbers (separated by spaces) and characters make up lists.

PIERRE ← 1 2 3 4
MIREILLE ← 'FILLE'

Numbers enclosed in parentheses are treated as single items, so now PIERRE will be a list, containing two lists.

PIERRE ← (1 2 3) (4 5 6 7)

A list of character lists is easier, just enclose each sublist in quotes (if you were to put it in a single, simple list, you'd put everyone under the same quotes anyway):

FRANCOISE ← 'UNE' 'JEUNE' 'FILLE'

This is not good for arithmetic, but it's useful to store characters and numbers together.

PHONES ← 'BILL' 577332 'FRANK' 886331

Let's start with a clean workspace.

)CLEAR

From now on, we clear the variables and the workspace across chapters.

)CLEAR

? is the Roll function, also called Random or Deal.

This generates numbers on range 1 to 100:

? 100

The two-argument form generates a list of n (left) unique numbers from 1 to m (right):

50 ? 100

In fact, it should always be true that n ≤ m, since the generated numbers are unique. If not, we'll have a DOMAIN ERROR.

Both n and m can be replaced by variables as well.

Iota, or Index, generates a sequence of numbers from 1 to m in its one-argument form.

⍳100

When entering tables, we use dyadic for of the rho (⍴) function, also called Shape or Reshape. The list before ⍴ states the order of the table; the following elements are its rows, element by element.

4 3 ⍴ 10 20 30 40 50 60 70 80 90 100 110 120

Let's generate twelve random numbers, then display them in a 4×3 table.

DATA ← 12 ? 100
4 3 ⍴ DATA

If you feed ⍴ less numbers than expected, APL just keeps wrapping these numbers. If you feed more than expected, APL uses just enough numbers to build the table.

4 3 ⍴ 1 2 3 4 5

And so follows that supplying one number fills the whole table:

3 5 ⍴ 1

Let's begin.

SALES ← 3 3⍴20 13 8 30 43 48 3 50 21
SALES

Performing arithmetic on a table affects every number, just like in a list.

SALES×10

Let's set up another table.

PRICES ← 2 3 ⍴ 21 2 12 47 33 1

This operation causes a LENGTH ERROR:

SALES×PRICES

This is because SALES is 3×3 while PRICES is 2×3. So let's reshape SALES into a 3×2 table. This way, both of them will have the same number of elements.

SALES ← 3 2⍴SALES

But that still won't do… we're trying to multiply elements of same address here, not make matrix multiplication. Let's try again.

SALES ← 2 3⍴SALES

Ok, now we're good and we can proceed.

TOTAL ← SALES×PRICES
SALES-PRICES

Catenating tables produce a big table. Each row is catenated like a list. Therefore, catenated tables must have the same number of rows.

SALES,PRICES

Let's test it a little more.

LITTLE ← 2 2⍴1
MEDIUM ← 2 6⍴5
BIG    ← LITTLE,MEDIUM

To perform LITTLE+MEDIUM, we pad LITTLE with a table of zeroes.

ZEROES ← 2 4⍴0
LITTLE ← LITTLE,ZEROES
LITTLE+MEDIUM

We could also have the zeroes on the other side; let's reset LITTLE and do it.

LITTLE ← 2 2⍴1
LITTLE ← ZEROES,LITTLE
LITTLE+MEDIUM

Since there is this kind of ambiguity, that is the reason why APL doesn't do arithmetic on data of unequal size.

Let's set up a 4×3 table for the next example.

+TABLE ← 4 3⍴2 12 15 4 11 7 1 16 8 20 19 9

Let's select the 9 in the bottom row, rightmost column.

TABLE[4;3]

We sum the element at Row 1, Column 2 to the element at Row 2, Column 2. Then we put it on Row 3, Column 2:

TABLE[3;2] ← TABLE[1;2] + TABLE[2;2]

We can select more than one element in a row, or even in a column.

TABLE[1;1 2]
TABLE[1 2;2]

To select entire rows or columns, omit the other parameter.

TABLE[1;]
TABLE[;1]

Let's replace the numbers in column 3 with the sum of numbers in columns 1 and 2.

TABLE[;3] ← TABLE[;1] + TABLE[;2]

Also note that indexing can also be applied on lists.

LIST ← 8 1 90 4
LIST[2]

In APL, data has dimensions.

• Single numbers have dimension zero.
• A list has one dimension.
• The previous tables have two dimensions.
• Three-dimensional tables/arrays are like cubes, having depth, height and length.
• It is possible to create arrays of many dimensions in APL.

SALES ← 6 4⍴24?50

In SALES, the salesmen are rows, the products are columns. If we wanted to represent more than one region – say, three regions –, we'd need another dimension.

+SALES ← 3 6 4⍴72?100
SALES[2;5;4]           ⍝ Plane 2, Row 5, Column 4
SALES[2;;]             ⍝ Plane 2

While the dyadic usage of ⍴ involves creating arrays, the monadic usage of ⍴ allows one to enquire about the size (or shape) of existing tables, variables, etc.

⍴SALES

Let's create some data.

TABLE ← 5 3⍴15?20
LIST ← ⍳6
NUM ← 234

Now let's ask about their shape.

⍴TABLE
⍴LIST
⍴NUM

Notice that, since NUM has no shape (equivalent to a point), APL gives an empty response.

We don't need variables to do this kind of thing, though. We can apply directly to literals.

⍴12 61 502 1 26 0 11
⍴'SHAMBOLIOSIS'

This is also straightforward; characters are stored as a list of characters. Let's do some experiments.

⍝ Compare these two.
ALF ← 3 5⍴'ABCDE'
NUM ← 3 5⍴12345

MYNAME ← 'GORSUCH'
⍴MYNAME

3 7⍴MYNAME
3 14⍴MYNAME
3 18⍴MYNAME

MYNAME ← 'GORSUCH '
⍴MYNAME

3 40⍴MYNAME

Solution for the given example.

4 11⍴'ADAMS      CHATER     PRENDERGASTLEE        '

We can build tables containing characters and numbers, just like the lists.

MIXTURE ← 3 3⍴'A' 1 'B' 'C' 2 'D' 'E' 3 'F'

Tables can contain other tables or lists.

NEST ← 2 3⍴(2 2⍴⍳4) (⍳5) 'A NAME' (2 4⍴⍳8) 23 (3 4⍴'NAME')
⍴NEST

The depth (≡) function shows the degree of nesting in a variable.

≡45          ⍝ Values have depth 0
≡1 2 3       ⍝ Lists have depth 1
≡2 2⍴3 4 5 6 ⍝ Tables too

Now let's check the depth of NEST:

≡NEST

When at least one element of a list or table is also a list or table, the depth becomes 2; and so on, as long as you have child list/tables inside child list/tables:

BIG_NEST ← NEST NEST
⍴BIG_NEST
≡BIG_NEST

Since the components of BIG_NEST already have depth 2, BIG_NEST adds one more layer of depth.

Some interesting snippets showcasing the strength of APL: combining functions.

⍝ Playing with sizes of character lists
(⍴'ABC','DEF')+⍴'GHI'

⍝ Selecting the first nine numbers in row 1 of a big table
TABLE ← 10 10⍴100?100
TABLE[1;⍳9]

The Slash (/) or Reduce operator is not a function; it modifies or extends the operation of the functions it is used with.

It works as if by putting the operator between the numbers.

+/ 1 6 3 4
×/ 1 2 3 4

This can be done on a table too, however it will sum in a row basis.

TABLE ← 3 3⍴⍳9
TABLE
+/ TABLE

We can, however, apply Reduce twice to obtain the entire sum.

+/+/ TABLE

Useful combination: To select the largest number in a list, use ⌈:

⌈/ 75 72 78 90 69 77 81 88

The opposite equivalent (⌊) selects the smallest number:

⌊/ 75 72 78 90 69 77 81 88

A final example: We take the sum of X (which is 15) and divide it by X's shape (5). This yields 3, as expected of calculating the average of a number.

X ← ⍳5
(+/ X)÷⍴X

Now we'll preserve statements.

It seems some APL editors have a built-in editor. For example, one can use the following commands:

)EDIT MYFUNC ⍝ On modern editors
)ED MYFUNC   ⍝ On Dyalog
∇            ⍝ On older editors, and on GNU APL as well

GNU APL also calls a new buffer when defining a function, under Emacs. We can also send the following region to the interpreter no problem. We just need to type in the function (∇) operator, which starts the input mode.

Typing ∇ again goes back to calculator mode.

∇TRY1
  'Type some numbers: '
  NUM ← ⎕   ⍝ Asks for user input
  'Total is: ' (+/ NUM)
∇

In case this function doesn't work when typing, just use ∇TRY1 to change its definition on the editor.

This defines a user function TRY1, which takes no arguments. The Quad (⎕) operator calls in for user input.

You can edit a function such as TRY1 anytime, by typing ∇TRY1 on the REPL; other APL implementations will allow you to use the command )EDIT TRY1, for example.

Here is another example:

∇TRY2
  'Type some numbers: '
  NUM ← ⎕
  'You have entered' (⍴NUM) 'numbers'
∇

And as requested, here is a way to calculate the average of some numbers:

∇AVERAGE
  'Type some numbers:'
  NUM ← ⎕
  'Integer average of these numbers is:' (⌊(+/ NUM)÷⍴NUM)
∇

One more definition.

∇TRY3
  'Type some numbers:'
  NUM ← ⎕
  'You have entered' (⍴NUM) 'numbers'
  'The biggest was' (⌈/ NUM)
  'The smallest was' (⌊/ NUM)
  'Sum of numbers is' (+/ NUM)
  'Integer average of numbers is' (⌊(+/ NUM)÷⍴NUM)
∇

You can check out the user-defined functions in your workspace with this command:

)FNS

There are some extra variables as well (check by using )VARS), so we need to erase them:

)ERASE TABLE X

Now we'll save the current workspace. First let's set the workspace ID to the filename where it should be salved.

Notice that we are using Unix notation and the XML extension. This is a requirement for GNU APL.

)WSID ./MyFirstWS.xml

Windows users, using NARS2000, should do something like:

)WSID 'c:\foo\MyFirstWS'

Now we use the command to save.

)SAVE

My result was:

2019-08-06  12:56:35 (GMT-3) ./MyFirstWS.xml

Now we can safely clear the workspace.

)CLEAR

To load the workspace again, use the load command with the file name.

)LOAD ./MyFirstWS.xml

NOTE: GNU APL instructs to use )COPY instead.

User functions can have no arguments, one argument or two arguments.

To do so, we need to rewrite the function to enable that. See this rewriting of AV.

∇R←AV X
  R←(+/ X)÷⍴X
∇

An example of usage:

¯3 + AV 3 8 1 4

The same can be done to dyadic functions.

∇R←A SUM B
  R←A+B
∇

Data is acquired by typing or from files. All data is held in arrays or scalars.

GNU APL supports complex numbers.

Formal names will be used from now on.

APL uses a modal interpreter. Calculator mode executes statements as entered. Definition mode does not execute immediately, and stores statements as a user-defined function or operator. Function execution mode happens when you run a user-defined function or operator.

APL has about 50 built-in functions which can be invoked by a single symbol.

Most functions can perform two different opperations depending on whether they're used with one or two arguments.

APL also has five built-in operators. Combining an operator with its operands creates a derived function.

Part of APL system, yet not part of APL language. Used to extend facilities provided by original APL, they vary from one vendor to another. Could also be tailored to the system which it is running.

System functions such as ⎕NREAD and ⎕NWRITE (with names starting with a Quad ⎕) read and write data from files, and are distinguishable from the rest by their starting character.

They are also not part of the APL language itself, but are crucial to managing the workspace. They always start with a ).

Functions or operators which can be written by the user. Consists of APL statements that have a name. Functions are edited through the function editor, which can also be used to tweak a function.

Files are usually not necessary on APL, given the convenience of workspaces, being only really required when dealing with big projects. When that time comes, APL has facilities for that; and workspaces can be shared between users.

APL provides facilities for error trapping and diagnostics.

Functions can take 0, 1 or 2 arguments; arguments to functions are always arrays.

Operators look like functions, but takes either one or two operands, which can be functions (e.g. the Each operator ¨). They can also be defined.

Classes are a collection of functions, operators and data (named properties). Acts as a template to create objects. Classes are supported in Dyalog, but not in GNU APL.

Some APLS allow changing the size of your workspace with )CLEAR 50MB, for example.

To check the amount of free space on your workspace, use the system function Workspace Available:

⎕WA

Here are some useful system variables which you may use.

• ⎕WA: Workspace Available. Number of available bytes for use in workspace.
• ⎕PP: Print Precision. Number of digits displayed in numeric output.
• ⎕PW: Print Width. Max number of characters in each printed line.
• ⎕LX: Latent Expression. This variable contains an expression or user-defined function which is executed when the workspace is loaded; effectively, a setup function for the current workspace. Empty by default.
• ⎕IO: Index Origin. Stores the value where indexes start. GNU APL starts at 1, but can be changed to 0.

These vary from vendor to vendor, so there is no guarantee that these will work in your APL. For example:

• ⎕NL: Name List. Produces a list of variables, functions, operators or classes.
• ⎕EX: Expunge. Expunges individual APL objects.

System functions are designed to be used in user-defined commands, whereas system commands are designed for direct usage.

Data can be directly quoted…

234.98×3409÷12.4

…or assigned to a name.

VAR ← 183.6

APL allows uppercase and lowercase characters, some APLs also allows symbols too.

Data can be numbers, characters or a mixture of those. GNU APL in particular also allows complex numbers; Dyalog allows classes.

From now on, unless there is something new, only some examples will be typed.

⍝ Scalars (no dimensions)
294
'A'

⍝ Vectors (one dimension -- length)
23 8 0 12 3
'ABC'
28 3 'A' 'BC'

⍝ 2D Matrices (two dimensions -- height and length)
⍝ There is no way to write a matrix literal.
4 4⍴7 45 2 89 16 15 10 21 8 0 13 99 83 19 4 27
4 2⍴'WILSO' 393 'ADAMS' 7183 'CAIRN' 87 'SAMSO' 8467

⍝ 3D Matrices (three dimensions)
3 3 4⍴36?100

Arrays are data structures of any dimension – obviously, scalars do not apply.

Useful for some things, for example flor predefined storage areas, where elements can be added.

X ← ⍳0   ⍝ X is a vector of zero elements
X        ⍝ Printing X gives an empty response
⍴X       ⍝ Asking for the shape of X gives a zero

This is fundamentally different than a scalar, which does not have zero elements: a scalar has zero dimensions instead.

⍴45

We can also create empty matrices. For example, a matrix of two rows and no columns:

TAB ← 3 0⍴⍳0
TAB
⍴TAB

General rule when applying an operation to data (e.g. a reduce /):

Unless specified otherwise, the operation takes place on the last dimension.

For example, consider a 3×4 matrix.

X ← 3 4⍴⍳12
+/ X

Applying a reduction to it yields a list of three elements. Each element of the list is the sum of a row. This is because a column is the last dimension of a 2D matrix (3 rows, 4 columns).

In other words, since we're performing the reduction on the last dimension (columns), then each result is the sum of all columns belonging to that row.

You can change that by using the axis ([]) operator:

+/[1] X

This carries the reduction on the first axis (rows), therefore the resulting list of four numbers is the sum of each column.

Now each result is the sum of all rows belonging to that column.

)CLEAR

There is something that remains to be discussed. Last section talked about the rows in index 1. This seems to mean that in APL indexes start at 1, but that might not be always true. This is true for GNU APL, to say the least.

If you wish to change indexing, just change the Index Origin system variable (this bit is not tangled):

⎕IO ← 0

From here on, we'll consider Index Origin to be 1.

Selecting elements is easy. Just use the brackets ([]), and separate variable indexes with ;.

⍝ Indexing in one dimension
X ← 1 45 6 3 9 33 6 0 1 22
X[4] + X[10]

⍝ Indexing in two dimensions
TABLE ← 3 3⍴9?100
TABLE[3;2]         ⍝ Indexing for more than one dimension

⍝ Indexing in three dimensions
DATA ← 4 4 4⍴64?100
DATA[2;1;4]

⍝ Selecting an entire row in tree ways
TABLE[1;1 2 3]
TABLE[1;⍳3]
TABLE[1;]

⍝ Selecting an entire column
TABLE[;2]

⍝ Selecting from anonymous data
(3 8 4)[1+2]

⍝ Selecting from an anonymous string, based on a variable
P ← 2
'ABCDE'[P]

Some useful stuff that has not been discussed yet:

Indexing can also be used to rearrange elements on a matrix!

'ABCDE'[4 5 1 4]

We can also do indexing with variables of a higher dimension. This pretty much collects stuff and stores it in the created shape:

'ABCDE'[2 2⍴4 5 1 4]

Indexing can also be done with the squad (⌷) symbol (notice that this is different from the quad ⎕, since it is narrower):

2⌷'ABCD'

)CLEAR

Most functions have two behaviours depending on how you place their arguments. For example:

⌈12.625         ⍝ Ceiling
2⌈8             ⍝ Select greatest number

÷1 2 3 4 5      ⍝ Reciprocal
100÷1 2 3 4 5   ⍝ Divide 100 by each

Expressions are evaluated from right to left. The results of one function become the argument of the next function.

Some functions work on numbers only. Some work on either numbers or text data. Using a function which does not work on a data type yields a DOMAIN ERROR.

Some functions also work only on a subset of the number domain, such as logical functions (∨, ∧ etc.) Thiis means that they only recognize the states of TRUTH (1) and FALSITY (0).

Some functions can be used only on data of a certain shape. The following example (not tangled) yields a LENGTH ERROR, because data on both sides do not have the same shape:

29 51 60 27÷3 11

Following there will be some examples of functions, which I'll store in tables as given in the tutorial, for further consulting.

Unless there is a new function with non-obvious usage, there will be some examples.

System functions exist to extend the power of APL, improving the usable tasks.

See the implementation documentation for that.

When used with functions as their operands, Slash and Backslash become Reduce (/) and Scan (\), which apply a single function to all elements of an argument.

⍝ These two operations are equivalent
22 + 93 + 4.6 + 10 + 3.3
+/22 93 4.6 10 3.3        ⍝ Reduce using plus

In the last example, Reduce interposes the + between the values on the vector. Were it replaced by the Scan operator, the same would happen, but the result would be a vector containing intermediate results; the last element of such vector would be the last result.

+\22 93 4.6 10 3.3        ⍝ Scan using plus
22 (22+93) (115+4.6) (119.6+10) (129.6+3.3) ⍝ Equivalent calculation

When used with one or more numbers, Slash and Backslash become Compression (/) and Expansion (\).

Compress selects a part of an object:

1 0 1 1 0 1 / 'ABCDEF'

Expand inserts fill data into objects:

TABLE ← 2 3⍴⍳6
⍝ Insert new columns (axis 2).
⍝ New columns indicated by zeroes.
1 0 1 0 1\[2]TABLE

Product operators distribute the application of a function between each element of one argument and all elements in another; this removes the constraint on applying certain functions to arguments of same shape.

The Each operator (¨) allows applying a certain function (on the left) to each elements of an array or vector (on the right).

⍴¨(⍳3)(⍳2)(⍳5)   ⍝ Find the length of each vector

Some functions operate in data which has more than one dimension. One can change the axis in which they operate by using the axis operator.

By default, APL functions work on the last dimension of your data. The order of dimensions is the one show when you apply ⍴ to the data.

TABLE ← 2 3⍴⍳6  ⍝ A matrix of 2×3 (two dimensions)

⍝ Reduce with + on the second dimension. This gives a
⍝ list of two numbers, each being the sum of numbers
⍝ along the COLUMNS (dimension 2, last one) of each
⍝ row of the matrix.
+/TABLE

⍝ This reduction specifies that the sum should occur
⍝ along the ROWS (dimension 1) of a column of the
⍝ matrix, therefore it gives a list of three numbers.
+/[1]TABLE

Functions can be thought of as external programs which are run. They can be:

• Niladic: They have no specified arguments.
• Monadic: Functions have one argument, passed at its right.
• Dyadic: Functions have two arguments, the first is passed at its left and the second is passed at its right.

Passing many values as an argument is enclosed into a single vector of arguments.

Definining a function that is both monadic and dyadic require testing the first and second arguments to dispatch based on it.

If you need to express a result, you will also need to give a name for the result field.

Operators must have one or two operands, which are functions; not more nor less, since operators are used to modify the behaviour of functions.

Some APLs allow you to edit a function by using the )EDIT command or the ⎕EDIT system function. This is the case for Dyalog, for example – however, Dyalog uses the )ED command instead.

)ED FUNK

Older APL systems, like GNU APL, allows editing one-line-at-time, using the Del (∇) editor. However, the gnu-apl-mode for Emacs replaces the use of Del by opening a new temporary buffer to edit the function.

∇FUNK

APL uses the concept of workspaces to store functions and values, however one can safely use the Del (∇) notation to define a certain function in an APL code file:

∇FUNK
  ⍝ Add some code here...
∇

The rest of this text will use the Del editor notation, in a way which it can be executed in a GNU APL script, therefore some things will be different e.g. line numbers will not be used here.

When typing the function, one must type a suitable function header, for example:

∇SD X
  SUM ← +/X
  AVG ← SUM÷⍴X
  DIFF ← AVG-X
  SQDIFF ← DIFF⋆2
  SQAVG ← (+/SQDIFF)÷⍴SQDIFF
  RESULT ← SQAVG⋆0.5
∇

This function takes a vector called X and performs some computation using it.

SD 12 45 20 68 92 108

The result exists in the global variable RESULT, created inside the function.

If we were defining a function with two operators, we would have a header such as:

∇X CALC Y

And if we wanted the result to be put in a specific variable, see how we could redefine SD:

∇R ← SD X
  SUM ← +/X
  AVG ← SUM÷⍴X
  DIFF ← AVG-X
  SQDIFF ← DIFF⋆2
  SQAVG ← (+/SQDIFF)÷⍴SQDIFF
  R ← SQAVG⋆0.5
∇

By doing this, the result of applying SD to something could be assigned to a variable; R itself is not a variable which is visible outside of SD, acting as a surrogate for the final result of execution.

Operator bodies are defined just like functions'; what changes is the header, which must specify an operator.

Here is the header of a monadic operator:

∇R ← X (LOP OPERATE) Y

And the header of a dyadic operator:

∇R ← X (LOP OPERATE ROP) Y

• OPERATE is the operator name;
• R is the optional return variable;
• X and Y are left and right parameters for the operator;
• LOP is an obligatory left operand, which the operator will change the behaviour of;
• ROP is an optional right operand, which the operator will also change the behaviour of.

One can quote variables in the header to make sure they are local to the function; by not doing so, they will remain global. Also notice that local variables are not shared with variables called inside the function body.

So let's fix SD.

)CLEAR   ⍝ Clear the workspace

∇R ← SD X;SUM;AVG;DIFF;SQDIFF;SQAVG
  SUM ← +/X
  AVG ← SUM÷⍴X
  DIFF ← AVG-X
  SQDIFF ← DIFF⋆2
  SQAVG ← (+/SQDIFF)÷⍴SQDIFF
  R ← SQAVG⋆0.5
∇

But the header is so big, that's not good. Let's try making this a little more compact so we have fewer local variables.

∇R ← SD X;SQDIFF
  SQDIFF ← (X-(+/X)÷⍴X)⋆2
  R ← ((+/SQDIFF)÷⍴SQDIFF)⋆0.5
∇

Inside the body of a function or operator, the symbol Goto (→) is used to determine a jump. The symbol should then be followed by some data; if the data is a scalar, the function jumps to the given line. If it is a vector, the function jumps to the first element of the vector and ignores the rest of it.

Here is an example of that in action, with numbering on the body for better understanding.

    ∇R←TEST X
[1]  →(X≥0)/4
[2]  R←0
[3]  →5
[4]  R←1
    ∇

The function starts by testing whether X is greater or equal to zero. If so, the result is 1, therefore the Compress (/) operator selects the sole number at the right, which is 4. The → symbol then instructs the function to jump to the line – that is, the fourth one.

Line [2] puts a 0 on the result variable. Then line [3] instructs the program to make an unconditional jump to the line 5, which does not exist – thus ending the function.

Line [4] attributes the number 1 to the result variable, and then exits gracefully, as there are no more jumps.

GNU APL has limited support for lambda expressions. Those are functions which are defined inline, and can even be named.

In lambdas, Alpha (⍺) is the symbol used for the left argument, and Omega (⍵) is the symbol used for the right argument. All lambdas are one-line functions, enclosed in Curly Brackets ({}), which can be monadic or dyadic depending on argument usage, and their single line always return a value.

AVERAGE ← {(+/⍵)÷⍴⍵}   ⍝ Named lambda
2 {⍺+⍵} 3              ⍝ Unnamed lambda, applied immediately

Here is an example lambda function which finds all the prime numbers below the second argument (⍵) of the monadic function (ACHARYA and PEREIRA):

PRIMES ← {(~⍵∊⍵∘.×⍵)/⍵←1↓⍳⍵}
PRIMES 100

APL prints errors when you type a statement containing an error in calculator mode. For example, this yields a DOMAIN ERROR:

1 1 0 'a'∨1 1 0 0

To correct an error in calculator mode, simply retype the statement correctly, or use the the implementation's line-editing facilities.

When executing a user-defined function or operator, if an error happens, the execution stops at that point. Modern APLs have a Debug window where you can examine and correct errors in the function or operator.

When the halted function was called by other function, one can inspect the call stack using the State Indicator. This can be done with the system function )SI or, in some APLs, by inspecting the variable ⎕SI.

Here is an example taken from implementation APLX (deprecated):

      )SI
C[2] *
B[8]
A[5]

In the example above, the problem happened at function C, at line 2. This function was called by function B at line 8, which was then called by function A on line 5.

The asterisk means that the execution of line 2 of function C is still pending. If another function were executed at this point and also yielded an error, this would happen:

E[3] *
D[6]
C[2] *
B[8]
A[5]

So now function E at line 3 is pendent, and was called from function D at line 6.

This top level can be cleared by using the Goto symbol (→). Another →, in this case, would clear the State Indicator completely.

      →
      )SI
C[2] *
B[8]
A[5]

There are also system functions to clear the State Indicator. In GNU APL, this can be done with )RESET.

One can resume the suspended execution where it stopped. To do so, just type Goto (→) followed by the line number.

→3   ⍝ Suppose execution halted at line 3 of the function

It is not mandatory to continue execution where the function halted. For example, suppose you want to restart at the next line:

→4

Another way to do this is by using the niladic system function ⎕LC. This yields a vector containing all current line numbers of functions in the State Indicator. All we need to do is to jump to the first number of such vector:

→⌷LC

Or, if we want to resume at the next line, we can also exploit the vector:

→1+⎕LC

It is possible to specify in advance what to do if an error occurs on execution; APL allows error trapping at runtime.

• Dyalog has the keywords :Trap, :EndTrap, :Case and :Else, and the system variable ⎕TRAP which allows precise control;
• APL2 has the system variables ⎕EA (Execute Alternate; executes the right argument and, if it fails, executes the left one) and ⌷EC (Execute Controlled; Executes the argument and returns the result, if any. Also returns additional information on errors).
• APL+Win has the keywords :Try, :Catch and :Finally; and the ⎕ELX system variable executes the argument passed on its right, whenever an error occurs.
• NARS2000 has ⎕ELX like APL+Win, and ⎕EA and ⌷EC, like APL2.

It seems like GNU APL does not have error trapping facilities.

Useful variable: ⎕PP (Print Precision).

When the left argument is not specified, the data is converted into plain text with no specific format, using only display defaults.

⍕ 0.0000003 3.0123456789

With two arguments, the left argument is always a list of two elements: Field width and number of decimal places.

6 2⍕341.82921

Note that, before the number was truncated, it was rounded.

Some APL implementations (except APL2 and GNU APL) have a ⎕FMT system function:

    'B K2 G< ZZ9 DOLLARS AND 99 CENTS>' ⎕FMT 8.23 12.86 0 2.52
 8 DOLLARS AND 23 CENTS
12 DOLLARS AND 86 CENTS
 2 DOLLARS AND 52 CENTS

Arrays have a type zero for numeric elements, and blank character for character elements.

⍝ Empty numeric vector and empty character vector
8⎕CR ⍳0 ◊ 8⎕CR ''

⍝ Same thing, but using ⍴
8⎕CR 0⍴676 ◊ 8⎕CR 0⍴'PETER'

┌⊖┐
│0│
└─┘
┌⊖┐
│ │
└─┘

Empty numeric vectors can also be created using Zilde (⍬).

X←⍬
⍴X
X≡0⍴0
8⎕CR ⍬

0
1
┌⊖┐
│0│
└─┘

Complex empty arrays can be created by using a nested array to generate the empty array:

⍝ A nested array containing a list of characters
⍝ and a list of numbers; the second statement
⍝ is an empty nested array containing another
⍝ empty array.
8⎕CR 'ABC' (⍳3) ◊ 8⎕CR 0⍴'ABC' (⍳3)

┌→────────────┐
│┌→──┐ ┌→────┐│
││ABC│ │1 2 3││
│└───┘ └─────┘│
└∊────────────┘
┌⊖────┐
│┌→──┐│
││   ││
│└───┘│
└∊────┘

When the first element is numeric, we end up with a nested array of null elements.

8⎕CR (2 2⍴⍳4) 'ABC' ◊ 8⎕CR 0⍴(2 2⍴⍳4) 'ABC'

┌→──────────┐
│┌→──┐ ┌→──┐│
│↓1 2│ │ABC││
││3 4│ └───┘│
│└───┘      │
└∊──────────┘
┌⊖────┐
│┌→──┐│
│↓0 0││
││0 0││
│└───┘│
└∊────┘

If the first element is mixed, then we'll have an array filled with zeroes and empty characters.

8⎕CR (2 2⍴1 'K' 2 'J') (⍳4) ◊ 8⎕CR 0⍴(2 2⍴1 'K' 2 'J') (⍳4)

┌→──────────────┐
│┌→──┐ ┌→──────┐│
│↓1 K│ │1 2 3 4││
││2 J│ └───────┘│
│└───┘          │
└∊──────────────┘
┌⊖────┐
│┌→──┐│
│↓0  ││
││0  ││
│└───┘│
└∊────┘

Therefore, the prototype concept can be used to display the type of an array.

8⎕CR VAR ← (2 2⍴1 'A' 'B' 2) ((⍳2) 7) 'ABC'

┌→────────────────────┐
│┌→──┐ ┌→──────┐ ┌→──┐│
│↓1 A│ │┌→──┐ 7│ │ABC││
││B 2│ ││1 2│  │ └───┘│
│└───┘ │└───┘  │      │
│      └∊──────┘      │
└∊∊───────────────────┘

To display the array type, we first enclose (⊂) the array to make it a scalar, then we build the empty vector with it (0⍴). Since building the empty vector creates an additional level of nesting, we use the First (↑) function to remove it:

8⎕CR ↑0⍴⊂VAR

┌→────────────────────┐
│┌→──┐ ┌→──────┐ ┌→──┐│
│↓0  │ │┌→──┐ 0│ │   ││
││  0│ ││0 0│  │ └───┘│
│└───┘ │└───┘  │      │
│      └∊──────┘      │
└∊∊───────────────────┘

Functions such as Take (↑), Expand (\) and Replicate (/) add elements to an existing array. A prototype can be used to determine the type and shape of extra elements.

Here are some examples.

8⎕CR 5↑1 2 3 ◊ 8⎕CR 5↑'ABC' ⍝ Numeric and textual vectors of 5 elts
8⎕CR 2↑0⍴⊂VAR   ⍝ Vector containing two prototypes
8⎕CR 2↑⊂VAR     ⍝ Put VAR's prototype after VAR, in a vector
8⎕CR ¯2↑⊂VAR    ⍝ Put VAR's prototype before VAR, in a vector

┌→────────┐
│1 2 3 0 0│
└─────────┘
┌→────┐
│ABC  │
└─────┘
┌→──────────────────────────────────────────────┐
│┌→────────────────────┐ ┌→────────────────────┐│
││┌→──┐ ┌→──────┐ ┌→──┐│ │┌→──┐ ┌→──────┐ ┌→──┐││
││↓0  │ │┌→──┐ 0│ │   ││ │↓0  │ │┌→──┐ 0│ │   │││
│││  0│ ││0 0│  │ └───┘│ ││  0│ ││0 0│  │ └───┘││
││└───┘ │└───┘  │      │ │└───┘ │└───┘  │      ││
││      └∊──────┘      │ │      └∊──────┘      ││
│└∊∊───────────────────┘ └∊∊───────────────────┘│
└∊∊∊────────────────────────────────────────────┘
┌→──────────────────────────────────────────────┐
│┌→────────────────────┐ ┌→────────────────────┐│
││┌→──┐ ┌→──────┐ ┌→──┐│ │┌→──┐ ┌→──────┐ ┌→──┐││
││↓1 A│ │┌→──┐ 7│ │ABC││ │↓0  │ │┌→──┐ 0│ │   │││
│││B 2│ ││1 2│  │ └───┘│ ││  0│ ││0 0│  │ └───┘││
││└───┘ │└───┘  │      │ │└───┘ │└───┘  │      ││
││      └∊──────┘      │ │      └∊──────┘      ││
│└∊∊───────────────────┘ └∊∊───────────────────┘│
└∊∊∊────────────────────────────────────────────┘
┌→──────────────────────────────────────────────┐
│┌→────────────────────┐ ┌→────────────────────┐│
││┌→──┐ ┌→──────┐ ┌→──┐│ │┌→──┐ ┌→──────┐ ┌→──┐││
││↓0  │ │┌→──┐ 0│ │   ││ │↓1 A│ │┌→──┐ 7│ │ABC│││
│││  0│ ││0 0│  │ └───┘│ ││B 2│ ││1 2│  │ └───┘││
││└───┘ │└───┘  │      │ │└───┘ │└───┘  │      ││
││      └∊──────┘      │ │      └∊──────┘      ││
│└∊∊───────────────────┘ └∊∊───────────────────┘│
└∊∊∊────────────────────────────────────────────┘

More info: Empty Arrays and Prototypes