Kap reference

Since all code is parsed prior to evaluation, the Kap parser needs to know if a symbol refers to a function or a value at the time of parsing. This means that in contrast to APL, the roles of a symbol cannot change during evaluation. The normal way to deal with this is to ensure that a function is declared before the point in the code where the function is called.

This presents a problem when two functions needs to call each other. At this point, forward declarations needs to be used.

At present, Kap does not have a dedicated syntax for forward declarations. Instead, one defines a function that will never be called for the purpose of ensuring that the symbol is defined as a function. After defining the function calling this function, it can be redeclared with its correct definition.

Kap supports the following datatypes:

Strings are single-dimensional arrays of characters, enclosed in double-quotes: "foo test".

The following escape codes are allowed in a string:

N-tuples, also simply called “lists”, are primitive values that act as a container of zero or more values. The explicit list syntax uses ; to separate the elements. List parsing has lower precedence than boolean operations as well as regular lists and function calls, which means that they usually have to be enclosed in parentheses.

1;2;3;4 — A list consisting of 4 elements.
1 + 2 ; 3 + 4 ; 5 — a list consisting of the three values: 3, 7, and 5.

Note that the above syntax can only create N-tuples of length 2 or more. To create N-tuples of length 0 or 1, use the function ≬.

The value null is an atomic value which can be used to represent the absence of a value. Its datatype is kap:null, which has only a single instance.

The names and and or are short-circuiting functions that act on the arguments true/false property. For the purposes of these functions, the numeric value 0 is considered false, and any other value is true.

io:println 2 and io:println 3 — Evaluates to 3, and will print both 2 and 3.
io:println 1 or io:println 0 — Evaluates to 1, and will not print 0.

Note that and and or has higher precedence than lists, but lower than regular arrays and function calls.

If a line ends with a backquote `, the subsequent newline is treated as whitespace. This allows for statements to be broken up into multiple lines.

Symbols are used to name objects in Kap. The name of a symbol consists of one or more non-space Unicode characters. Some examples include:

All symbols belong to a namespace. A namespace is a grouping of symbols. When parsing a symbol, the namespace can be explicitly specified by prefixing the symbol name with the namespace name, separated by a :. Examples:

If the namespace is blank, it is assumed to be keyword. Any symbol in the keyword namespace acts as a variable that returns the symbol itself.

When looking up a symbol without a namespace, the symbol is searched in the following order:

A symbol can be marked as “single character”, in which case it will always parse as a single symbol. For example, the symbol ÷ is a single character symbol. Because of this, the sequence ÷÷ are two separate symbols, instead of a single symbol consisting of two characters.

The declaration :singleCharExported can be used to declare a symbol to be single character. See :singleCharExported for details.

The ⍝ character indicates the start of a comment. Everything until the next newline will be ignored.

The symbol ∇ is used to define global functions. The general form is:

The last evaluated form in body is returned from the function.

The header has the following possible forms:

When declaring an operator, the function arguments are passed as function objects, and needs to be applied using the function application operation: ⍞.

To declare a monadic function that returns the argument + 1:

To declare an operator that adds 100 to the result of evaluating the function after adding 1 to the argument:

The symbol ⇐ is used to declare lexically scoped local functions. It has the following general form:

Where fn can be any function as it appears in an expression. This includes:

The declared function has the normal lexical scope, which is the same as any variable declared in the same scope. Local functions also has access to any variables visible within its scope.

The λ symbol is used to create a function reference from a function. The syntax is: λ fn where fn is any function as it appears in an expression.

The return value is a primitive value which behaves just like any primitive. It can be passed to other functions, and be members of arrays.

When creating a function reference, the function captures any lexical bindings references from within the function. These bindings remain valid even after the scope is exited.

To call a function from a function reference, use the apply symbol: ⍞. Please see the documentation for this symbol for more information.

The ⍞ is used to call a function given its function reference. It can take any of the following forms:

Modified assignment are specified using a ← in a position where an operator would be allowed. I.e. after a function call. A modified assignment has the following form:

Where F can be any function call, including explicit named functions, dfns or tacit expressions. The modified assignment expression is evaluated as follows:

Note that any side effects when evaluating Lvalue will only be executed once.

Format: use("filename")

When the parser sees a use statement, the file is looked up and loaded as a separate parse unit. Any changes to the default namespace made while processing the file will be reverted once parsing of the file is complete.

Format: import("namespace")

This statement makes all exported symbols from namespace visible in the current namespace without the need to specify the namespace explicitly.

Format: namespace("namespace")

Set namespace as the default namespace for this parse unit.

The declare statement is used to control various aspects of symbols.

An array can be followed by an index within square brackets. An index is specified as an n-tuple of the same size as the number of dimensions in the value. Each value in the index specification indicates which values along the corresponding axis to retrieve.

For example, to retrieve a scalar value from a 1-dimensional array:

To retrieve specific elements:

To retrieve a scalar value from a 2-dimensional array:

To retrieve an entire row:

To retrieve a subarray:

The dimensions of the result always match the combined dimensions of the index arguments. A consequence of this is that when reading a single element from a nested array, the result is enclosed:

Use the ⊃ function to retrieve the enclosed array.

In most places where array positions are specified using an integer index, a negative value can be used to index from the end of the given axis, where ¯1 refers to the last element, and -≢A refers to the first element.

The . symbol can be used to dereference an element in a hashmap or an array.

The symbol used in not an operator or a function but rather a syntactic element which ensures evaluation from left-to-right. This makes the feature particularly useful for resolving elements in tree structures, such as the form returned after parsing JSON data.

Assuming the file file contains the following JSON content:

And then running the following code:

After this, the variable a will contain the value "test".

The different forms allowed in array dereferencing are explained below:

This variable contains the following string: "abcdefghijklmnopqrstuvwxyz"

This variable contains the following string: "ABCDEFGHIJKLMNOPQRSTUVWXYZ"

This variable contains the following string: "0123456789"

This variable contains an array of strings representing the arguments given to the interpreter when it was started.

Monadic Transpose reverses the axes of the right argument. When applied to a 2-dimensional array, the result is its transpose. Scalar and 1-dimensional arguments are unaffected. ^[1]

Compatibility note: APL supports repeated axis in the left argument. This is not supported in Kap.

APLWiki Transpose

Both arguments can be arrays of any shape. The entire left argument is tested against each position in the right argument. The result is a boolean array having the same shape as the right argument, where a 1 indicates the position of the first element of the matched subarray (which can be seen as the "leftmost" or "top left" position in case of a vector or matrix). If the left argument has lower rank, it is treated as if the shape is prepended with ones. If the left argument has higher rank, Find does not error, but it is never found in the right argument (resulting in an all-zero array). ^[1]

APLWiki Find

Grade up returns a permutation vector whose length equals the number of major cells, so that indexing into the argument gives the sorted array. The resulting array is sorted in increasing order.

Grade performs stable sorting, so that the indices of the repeated major cells are sorted by the order of appearance. Because of this, Grade Down produces the reverse of Grade Up only if all the major cells are unique. ^[1]

APLWiki Grade

This function performs the same operation as ⍋ except that the array is sorted in decreasing order.

APLWiki Grade

The replicate function copies each element of the right argument a given number of times, ordering the copies along the last axis by default. If provided, the axis argument specifies along which axis the operation should be performed. Replicate is a widely-accepted extension of the function Compress, which requires the number of copies to be Boolean: each element is either retained (1 copy) or discarded (0 copies). Replicate with a Boolean left argument or operand may still be called “Compress”. ^[1]

https://aplwiki.com/wiki/Replicate

This function is the same as /, except that it performs the operation along axis 0.

A must be an array of coordinates specifying values in B. Each coordinate must be an array with the same size as the rank of B (they may also be scalar, if B is 1-dimensional). The result is an array with the same dimension as A containing the specified values in B.

APLWiki From

Encode computes the representation of the right argument in the radix system defined by the left argument. Encode is the inverse of Decode ⊥ with the same left argument A, when A is a 1-dimensional array. ^[1]

If the left argument is a scalar integer, the result will be computed as if that value was repeated to the required length to fit the entire value.

APLWiki Encode

Decode evaluates the right argument in terms of the radix system defined by the left argument. Decode is the inverse of Encode ⊤ with the same left argument A, when A is a vector and the right argument is a valid representation of a number in the radix system defined by A. ^[1]

APLWiki Decode

Returns the intersection of A and B. The result is an array of all elements that are present in both arrays.

APLWiki Intersection

The Key function is used to group a set of values based on some set of keys.

A is an array containing keys, and B is an array of the same size that holds the values. The result is an n-by-2 array where n is the number of unique keys. For each row, column 0 contains the key, and column 1 contains an array of all values with the corresponding key. Example:

Create an N-tuple. The function returns an N-tuple containing the elements of the input array.

The labels function is used to programmatically manage the axis labels for a given array. Once assigned, the labels will be preserved by certain functions that preserve the general structure of an array. Such functions include take, drop, reverse, etc. The idea is that the axes in the return value for these functions can be interpreted to be the same as the ones in the input.

Axis labels are used by the charting functions to label values. They are also used by the array editor to display the names of the columns and rows.

Collapses a possibly lazy array and evaluates all values. The return values are guaranteed to be a self-contained array with no references held to any other objects. Reading from this array will not cause concurrency issues.

This function is used to close any stateful object. The main such object is the SQL connection objects and SQL prepared statements.

NOTE: The syntax for this operator is not fixed, and may change syntax in the future, if a nicer syntax is suggested.

This is a monadic operator that derives a monadic function. When called, this function will register the operator argument to be called once execution leaves the current scope. Example:

This will print the following:

This operator is typically used when using resource objects that needs to be closed when completed. For example, to ensure that SQL connections are closed, use the following:

The given function is applied to the arguments and returns an array of the same shape as the input.

Assuming F is a function:

F¨ 1 2 3 is equivalent to (F 1) (F 2) (F 3)

10 20 30 F¨ 1 2 3 is equivalent to: (10 F 1) (20 F 2) (30 F 3).

Lazy behaviour: The result of ¨ is a lazy array. The function will only be called when the underlying value is retrieved. Note that the result is not cached, so if a result is retrieved more than once, the function will be called once for each time the value is read. If multiple reads are expected it is recommended to collapse the array prior to reading it.

Format: x F⌻ y where F is a dyadic function.

This operator derives a dyadic function that returns an array consisting of all combinations of the elements of the last axis of x with the elements of the leading axis of y.

For one-dimensional arrays, this corresponds to a table mapping each element of x to each element of y:

The Kap implementation of inner product is compatible with that of APL, with the difference being that the middle dot symbol is used instead of a period.

APLWiki Inner product

A call to the power operator is of the form A (f⍣g) B, where

The power operator repeatedly applies f to Y based on the type of operand g:

APLWiki Power (operator)

The scan operator is similar to reduce, with the difference that the intermediary results are preserved.

Compatibility note: Like the reduce operator, the calculation is performed left-to-right, accumulating the result from each function invocation in order. This behaviour is different from APL which defines scan as a right-to-left reduce on each prefix. The Kap implementation is similar to that of BQN and J.

APLWiki Scan

This operator is the same as scan, except that it scans along the first axis by default.

APLWiki Scan

The right operand specifies the rank of subarrays to which the left operand function is applied as follows: For left argument ⍺ and right argument ⍵,

A non-negative right operand specifies the number of final axes to which the function applies. A negative right operand specifies complementary rank, i.e. the number of leading axes to be excluded. Negative rank can also be thought of as rank specification relative to the overall rank of the argument array. ^[1]

APLWiki Rank (operator)

Derives a version of the underlying function which performs its operation on the individual bits of an integer. The following bitwise operations are implemented:

Example:

5 +∵ 3 ⇒ 6

The parallel operator derives a new function that performs a parallel version of the function it is applied to. The exact behaviour of the derived function depends on the specific underlying function.

Currently, this operator can only be applied to ¨ (each). In this case, the result is computed split into separate tasks that are executed in parallel. The number of tasks run in parallel is equal to the number of CPU cores on the system.

Example:

Note: The function that is called must be pure. I.e. it must not have any side effects. If the function has side effects, unpredictable results may be seen.

Derives the functional inverse of the argument function. Generally, the inverse of a function is a function that satisfies the following: F F˝ x = x. For dyadic invocations, the equivalence is: x F x F˝ y = y.

In plain language, the call F˝ x can be seen as answering the question: “what value z can I pass to F such that F z returns x?” Likewise, the dyadic call x F˝ y can be seen as answering the question: “what value z can I pass to x F z that will return y?”

The equivalence rule explained above is not strictly adhered to, but rather the implementations of the inverse functions are driven by practicality. If a specific inverse makes more practical sense, then that is implemented even if the implementation isn’t a strict inverse.

10×˝2.0 ⇒ 0.2

This operator derives a function which, when called, checks if the right argument is null. If it is, returns null. Otherwise calls the original function with the arguments as passed to the derived function. This is useful when looking up values in hashmaps.

The over operator derives a function which, when called dyadically, calls the right function on both arguments individually and then calls the left function on the results. In other words, this operator can be thought of processing the arguments using A before acting on it using B.

The structural under operator takes two functions: When called as A⍢B x, the function B is first called on x, and the return value is passed to A. The effect of B is then reversed.

For inversible scalar functions B, the reverse is simply a call to the inverse of B. However, some other functions can be used that are not normally inversible. An example:

The above operation represents the addition of 10 after taking the first two rows of the array. After the addition, the original removed rows are put back.

The fork is specified using « and ». It has the following form:

A sequence of two functions next to each other are executed in the same manner as a train in APL:

Because Kap uses explicit syntax for forks, this expands to any number of functions in a train. In other words:

A left-bound function derives a monadic function from a dyadic function by assigning a constant to the left argument. For example, 2+ is a derived function that adds 2 to its argument. This functionality is particularly useful in trains. The following is a function that divides the argument by 2 and then adds 1: 1+2÷⍨. Example:

This is a scalar function which, for each numeric value, returns the real part of a complex number.

This is a scalar function which, for each numeric value, returns the imaginary part of a complex number.

Returns an array of all primes up to A.

This is a monadic scalar function which returns a boolean value indicating whether the value is prime.

The left argument is a map, the right argument is array of key/value pairs as per map:with. For each key, the associated value is looked up. If the value exists and is a list, the new value is appended to the existing values. If it does not exist, it is added as a single-element list.

If the value exists, but is a scalar, the new value is concatenated with the old value. However, this should probably be seen as an error and may throw an exception in later versions.

This function is called dyadically with A being the map and B being the key. The corresponding value is returned, or ⍬ if the key was not found in the map.

Regular bracket indexing works on maps, and is equivalent to a call to map:get:

This function removes keys from a map. A is the map to update, and B is an array consisting of a list of keys to remove. This function returns the updated map.

This function is called monadically with a map as argument. It returns a two-dimensional array with two columns, where the first column is the keys and the second column the values.

This function is called monadically with a map as its argument. It returns the number of elements in the map.

Format: if (expression) { thenStatement }

Evaluate expression. If true, evaluate thenStatement and return the result of its last form. Otherwise, return ⍬.

Format: if (expression) { thenStatement } else { elseStatement }

Evaluate expression. If true, evaluate thenStatement and return the result of its last form. Otherwise, evaluate elseStatement and return the result of its last form.

The when statement is used as an alternative to series of if and else. The following sets a to be the value of some variable, or returns a message if all conditions failed.

Format: while (expression) { body }

The while statement evaluates the body as long as expression is true.

Exceptions are thrown using throw. Exception have a type, represented by a symbol and some associated data. The following example throws an exception of type :foo with data "test":

When called monadically, throw will throw an exception of type :error.

The catch operator is used to perform some processing when an exception is thrown. It has the following form: F catch x.

x must be either a one-dimensional array with an even number of elements, or a two-dimensional array with 2 columns. The content must be pairs of values, where each pair is a tag, followed by a function reference.

The derived function first calls F with ⍬ as argument. If the invocation of F does not throw an exception, its return value is returned. If an exception was thrown, the tag is looked up in x, and if found, the corresponding function is called, with the left argument being the data that was passed to the throw call, and the right argument being the tag. The return value from the handler is then returned.

Format: io:read name

Read the content of the file name and return the lines in the file as an array of strings.

Format: io:print value

Prints value to standard output.

Format: io:readdir path, format io:readdir path

When called monadically, this function assumes the left argument is an empty array.

This function loads the contents of the directory at path, and returns a 2-dimensional array of results. The first column is always the name of the directory entry, with the remaining columns decided by the format argument.

The format is a list of specifiers indicating what information should be included. Currently, the following formats are supported:

This function accepts either one or two arguments. The first argument is always a string, indicating a file to be read. The second argument, if provided, is a list of keyword arguments. The following keywords are available:

This is a dyadic function where the left argument is a filename and the right argument is a 2-dimensional array. The content of the array will be encoded into a CSV file and written to the given file.

The first argument is a file name that specifies which file to open. The optional second argument is a list of keywords that indicate how the file is to be opened. The following flags are accepted:

The default option is :input.

The resulting stream must be closed after being used. See close for more information.

This function reads binary data from a stream. The first argument is the stream to read from. If no second argument given, the entire content is read. If a second argument is provided, it must be an integer indicating the maximum number of bytes to read.

Write data to a stream. The first argument is a stream, and the second argument is the data to be written. If the data is a string, it’s converted to binary by encoding using UTF-8 prior to writing. For binary data, the argument must be a scalar or a single-dimensional array of integers, where each integer must be in the range 0 to 255.

This function reads data up until the next newline or the end of the stream, and returns the string. If an end of file condition was seen before any data was read, the function returns null.

Given a byte array, return a stream which returns the data from the byte array.

Performs an HTTP GET request and returns the result.

Performs an HTTP POST and returns the result.

Performs an HTTP PUT request and returns the result.

Performs an HTTP DELETE and returns the result.

This function must be called monadically with the argument 0. It returns the current time in milliseconds from midnight, 1 January 1970 UTC.

The argument is a number that has the same form as the return value from time:timeMillis. The return value is a timestamp object.

The argument is a timestamp object, and returns an integer in the same as the return value from time:timeMillis.

Parse an ISO 8601 string and returns a timestamp object. Note that only UTC timestamps are supported.

Formats a timestamp object as an ISO 8601 UTC timestamp.

The special syntax function is called as follows:

The code inside the curly brackets will be executed, and before returning, the total runtime will be printed on the standard output. The entire call returns the last evaluated expression.

Connect to an SQL database. This is a monadic function with the argument being a JDBC connection string. To connect to an SQLite database:

Note that the connection has to be closed using the close function when done. After being closed, the connection object should no longer be used. Please see close and atLeave for information how to use the close function.

Send an SQL query to the database and return a table of the results. The left argument is an SQL connection previously obtained using sql:connect, and the left argument is a string containing an SQL statement. Example:

Perform an SQL update operation (this includes delete, update, etc). The left argument is the connection, and the right argument is the query string. Theis function returns the number of rows affected by the operation.

Prepare parametrised SQL statement. The left argument is the connection, and the right is the SQL query. Any parameters are specified using a ?, which can be later provided when calling queryPrepared or updatePrepared.

A prepared statement can be closed using the close function. If not closed, it will be automatically closed when the connection is closed.

Executes a prepared SQL query. The left argument must be a statement previously returned from prepare. The right argument must be a 1-dimensional array with a dimension equal to the number of positional parameters in the prepared statement. Each value in the argument is assigned to the corresponding position in the prepared statement and the query is executed. The result of the query is returned as per the query function.

Execute a prepared statement as one or more updates. If the right argument is of rank 1, it performs a single update with arguments assigned as per queryPrepared. If the right argument is a 2-dimensional array, each row represents a single update, with the columns assigned to the positional parameters in the prepared statement.

The following example inserts three rows into the table foo, which is assumed to have two columns, a and b:

The linear charting functions uses the same data format. Input can be a 1- or 2-dimensional array of numbers. For 1-dimensional input, each element is a single numeric value. For 2-dimensional input, the major axis represents each dataset, with the second axis each value within that dataset.

If the argument has row or column labels, the labels are displayed in the chart.

The plot function is a dyadic function that accepts a two-element array as a left argument, and a function or a list of functions as the right argument. The left argument represents the left and right edge of graph, and the right argument being the functions to plot.

To plot the square root function:

Kap supports a native map type. Objects of type map are atomic values (i.e. they behave similar to scalar numbers). A map contains a set of key/value pairs, where both the keys and values may be any Kap object.

The following section describes the decisions leading to the current design of maps in Kap.

Different array programming languages have taken different approaches to implementing maps (also called hashtables or dictionaries). Many languages have adapted existing array manipulation functions to maps, so that the user may treat maps as a variation of a 2-dimensional array. With such support, one would be able to do things like 1↑someMap to retrieve a single key/value pair, for example. For example, TinyAPL decided to take this approach.

In Kap, it was decided to make the map a scalar object. The reason for this is that while maps do share a lot of common properties with arrays, they are also different in several fundamental ways. Specifically, maps are highly inappropriate for anything which is not their primary use: To look up values by key. While it certainly would be possible to allow the existing array manipulation functions to operate on maps, and there may in fact be some useful usecases, for the most part the behaviour would be both surprising (because maps have no ordering) and inefficient. If this kind of manipulation of data in maps is needed, the function map:entries can be used to convert it to an array first, and then regular array functions can be used to manipulate the content.

Atoms are values with rank-0, and which are not enclosed arrays. Atoms cannot be enclosed (⊂) or disclosed (⊃) . Instead, performing these operations on an atomic value always returns the value itself.

An axis specifier is integer value that specifies which axis of a multidimensional array to act on. Axes are numbered from 0 to the dimensionality of the array - 1. For example, in a 2-dimensional array, axis 0 refers to the rows, while axis 1 refers to the columns.

An instance of an n-tuple. Lists are created using the function ≬, or specified as a series of elements separated by ;. For more information, see the section N-tuples.