# Klong Introduction

```        ================================================================
|              KLONG  **  A SIMPLE ARRAY LANGUAGE              |
================================================================

A Really Short Introduction
By Nils M Holm
n m h @ t 3 x . o r g

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Klong tends to be terse. This is a table formatter:

fmtc::{(-|/{#\$x}'x)\$x}
fmtt::{+fmtc'+x}

"fmtc" (format column) converts the elements of a list to
strings and right-justifies them so that all strings have the
same length.

"fmtt" (format table) does the same for a two-dimensional array.

In case you are confused now, note that Klong is a mathematical
notation rather than a programming language. If you expect it to
be a programming language, you will only be frustrated and
dismiss it as a "write-only language" and think that it looks
like "line-noise".

While you read program code in most languages line by line, or
maybe even just scan over blocks of text, this will bring you
nowhere when trying to understand Klong. You will have to take
your time and read and write programs one character at a time.
This makes sense, because a single operator, like :^ (Reshape)
may do something quite complex, like reshaping an array:

[2 2 2]:^[1 2 3 4 5 6 7 8]

means: reshape the vector [1 2 3 4 5 6 7 8] to an array of the
dimensions (2,2,2). It will give you:

[[[1 2]    :"      1------2   "
[3 4]]   :"     /      /|   "
[[5 6]    :"    /      / |   "
[7 8]]]  :"   3------4  6   "
:"   |      | /    "
:"   |      |/     "
:"   7------8      "

(:"something" is a comment.)

Klong expressions consist of monadic (single-operand) prefix
operations, dyadic (two-operand) infix operations, and function
applications. They have no precedence rules and evaluate from
the right to the left, i.e.

1-2-3

means

1-(2-3)

but, as usual, parentheses can be used to regroup operations.

A Klong function is simply a program in braces. The function

{x+1}

would increment its argument by 1. There are no argument lists;
a function containing the symbol "x" is automatically a monadic
function receiving its only argument in "x".

A function (or any object) can by assigned to a variable using
the "::" (Define) operator:

inc::{x+1}

However, since Klong is terse, it often does not make sense to
assign a name to a function. For instance, here is factorial:

*/1+!x

(Times Over (one Plus Enumerate x)). It generates a list of the
numbers from 0..x-1, adds one to each element, resulting in 1..x,
and then multiplies all elements of that list. Giving a name to
the function would not really help, especially once you got used
to spotting idioms:

*/1+!x
fac(x)

Functions (which are also called "verbs") can be augmented by

#'x

(Size-Each x) will return a list containing the size of each
element of x:

#'["hi" "world" [1 2 3]]  -->  [2 5 3]

The Times-Over in factorial is also an augmented verb. "/"
(Over) folds a verb over an object:

f/[1 2 3 4]  =  f(f(f(1,2),3),4)
*/[1 2 3 4]  =  ((1*2)*3)*4

It would be called "fold" or "reduce" in other languages.

Let's get back to the table formatter.

Once you get used to it, it's quite readable. You just have to
a function like the above:

fmtc::{(-|/{#\$x}'x)\$x}

There is a parenthesized group, so we deal with that first:

fmtc::{(-|/{#\$x}'x)\$x}
^^^^^^^^^^^^
In the group there's another function, Size of Format of x,
applied to each member of x:

fmtc::{(-|/{#\$x}'x)\$x}
^^^^^^^
(Size of Format of x)-Each x. Note that the "x" of the inner
function is different from the "x" of the outer function! This
expression computes the size of the representation (Format) of
each member of a list:

{\$x}'[1 23 456]  -->  ["1" "23" "456"]   :"Format-Each"
{#\$x}'[1 23 456]  -->  [1 2 3]       :"(Size of Format)-Each"

The next step is

fmtc::{(-|/{#\$x}'x)\$x}
^^^
(Negate Max-Over it, "it" being the result of the previous
operation). "It", in this context, is the list of sizes obtained
in the previous step. "Max-Over it" is the maximum of the sizes,
"Negate Max-Over it" is the negative maximum size:

|/[1 2 3]  -->  3
-|/[1 2 3]  -->  -3

The rest of the function:

fmtc::{(-|/{#\$x}'x)\$x}
^^
(Format x with it, "it" here being the negative maximum size
from the previous step.) "\$" is an "atomic operator", i.e. it
is automatically applied to each member of a list, e.g.:

3\$[1 23 456]  -->  ["1  "
"23 "
"456"]

So each member of "x" is being formatted with "it". Dyadic
Format (Format2) with a negative left value "v" right-adjusts
its right value in a field of size #v (magnitude of v). So the
function right-justifies all members of its argument in strings
of the length of the greatest member:

(-3)\$[1 23 456]  -->  ["  1"
" 23"
"456"]

and hence:

fmtc([1 23 456])  -->  ["  1"
" 23"
"456"]

Now for fmtt:

fmtt::{+fmtc'+x}

(Transpose fmtc-Each Transpose x). Remember to read from the
right to the left:

- Transpose x
- fmtc-Each it
- Transpose it

So +fmtc'+x swaps rows and columns of a table, formats each row,
and transposes the result back. Because fmtc'x would format the
rows of a table, +fmtc'+x formats its columns. Voila, a table
formatter.

BTW, you can really try the above with Klong, because it always
binds the result of the most recent computation to the variable
"it" (user input indented):

fmtc::{(-|/{#\$x}'x)\$x}
fmtt::{+fmtc'+x}
:"Factorials, ordered by column"
+[3 3]:^*\1+!9
[[1 24 5040]
[2 120 40320]
[6 720 362880]]
+it
[[1 2 6]
[24 120 720]
[5040 40320 362880]]
fmtc'it
[["1" "2" "6"]
[" 24" "120" "720"]
["  5040" " 40320" "362880"]]
+it
[["1" " 24" "  5040"]
["2" "120" " 40320"]
["6" "720" "362880"]]

Nice, isn't it? A table formatter in just 38 characters of code.

are no loops or conditionals in it. This does not mean that
there are no such things in Klong, it only means you do not need
them very often. You use adverbs to do most of the heavy-lifting.

This program computes the square root of 2:

{(x+2%x)%2}:~2

The part in front of the :~ adverb is the formula that computes
the next iteration in Newton's method:

(x Plus 2 Divide x) Divide 2

The :~ (Converge) adverb applies that function to its right
argument initially and then to its own result over and over
again until it finds a fixpoint, i.e. a point where x = f(x).
The :~ operator has a cousin called \~ (Scan-Converge) that
collects the intermediate results:

{(x+2%x)%2}\~2  -->  [2
1.5
1.41666666666666666
1.4142156862745098
1.41421356237468991
1.41421356237309504]

(As we can see, Newton's methods converges really fast!)

Of course, Klong has more control constructs. Here is a function
that computes the maximal depth of a tree (a list of lists):

dp:{:[@x;0;1+|/dp'x]}

(If Atom x Then 0 Else 1 Plus Max-Over dp-Each x)

It uses the :[a;b;c] syntax that means "if a then b else c".
The function works as follows: If "x" is an atom (@x, Atom x),
then the result is 0. Else the result is 1 Plus Max-Over
dp-Each x -- the depth of the deepest element of x plus 1.

Are you getting the hang of it?

There are looping constructs, too, but they are rarely used.

{x<1000}{x*2}:~1  -->  1024

When :~ has a left argument, it is called While, and the above
expressions reads "While x Less 1000, x Times 2, starting at 1".
While also has a cousin that scans intermediate results:

{x<1000}{x*2}\~1  -->  [1 2 4 8 16 32 64 128 256 512]

However, the above result could be retrieved more easily and

{2^x}'!10

(2 Power x)-Each Enumerate 10. !x creates a list of integers
from 0 to x-1 and {2^x}' maps them to their respective powers
of two.

If you have to resort to conditionals and recursion, though,
Klong has those, too. Here's the Peter-Ackermann function:

ack::{:[0=x;y+1:|0=y;ack(x-1;1);ack(x-1;ack(x;y-1))]}

or, if you prefer a multi-line version:

ack::{:[0=x;y+1
:|0=y;ack(x-1;1)
;ack(x-1;ack(x;y-1))]}

The :| means "else-if". The ";" in a function call, like f(1;2),
conditional expression, it separates the predicate and the "true"
and "false" branches.

In programs (but outside of argument lists and conditionals),
it indicates a sequence:

sqr::{[a];a::x;{(x+a%x)%2}:~a}

Here it separates three parts. The first one, [a], indicates
that the function bound to "sqr" has a local variable called
"a". The second one (a::x, a Define x) assigns the value of the
argument "x" to "a". The third one is a generalized form of the
expression computing the square root of two, as shown earlier.

When "sqr" is called, the first part is skipped (because it is
a declaration), the subsequent expressions are evaluated from
left to right, and the result of the last one is returned. So
"sqr" computes the square root of any (positive) number.

Klong programs typically manipulate arrays or lists as a whole
rather than operating on individual elements. They also use
adverbs for finding fixpoints or creating sequences. This is
quite an abstract approach that requires careful planning and
thinking. Typing speed does not really matter when solving
problems in Klong. Understanding the problem properly does.

================================================================
```