janet/doc/Loop.md

Loops in Janet

A very common and essential operation in all programming is looping. Most languages support looping of some kind, either with explicit loops or recursion. Janet supports both recursion and a primitive while loop. While recursion is useful in many cases, sometimes is more convenient to use a explicit loop to iterate over a collection like an array.

An Example - Iterating a Range

Suppose you want to calculate the sum of the first 10 natural numbers 0 through 9. There are many ways to carry out this explicit calculation even with taking shortcuts. A succinct way in janet is

(+ ;(range 10))

We will limit ourselves however to using explicit looping and no functions like (range n) which generate a list of natural numbers for us.

For our first version, we will use only the while macro to iterate, similar to how one might sum natural numbers in a language such as C.

(var sum 0)
(var i 0)
(while (< i 10)
    (+= sum i)
    (++ i))
(print sum) # prints 45

This is a very imperative style program which can grow very large very quickly. We are manually updating a counter i in a loop. Using the macros += and ++, this style code is similar in density to C code. It is recommended to use either macros (such as the loop macro) or a functional style in janet.

Since this is such a common pattern, Janet has a macro for this exact purpose. The (for x start end body) captures exactly this behavior of incrementing a counter in a loop.

(var sum 0)
(for i 0 10 (+= sum i))
(print sum) # prints 45

We have completely wrapped the imperative counter in a macro. The for macro, while not very flexible, is very terse and covers a common case of iteration, iterating over an integer range. The for macro will be expanded to something very similar to our original version with a while loop.

We can do something similar with the more flexible loop macro.

(var sum 0)
(loop [i :range [0 10]] (+= sum i))
(print sum) # prints 45

This is slightly more verbose than the for macro, but can be more easily extended. Let's say that we wanted to only count even numbers towards the sum. We can do this easily with the loop macro.

(var sum 0)
(loop [i :range [0 10] :when (even? i)] (+= sum i))
(print sum) # prints 20

The loop macro has several verbs (:range) and modifiers (:when) that let the programmer more easily generate common looping idioms. The loop macro is similar to the Common Lips loop macro, but smaller in scope and with a much simpler syntax. As with the for macro, the loop macro expands to similar code as our original while expression.

Another Example - Iterating an Indexed Data Structure

Another common usage for iteration in any language is iterating over the items in some data structure, like items in an array, characters in a string, or key value pairs in a table.

Say we have an array of names that we want to print out. We will again start with a simple while loop which we will refine into more idiomatic expressions.

First, we will define our array of names

(def names @["Jean-Paul Sartre" "Bob Dylan" "Augusta Ada King" "Frida Kahlo" "Harriet Tubman")

With our array of names, we can use a while loop to iterate through the indices of names, get the values, and the print them.

(var i 0)
(def len (length names))
(while (< i len)
    (print (get names i))
    (++ i))

This is rather verbose. janet provides the each macro for iterating through the items in a tuple or array, or the bytes in a buffer, symbol, or string.

(each name names (print name))

We can also use the loop macro for this case as well using the :in verb.

(loop [name :in names] (print name))

Iterating a Dictionary

In the previous example, we iterated over the values in an array. Another common use of looping in a Janet program is iterating over the keys or values in a table. We cannot use the same method as iterating over an array because a table or struct does not contain a known integer range of keys. Instead we rely on a function next, which allows us to visit each of the keys in a struct or table. Note that iterating over a table will not visit the prototype table.

As an example, lets iterate over a table of letters to a word that starts with that letter. We will print out the words to our simple children's book.

(def alphabook
  @{"A" "Apple"
    "B" "Banana"
    "C" "Cat"
    "D" "Dog"
    "E" "Elephant" })

As before, we can evaluate this loop using only a while loop and the next function.

(var key (next alphabook nil))
(while (not= nil key)
  (print key " is for " (get alphabook key))
  (set key (next alphabook key))

However, we can do better than this with the loop macro using the :pairs or :keys verbs.

(loop [[letter word] :pairs alphabook]
  (print letter " is for " word))

Using the :keys verb and the dot syntax for indexing

(loop [letter :keys alphabook]
  (print letter " is for " alphabook.letter))

The symbol alphabook.letter is shorthand for (get alphabook letter). Note that the dot syntax of alphabook.letter is different than in many languages. In C or ALGOL like languages, it is more akin to the indexing operator, and would be written alphabook[letter]. The . character is part of the symbol and is recognized by the compiler.

We can also use the core library functions keys and pairs to get arrays of the keys and pairs respectively of the alphabook.

(loop [[letter word] :in (pairs alphabook)]
  (print letter " is for " word))

(loop [letter :in (keys alphabook)]
  (print letter " is for " alphabook.letter))