The Kap Turbo Tutorial

Kap is a programming language where most programs are executed directly on the REPL, as opposed to being typed into a file and run. The goal is to allow the user to easily perform computations without having to write a full program, with all the extra work that entails.

The best comparison is with the Unix shell. While a shell like Bash is a full programming language, the majority of Bash code are commands written by the user at the prompt. Sometimes these commands can be quite complex, and solve very complicated problems. And once the command is typed, the code is no longer needed, so it scrolls off the screen (perhaps accessible in the command history).

Kap aims for a similar type of usage. The language is so concise and powerful that it allows users to solve, directly in the REPL, problems that would require tens, if not hundreds of lines of code in other languages.

However, Kap is not magic, and it requires the user to approach problems in a different way, thinking about data in terms of arrays with a shape that operations are performed on, rather that sequences to be iterated over. It can be both challenging and fun, and it can be worth the effort to learn the language.

Please visit the Matrix room where any questions about the language and how it’s used will be happily answered.

To provide feedback on this tutorial, either go to the Matrix room, or report an issue on Codeberg.

In the examples below, input is indented by 4 spaces, and output immediately following the input:

At the REPL, after executing an expression, the return value is printed in a way that is useful for human consumption.

Kap uses non-ASCII characters for some operations. When introduced, the keys to type to obtain these symbols are stated in the text.

The easiest way to follow along is to use the web-based REPL, which is implemented in Javascript. Other versions are available on the download site.

Numbers return themselves:

From the last example, we can see that there is no limitation to the size of an integer. Internally, integers that fit in 64 bits will be stored as such, while larger numbers use bigints. This is completely transparent to the user, except for performance differences.

Negative numbers use ¯ (input: `, 2). This is to distinguish it from - which is a regular function.

Note that the ¯ symbol is part of the number, and not a function. Note the difference between the following two expressions. In the first case, the two numbers negative-1 and 2 form an array. In the latter case, the two numbers 1 and 2 form an array which is passed to the function - which negates the members.

When printed, negative numbers are displayed using -, since this makes it more convenient when copy&pasting to other tools.

If a number contains a ., it’s a floating point number. These follow standard IEEE-754 64-bit semantics:

From the above, we can see that 0 and 0.0 are two different numbers, one being an integer and the other a floating point number.

Rational numbers are given by separating the numerator and denominator using the character r:

Integers are also rational numbers, and dividing two rational numbers will yield a rational. This avoids a lot of precision problems inherent in the use of floating point, at the cost of performance. It is always possible to force the use of floating point calculations by using floating point numbers instead of rationals.

Complex numbers are specified using the letter j between the real and imaginary parts:

Characters are 32-bit Unicode codepoints and specified using @, followed by the character, or a backslash and a code description as follows:

Examples:

All arrays have a dimensionality, or “rank” as it is often referred to. Arrays in most languages are 1-dimensional, meaning that values in the array are addressed using a single number. When creating an array using the syntax described in the previous section, the result is a 1-dimensional array.

Rank-0 arrays

A rank-0 array contains a single value:

All scalar values such as numbers or characters can be seen as rank-0 arrays.

Rank-1 arrays

Rank-1 arrays are often referred to as vectors, and are the default type of arrays in almost all programming languages. Elements are referenced using a single index:

Rank-2 arrays

A 2-dimensional array is similar to a spreadsheet, and have elements that are indexed using two numbers:

Rank-3 arrays

One can think of 3-dimensional arrays as a stack of 2-dimensional arrays, where the first index indicates the sheet, the second the row and the third is the column:

Rank-4 arrays

A 4-dimensional array can be thought of as multiple stacks of sheets. One needs 4 numbers to find a given cell, with the first number being the stack and the remaining three numbers as per the rank-3 array.

Kap supports arrays with a large number of dimensions (the exact number is 2³¹-1), but in practice it’s rare to work with arrays with more than 4 dimensions. The principles that are illustrated in the previous paragraphs extend naturally to any number of dimensions.

Not counting the 0-dimensional array which is just a scalar value, the simplest form of an array is the 1-dimensional array. They are written by separating values by space. Note how arrays are displayed by drawing a box around them:

There are many ways to access individual elements of an array. The square bracket syntax is probably the most familiar to users of other languages:

The value inside the square brackets can also be an array, with the result being a new array which is the selection based on that array:

There is nothing stopping you from repeating indexes:

As mentioned in the summary above, in most programming languages, arrays can only have a single dimensions. I.e. elements are dereferenced using a single index. Kap arrays can have any number of dimensions. To help creating arrays with more dimensions, the function ⍴ (type: `, r) is used. This function is referred to as “reshape”, and takes the desired dimensionality on the left, and a value to be reshaped on the right:

The result is an array with 2 rows and 3 columns. If the size of the right argument is too small, it will simply loop around and start taking values from the beginning of the input. If the array is too large, any extra elements will simply be dropped:

This behaviour can be leveraged in various ways, for example by creating a checkerboard pattern (assuming the number of columns is odd):

If ⍴ is called monadically (i.e. with just a single argument to the right), it will return an array of numbers representing the dimensionality of the argument:

Getting values from a multi-dimensional array using square brackets can be done by separating the dimensions using ;:

The indexes at a given axis does not have to be a scalar number, it can also be an array, in which case all the given indexes are used. The following gets the second, then then first row of the second column:

If an axis is left blank, all elements along that axis are picked. The following gets all elements on the last row:

All values in Kap are arrays. However, some of them does not have any dimensions. I.e. they are scalar values. When calling ⍴ on a scalar, it returns an empty array, which is represented by ⍬:

Note how we never mentioned strings in the explanation of value types above. This is because a string in Kap is simply a 1-dimensional array where all values are characters. Strings can be entered by enclosing them in double-quotes, or they can be created using any other method that creates arrays:

Since an array can contain elements of any type, it’s possible for an array to contain other arrays. Here is a simple example:

Note: At this point it is important to note a possibly unexpected behaviour when looking up individual elements using bracket notation:

The extra box around the result is because the value is “enclosed” to ensure that the result is scalar. This is explained in the chapter Enclosing data. For now, we can ignore this and instead use “period notation” which can be used when looking up a single value in a container object:

Period notation is also useful when dereferencing values in a deeply nested object:

Calling the function , monadically will create a 1-dimensional array with the same number of elements as the original array:

The function ⍪ can be called monadically in which case it’s referred to as “table”. It converts a one-dimensional array into a 2-dimensional array with a single column:

The operator comes after the function on which it acts:

When applied to a multi-dimensional array, / acts on the last axis:

Using ⌿ (type: `, /), acts on the first axis:

It is also possible to specify an axis parameter to choose precisely which axis to reduce over:

The outer product operator, ⌻ (type: `, K) creates a permutation matrix with the result of the function applied to all combinations of the input arguments. For example, it can be used to create a multiplication table:

The operator ¨ (type: `, 1) is called “each”, and applies the function on each element in the input array. This is very similar to the “map” function in most functional languages:

Another useful operator is commute/duplicate, ⍨ (type: `, T) which has two uses. When the derived function is called dyadically, it calls the original function with the two arguments swapped:

When called monadically, it calls the functional dyadically with the same argument on the left and right:

Using this operator, the multiplication table above can be written very concisely. It’s left as a small exercise for the reader.

Inline functions are defined using { and }. The entire expression acts as any other function and when called, the variables ⍵ (type: `, w) and ⍺ (type: `, w) contains the values of the left and right arguments.

A local function is created using ⇐ (type: `, U). The left side of the assignment is the name of the function, and the right side is a function, written as it is called in code. The following creates an alias for the function - called minus:

This method is also the way to give a name to a lambda expression:

Global functions are declared using ∇. We’re not going to need those for now, but for anyone interested, more information can be found about it in the reference documentation.

Aside from the mathematical functions mentioned above, there are plenty of others:

Problem: Given a list of numbers, we want to multiply all values above 5 by 10, and leave the remaining numbers as they are.

For the purposes of the below examples, the values are available in the variable nums:

Problem: You have an array of names of people in names, and an array of their ages in ages. Get a list of the names whose age is greater or equal to 20:

The transpose function ⍉ (type: `, ^) is used to reverse the axes of an array. For 2-dimensional arrays, this means that the rows becomes the columns and vice versa:

The ⍉ function can also be called dyadically, in which case it allows the user to specify precisely which axis is moved where. More information about this can be found in the reference.

Note that in Kap, along with the majority of functions that change the shape of the content, transposition does not result in a new array being allocated. Instead, it simply changes the way that the positions of values in the array is calculated.

The functions ⊖ (type: `, 7) and ⌽ (type: `, 5) are used to reflect and rotate arrays.

The enclose function ⊂ (type: `, z) is used to create nested arrays from non-nested data. In its simplest form, it creates a scalar (zero-dimensional) value from an array:

Since scalar functions (such as +) acts on scalar values by replicating them to each value in the other argument, one can do the following:

The content of an enclosed value can be recovered using the disclose function ⊃ (type: `, x):

Given a nested array, the disclose function can be used to turn each element in an array into a new axis in a new array which will have one more dimension than the original. Example:

To perform the opposite of the disclose function above, one uses enclose, but with an axis argument:

Of course, another axis can also be used:

When called dyadically, ↑ takes a given number of elements from an array, and removes the rest. If the number is negative, it takes elements from the end of the axis.

Take the first 3 elements:

Take the last 4 elements:

From the first row, take the two first columns:

Instead of a count, null can be used to specify that you want all the elements alogn an axis. Take the first 2 columns of all the rows:

When taking more than the available number of elements, by default 0 is used to fill in the missing values:

Drop works similar to take, except that the numbers specify the number of cells to remove, as opposed to the number of cells to keep.

Drop the first row and the last 4 columns:

The function ⊇ (type: `, X) is called “pick” and it used to select elements from an array by specifying its coordinates.

A simple case with a 1-dimensional array:

If the array is multi-dimensional, each element is selected using an array of values the same length as the dimensionality of the array. For example, if the array is 3-dimensional, a cell specification consists of a 3-element array:

Note: if the array is multi-dimensional and one only wants to retrieve a single value, this value must be enclosed. In the example below, if the numbers (1 2) had not been enclosed, ⊇ would think that 2 elements from a 1-dimensional array was requested. This would not match the actual array, so an error will be raised.

Without the enclose:

To load a text file into an array, where each row is a string, use io:read. Let’s assume there is a text file called abcd.txt containing the following content:

Then, the content can be read like so:

For this example, assume the file report.csv contains the following content:

Loading the data results in the following:

CSV is a fairly underspecified data format, and there is no type information included in it. Also, the headers are just cells like any other.

The function labels assigns labels to an axis, which is very useful when working with the data. The following expression takes the first row and uses it as headers for the remaining rows:

We can also convert the third column into a numeric value using the function ⍎ (type: `, ;):

What we did above was to take the last column, convert all the cells to numbers, and then concatenate back all but the last column. This is obviously a bit cumbersome, so to avoid this, the operator ⍢ (type: `, G) can be used. This operator calls the function to the right, then applies the function on the left to the result, and then reverses the action that the first function produced. In this particular case, it puts back the columns that were previously removed:

The JVM version of Kap provides functions to load and save data to/from spreadsheets. Currently OpenDocument and Excel formats are supported. This is done using the functions libreoffice:read/libreoffice:write and msoffice:read/msoffice:write.

The read functions are monadic and accepts a filename as its argument. The first sheet in the file is loaded and converted to a Kap array. The write functions are dyadic, and accepts a filename as the left argument and the data to write as the right argument.

These functions are not available in the native or Javascript versions of Kap. However, it is possible to load Excel data into the web version via the UI. Click on the sidebar to load the file.

The function ∊ (type: `, e) takes an array on the left, and for each element in that array, check if the element exists in the right argument. The result is an array of the same shape as the left argument, where each cell is a 1 or 0 depending on whether the value was found or not.

One way this function can be used is to create a selection mask. The following filters out any characters not in validChars:

Some special variables and functions with names starting with a ⎕ (type: `, l) provide useful shortcuts to commonly used features. ⎕a is a list of the lower case ASCII letters a-z, ⎕A is an array of the uppercase letters A-Z and ⎕d is the decimal digits 0-9.

If we want to do the opposite, simply negate the mask before selecting:

The dyadic version of ⍳ is used to determine where in an array a certain value is located.

In the first example, the value 20 was found at the second location in the left argument, so the index 1 is returned.

In the second example, the value is not found, so the first index after the last argument is returned.

Another way to think about the behaviour of dyadic ⍳ is as way to map a list of values into an alphabet:

In the example above, we’re using the … (type: `, m) function, called “range” to generate the sequence of hex digits. See reference for details.

The ⍷ function (type: `, E) is used to find subsequences in an array. The left argument is the value to search for, and the right argument is the array to search. It returns a bitmap where the value was found:

One can also search for subarrays of higher dimension:

Overlapping results are handled correctly:

The ⍷ function is also used to check if array starts with a specific sequence:

Note that thanks to the use of lazy evaluation, this is O(1) with respect to the length of the string being searched.

A split happens if the value is greater than the previous value. If the value is 0 the element is skipped.

Split by increasing values:

As can be seen, a decreasing value will not cause a split.

Here’s an example of skipping elements:

This behaviour makes this function very useful when one has a bitmask with the groups that needs to be split. One example of such case is if you want to split a string by space:

In the above example, the expression ⍵≠@\s returns a bitmask where any character is not a space:

This bitmask is the perfect input to ⊂.

What if we want to split on several characters? Let’s say we want to split on space, period and comma. We can take advantage of the function ∊ discussed above, and do it this way:

The function partitioned enclose is very similar to partition, but here the array is split wherever the value is 1: