31:T3b29,32:T70d,

1 ╵ ╰──╮ ╵ ╭─────╮ ╵╵ ╰─ 2 ─╯╰─╮╰─── ╷╰───╮╯ ╷ 3 ╰─── ╷ ──╯╭ 5 │ │ 7 ╰─╯╷

Fig. 4.1: A program to subtract one list cell value from another. But what is the purpose of that glyph on the right?

33:T747,Rather than get Rivulet to follow all data and action instructions glyph-by-glyph, we can make the effect of a block of instructions conditional on the answer to some question. We do this with _question strands_. These have two parts: The upper part starts with a `╷` which acts as a marker, like the marker of a reference strand, identifying a cell or list to be evaluated by the question strand. It should end in a lexeme with vertical open end. The intermediate connected lexemes can be of any type or number as long as the final lexeme ends in a column somewhere to the left of the starting `╷` marker column. The second part must start immediately below the final lexeme of the upper strand, continuing it with another `╷`. If the final lexeme of this lower part ends vertically, the marker of the upper part will reference a list cell using exactly the same referencing rules as the marker of a reference strand. If it ends horizontally, it references the entire list indicated by the marker's row (analogous to the horizontal end of an action strand indicating a list action). Question strands have a lot of flexibility in their layout as their length and position relative to other strands in the same glyph makes no difference to their execution. This is something we will consider in more detail in the next section. If the marked cell contains a 0 or a negative number, the _code block_ in which the question strand sits is rolled back. In other words, any changes made to lists within that code block are undone, and the lists returned to their prior values. This is why glyph levels are important, because they allow glyphs that can be rolled back by a question strand to be grouped into a single block. This probably makes more sense with an example:34:T91e,

1 ╵ ╰──╮ ╵ ╭─────╮ ╵╵ ╰─ 2 ─╯╰─╮╰─── ╷╰───╮╯ ╰───╮╷ 3 ╰─── ╷ ──╯╭ ──╯│ │ │ ╭╯ ╰─╯╷ │ ╷ │ ╷

Fig. 4.2: A program to test if list2[0] is less than list2[1]

35:T76c,The first two glyphs perform a subtraction of two list items just as they did in Figure 4.1. The modified level 2 glyph first sets `list1[0]` to 1 (again, as previously), but now adds a zero-padded question glyph shown in green. Its top marker refers to `list2[1]` (thanks to the zero value strand to its left), which contains the result of the earlier subtraction. So if this value is 0 or less, the question strand will roll back everything in this block, which in this case was the setting of `list1[0]` to 1. The result is that `list1[0]` will contain a 1 ('true') if `list2[0]` is less than `list2[1]` (no rollback) or a 0 ('false') if it is not. In other words it tests whether or not the first two items in `list2` are in numerical order. You can confirm the algorithm by running `riv -p` on the code, which should generate the following output: ``` glyph 0 ╰──╮ ─╯╰─╮╰─── ╰─── GLYPH_SUMMARY level: 1 list1[0] += 0 list2[0] += 11 list2[1] += 6 glyph 1 ╭─────╮ ╷╰───╮╯ ──╯╭ │ │ ╰─╯ GLYPH_SUMMARY level: 1 list2[0] += 0 list2[1] -= list2[0] glyph 2 ╰─ ╰───╮╷ ──╯│ ╭╯ │ ╷ │ GLYPH_SUMMARY level: 2 list1[0] += 1 list2[0] += 0 block_type = if [2, 1] <= 0: roll back ``` And you can test the result by running `riv -o numeric`, which in this case should generate a single **0** indicating `list2[0]` (11) is not smaller than `list2[1]` (6). Try changing the initial pair of values in `list2` to check it works for other cases. One note of caution: When viewing the output from the `riv` command without any options, it will display the list state before any rollback, so may not correspond to the final output. Think of it as a snapshot taken before any question strands are evaluated.36:T9c8,

1 ╵ ╰──╮ ╵ ╭─────╮ 2 ─╯╰─╮╰─── ╷╰───╮╯ 3 ╰─── ╷ ──╯╭ │ │ 1 ╵╵ ╰─ ╵╵ ╰─╯╷ 2 ╷ ╰───╮╷ 3 ╭╮──╯│ ╷╰───╯ │ ╷

Fig. 4.3: A level 2 code block split across two glyphs

37:T997,

1 ╵ ╰─ ╵ ╵╵ ╰──╮ 2 ╮╰──╰─╮╰─╰╮ ╰─ ─╯╷ 3 ╰──── ╰── ╰── ╷ ╭─╮ ╭──╮│ │ ─╯│ ╰─╮ ╭───╯ │ ╷ ─╯╷ ╰─ ╷

Fig. 4.4: A program to test if list2 contains only even numbers

38:Tc9c,

1 ╵╭─ ─╮ ─╮ ╵╰─╮ ╵╰─╮ ╵╰─╮ ╵╰─╮ ╵╰─╮ 2 ╯╰─╰──╯╰──╰───╯╷ ╴╯ ╴╯ ╴╯ ╴╯ ╴╯ 3 ╭─╮ ╭─╮ ╭─╮ ╭─╮ ╭─╮ │ │ │ │ │ │ │ │ │ │ ╰ │╷ ╰ │╷ ╰ │╷ ╰ │╷ ╰ │╷

Fig. 4.6: Summing the values of list2 without using a while loop

39:T936,

1 ╵╭─ ─╮ ─╮ ──╮ ╵╵ ╰─╮─╮ 2 ╯╰─╰──╯╰──╰───╯ ╰─╯ ╴╯ │ 3 ╭── ╭─╮ │ 5 ╯ ╷ ╷│ │ ╯ │╰ │╭╮ ╰───╯╷ │╷

Fig. 4.7: Summing the values of list2 using a while loop

3a:Td13,

1 ╵ ╵ ╭─ ─╮ ╵╵ ╮ 2 ╴─╮ ─╮ │ ╰─╯ ╰─╶ 3 │╰─╯ ╭╶ │╭──╯ ╮ 5 ╯ ╰─╯╯╰─ ╰─╶╷ ╭ ╭ ╰──╮ ╵ │ ╭─│╭ ╭ ╭─╮╭─╮╷ │ │ │ ││ │ │ ││ ││ ╰─╯ ╷ ╰─╯╰─╰─╷ ╰ │╰ ││╷

Fig. 4.8: Summing the values of any input stored in list2

3b:Tee0,

1 ╵ ╵ ╭─ ─╮ ╵╵ ╮ ╵╰─╮ 2 ╴─╮ ─╮ │ ╰─╯ ╰─╶ │ 3 │╰─╯ ╭╶ │╭──╯ ╮ ╴╯ 5 ╯ ╰─╯╯╰─ ╰─╶╷ ╭ ╭ ╰──╮ ╵ │ ╭─│╭ ╭ ╭─╮╭─╮╷ │ │ │ ││ │ │ ││ ││ │ ╰─╯ ╷ ╰─╯╰─╰─╷ ╰ │╰ ││╷ ╭─╯╷

Fig. 4.9: Program to calculate the mean of an input list (just one simple division glyph added to the previous program)

3c:T886,

1 ╵╰──╮ ─╮ ╵╵╭─╮╰───╮ 2 ─╯╰─╯ │ │╭ ╷─╯ ╭ │ ╷│ ╰─╮ │ │ ││ │ │ ─╯ ╷ │─╯╰─╯ │ ╰──────╯╷

Question 2: What does this do?

3d:T18f5,

1 ╵╰─ 2 ╭───╰─╮ ╮ 3 │ ╮ ╴─╯ ─╮│ 5 │ │ ╭ ╭╶╵╰─╯│ 7 ─╮ ╭─ │ │ │ │ ╰───╯ 11 ╭─ │ │ ╭─ │ │ ╰─╯ ╭ 13 │ │ ╭─│ │╭─ │ ╰───────╮ │ 17 │ ╭──╯╭───╯ │╭────╯│ │ ╭ │ │ 19 │╭──╯ ╭─╯╭────╯│ │ │ │╴╮╭────╯ │ 23 ╰───╯╯ ╯ ╯ ╮╯ ╰───╯╮ │ │ ││ ╴╮ │ 29 ╰─── ╰──╯ ╰─╯╰────╯─╯╷ 1 ╵╵╰──╮ 2 ╭ ─╯╷ │╭──╯ │╷ │╰──│ ╰───╯╷

Question 3: What does this do?

3e:T170a,

1 ╵╰─ ╵ ╵╵ ╵ ╵╵╰──╮ 2 ╴╮ ╭╶ ─╮ ╴─╮ ─╮ ╭ ─╯ 3 ╰─╯│ ╭─╯ ╵ │╭─╯ │ 5 ╭│ │ ──╮ ╰─╯ ╯│ │ │╮ ╷ 7 ╵ ││ ╯ ╴─╮ │ ╭─╮ ╮ ╴╮│ ╰─╯│ │ 11 │ │╯ ╭─╮ ╯╰─╯ ╭╶│╴─╯╷ │╯ ╷╭─╯ ╰─╯╭ │ │ ╭ │ │╭─╮│ ╰ ╭─╮╷ │ │ ╷ ╭─│╭ ╰─╯│ ╰─╮ │ │ ╰─╯ │ ││ │ │ ╷ │ │ ╷ ╰─╯╰─╷ ╰─╯ │╷ ╷ ╰─ ╰─ ╷

Question 4: What does this do?

3f:T522,

(click for answer)

This program detects if the input list is a _palindrome_.

The first glyph makes two copies of the input `list2`, one stored in `list3` and one in `list11`. Additionally it places a 1 in `list1` and `list7`.

The second glyph sets `list11` to be a 'shadow list' (See Figure 4.8 above) containing 1s in place of the original input list values. Using this shadow list to set the number of iterations, the third glyph pops values off the end of `list3` to the end of `list5` effectively reversing the list's contents (See Figure 3.15 in the previous chapter). `list2` and `list5` now contain the same values, but one in the reverse order of the other.

The fourth glyph subtracts each of the values in `list2` from their equivalent in reversed `list5` and adds 1 to list11[0] setting its value to 2 for use in next glyph.

And the final gylph, squares all values in the difference list (`list5`) using that 2 from the previous step, and then checks to see if it contains any positive numbers. If there are, this indicates there has been some difference between the original list and its reverse, so the output is set to 0, if not, the glyph is rolled back and the original value of 1 is retained.

40:T1d09,

1 ╵ ╰─ ╵╵ ╮ ╭─╮ ─╮ 2 ╮─╮ ╭─╮ ╭─╮ ╭─╮ ╭╯╵ │╷╰─╮╯╭─╮ 3 │ ╰─╯ ╰─╯ │ │ ╰─╯╭╰─╯╰╮ ╰─╯││ 5 ╰───╮ ╭───╯ ││╭─╮│╭╮╭╮╷╭╮╭╮││ 7 ╭╯ ╰╮ │╰╯╭╯╰╯╰╯││││││││ 11 ╭╯ ╰╮ │╭╮│╭╮ ╭╮││││││││ 13 ╰╮ ╭╯ │││╰╯╰─╯╰╯╰╯╰╯│││ 17 ╭──╯ ╰╮ ││╰───────────╯││ 19 ╰╮╭╮ ╭╮╭╯ │╰─────────────╯│ 23 ╰╯╰─╯╰╯ ╷ ╰───────────────╯╷

Question 5: What does this do?

41:[] 2f:{"title":"4. Rivulet Levels and Decisions","cells":[{"id":0,"value":"# 4. Rivulet Levels and Decisions\n\n[Action Strands](https://observablehq.com/@jwolondon/rivulet-action-strands)","pinned":false,"hidden":false,"mode":"md"},{"id":1539,"value":"$31","pinned":false,"hidden":false,"mode":"html"},{"id":1243,"value":"## 4.1 Glyph levels\n\nSo far, all the glyphs we have seen have started with single `╵` glyph markers. These implicitly create glyphs at 'level 1'. A level can be thought of as a single block of code, even if split across multiple glyphs.\n\nWe can create deeper levels simply by increasing the number of adjacent glyph opening markers. Consider the following program:","pinned":false,"hidden":false,"mode":"md"},{"id":1248,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":1254,"value":"The first glyph allocates two numbers (11 and 6) to `list2`. The second glyph subtracts `list2[0]` from `list2[1]` placing the result back in `list2[1]`. But we have a third glyph on the right at 'level 2' (indicated by the `╵` `╵` ) that allocates a 1 to `list1[0]`. \n\nIn this context, that third gylph being at level 2 makes no difference to the effect of the program – we would have exactly the same output if it had been started with a single `╵`. Deeper glyph level markers become useful when we need the program to make decisions...","pinned":false,"hidden":false,"mode":"md"},{"id":1267,"value":"## 4.2 Conditional 'if' blocks","pinned":false,"hidden":false,"mode":"md"},{"id":1294,"value":"$33","pinned":false,"hidden":false,"mode":"md"},{"id":1280,"value":"$34","pinned":false,"hidden":false,"mode":"md"},{"id":1303,"value":"$35","pinned":false,"hidden":false,"mode":"md"},{"id":1334,"value":"It is important to remember that code blocks are not necessarily equivalent to glyphs. A code block is formed by a consecutive sequence of glyphs at the same level. When a question strand results in a roll back, all glyph instructions in the code block of the question are undone. For example, the program above could also be expressed as follows, separating the level two value and question strands into two glyphs. Both get rolled back if the question evaluation does not succeed:","pinned":false,"hidden":false,"mode":"md"},{"id":1336,"value":"$36","pinned":false,"hidden":false,"mode":"md"},{"id":1328,"value":"For a question strand with a final horizontal lexeme (a list-marked question), it only succeeds if every cell in the referenced list is not negative and at least one cell within it is positive. The presence of a negative value or the complete absence of positive numbers will trigger the roll back.\n\nHere's an example that uses a list-marked question to test if a list contains only even numbers:","pinned":false,"hidden":false,"mode":"md"},{"id":1357,"value":"$37","pinned":false,"hidden":false,"mode":"md"},{"id":1363,"value":"The first level 1 glyph allocates the list of numbers to check for evenness to `list2` (`[12, 4, 8, 2, 6]`) and the default output value of 1 in `list1`. The second level 1 glyph uses the modulus action modifier to convert `list2` into their modulus 2 values. So the list now contains 0s for even numbers and 1s for odd numbers. Finally the level 2 glyph assigns a 0 to the output (via the assignment action strand), but the list marked question strand will roll back that assignment if all of the modulus values are 0s (i.e. all even).\n\nYou can test this by specifying the input `list2` from the command-line. Assuming the program is called `evens.riv`,\n\n```\n riv -i \"4, 8, 120, 6, 44\" -o numeric evens.riv\n```\nshould yield a `1` (all even numbers) and\n\n```\n riv -i \"4, 8, 120, 6, 45, -30, 1234\" -o numeric evens.riv\n```\nshould yield a `0` (at lest one odd number).","pinned":false,"hidden":false,"mode":"md"},{"id":1270,"value":"## 4.3 Conditional 'while' blocks","pinned":false,"hidden":false,"mode":"md"},{"id":1372,"value":"These use question strands in a similar way to `if` blocks. The only visual difference is that the bottom end of the upper part (immediately above the break in the strand) must be to the _right_ of the strand start, not to its left. The rules for evaluating the question are identical to `if` question strands for both the cell-based and list-based variants. Unlike the `if` case, the entire block is repeatedly applied while the question succeeds. After the first failed evaluation, the last iteration of the block is rolled back and flow proceeds to the next glyph at the previous level (or halts if the last glyph).\n\nConsider how we might use a while loop to count backward from 10 to 1:","pinned":false,"hidden":false,"mode":"md"},{"id":1402,"value":"

\n1 ╵ ╮ ╵╵╷─╯\n2 │ ╰─╮\n3 │ ╷\n5 ╰──╷ │╷\n

Fig. 4.5: Counting down from 10 to 1 with a 'while loop'

\n","pinned":false,"hidden":false,"mode":"md"},{"id":1414,"value":"The first glyph sets `list1[0]` to be 10. The second glyph at level 2 decreases that value by 1 (adds -1 to `list1[0]`) then uses a question strand to test if it is zero. Because the strand's break (line 3) ends to the right of its start, this repeats the glyph, again decreasing `list1[0]`. After 10 iterations `list1[0]` will be 0, so the question does not succeed, so rolls back the last decrement, leaving `list1[0]` at 1.\n\nThis gives us a pattern we can use to repeat some instructions a fixed number of times (sometimes expressed as a 'for loop' in many other languages).","pinned":false,"hidden":false,"mode":"md"},{"id":1394,"value":"For a more practical example, consider the task of calculating the sum of the values in `list2` and reporting it in `list1[0]`. Without a while block, we could do this as a set of move cell actions, adding a moved `list2` value to `list1[0]` for each element in `list2`:","pinned":false,"hidden":false,"mode":"md"},{"id":1376,"value":"$38","pinned":false,"hidden":false,"mode":"md"},{"id":1417,"value":"We can refactor to use the 'for loop' pattern to repeat that moving action a fixed number of times. In the example below, the number of repeats is stored in `list5[0]` to keep it separate from `list2` which contains the values to sum and `list1[0]` which contains the running total as we progress through the loop.\n\nBecause we are popping values off `list2` we need to consider what happens when we get to the final element in our list to sum. A question strand will always perform its glyph's strand commands, including once when the question does not succeed. Only at that point do we roll back the last iteration. This means we need to take care not to pop from an empty list. We avoid this by adding an extra padding zero at the end of the list to sum.","pinned":false,"hidden":false,"mode":"md"},{"id":1386,"value":"$39","pinned":false,"hidden":false,"mode":"md"},{"id":1551,"value":"Suppose we wanted to adapt the program to sum the input list provided via the command line (`riv -i ...`). At the point we write the program we don't know how long the list will be so cannot code its length in `list5` as above. \n\nOne alternative strategy is to create a 'shadow list' that stores a `1` for every value in the input list. Testing that rather the original list avoids failing the test when the input legitimately contain zeros or negative numbers. Here's one implementation:","pinned":false,"hidden":false,"mode":"md"},{"id":1555,"value":"$3a","pinned":false,"hidden":false,"mode":"md"},{"id":1564,"value":"The first glyph copies the input `list2` to a shadow list (`list5`) and initialises `list3` to be 1. The second glyph uses the list modified assignment action to copy that 1 stored in `list3` to every cell of the shadow `list5` and appends an extra 1 to the end of it and the input list (to protect the last popping action in the final glyph). It also resets `list3` back to 0 so we can use it to accumulate the number of items in the list.\n\nThe final glyph does the looping – popping values off both the shadow list and the original input list, accumulating them in `list3` and `list1` respectively. ","pinned":false,"hidden":false,"mode":"md"},{"id":1557,"value":"Assuming this program is called `summer`, running the following \n\n```\nriv -i \"1, 2, 3, 4, 5, 6, 7, 8\" -o numeric summer.riv\n```\n\ngenerates `36` as output. And `list3` usefully stores the length of the input list (the sum of all the 1s in the shadow list), which can be useful for extending the program. For example, it would be easy to calculate the mean of the input list values by dividing `list1[0]` by `list3[0]`:","pinned":false,"hidden":false,"mode":"md"},{"id":1568,"value":"$3b","pinned":false,"hidden":false,"mode":"md"},{"id":1553,"value":"## 4.4 Some examples","pinned":false,"hidden":false,"mode":"md"},{"id":1396,"value":"That's it for the Rivulet language! A set of just ten lexemes and four types of instructions – _data strands_, _reference strands_, _action strands_ and _question strands_. Yet between them we have Turning complete language capable of (theoretically) any computable task.","pinned":false,"hidden":false,"mode":"md"},{"id":1423,"value":"But to round off, here are few more examples – try decoding the strands to work out what each program does. Assume that all generate some output in `list1` when complete.","pinned":false,"hidden":false,"mode":"md"},{"id":1585,"value":"### Some combinatorial help","pinned":false,"hidden":false,"mode":"md"},{"id":1435,"value":"

\n1 ╵╰─ ╵╵ ╮─╮\n2 ╮ ╴─╯╷╯\n3 │ ╭─╮╰╮\n5 │ │ ╷\n7 ╰─╷ │╷\n

Question 1: What does this do?

\n","pinned":false,"hidden":false,"mode":"md"},{"id":1441,"value":"

(click for answer)

\n The first glyph allocates some input value to `list2[0]` (7 in this case) as well as a 1 in the output `list1[0]`. The level 2 glyph multiplies the output value by `list2[0]` (via action modifier 2) before decreasing list2[0] by one. This process is repeated until `list2[0]` is zero (via the 'while' question strand). It therefore ends up placing 7×6×5×4×3×2×1 = 5040 in the output list. In other words this is a factorial calculator.\n

","pinned":false,"hidden":false,"mode":"md"},{"id":1427,"value":"### 100% natural ingredients\nAssume an input value or values can be specified in `list2` with the `riv - i` option.","pinned":false,"hidden":false,"mode":"md"},{"id":1456,"value":"$3c","pinned":false,"hidden":false,"mode":"md"},{"id":1468,"value":"

(click for answer)

\n Tests if the input list contains only natural numbers (0 and positive whole numbers).\n

\n The first glyph sets the output to 0 and appends a 1 to the end of the input list. The second sets the output to 1 and tests `list2`. If it contains any negative values it will fail and roll back to the original output of 0. Because we've appended a 1 to the input list, even an input of just zeros will pass the test.\n

","pinned":false,"hidden":false,"mode":"md"},{"id":1646,"value":"### Open Sesame\nAssume an input value or values can be specified in `list2` with the `riv - i` option.","pinned":false,"hidden":false,"mode":"md"},{"id":1448,"value":"$3d","pinned":false,"hidden":false,"mode":"md"},{"id":1450,"value":"

(click for answer)

\n This is a simple password checker. The group of 8 data strands on the left of the first glyph code the password (`[80,65,83,83,87,79,82,64]` corresponding to the unicode characters 'PASSWORD') in `list23`. Additionally the output is set to 1. The remaining strands in the first glyph copy the password to `list3`, take the squared difference between every cell in `list3` and whatever is provided as input in `list2`.\n

\nThe second glyph just checks if the squared differences now stored in `list2` contain any positive vales. If so, this means there must be some difference between the input and the secret password, so it assigns 0 to the output. If not, the password matches so it rolls back to the default output of 1.\n

","pinned":false,"hidden":false,"mode":"md"},{"id":1587,"value":"### Was it a car or a cat I saw?\n\nAssume an input value or values can be specified in `list2` with the `riv - i` option.","pinned":false,"hidden":false,"mode":"md"},{"id":1454,"value":"$3e","pinned":false,"hidden":false,"mode":"md"},{"id":1466,"value":"$3f","pinned":false,"hidden":false,"mode":"md"},{"id":1590,"value":"### A friend revisited","pinned":false,"hidden":false,"mode":"md"},{"id":1460,"value":"$40","pinned":false,"hidden":false,"mode":"md"},{"id":1470,"value":"

(click for answer)

\n This is also a factorial calculator, identical in function to the first example. But it illustrates the flexibility we have in strand arrangement, allowing for a diversity of visual styles in code layout. More on this in the next section.\n

","pinned":false,"hidden":false,"mode":"md"},{"id":1420,"value":"In the [next section](https://observablehq.com/@jwolondon/rivulet-aesthetics-layout) we will consider what opportunities this very visual language, rich in strand synonyms, offers us from a visual design perspective.","pinned":false,"hidden":false,"mode":"md"},{"id":1239,"value":"[Aesthetics and Layout](https://observablehq.com/@jwolondon/rivulet-aesthetics-layout)","pinned":false,"hidden":false,"mode":"md"},{"id":76,"value":"---\n\n## Appendices","pinned":false,"hidden":false,"mode":"md"},{"id":1165,"value":"_For formatting Rivulet code snippets:_","pinned":false,"hidden":false,"mode":"md"},{"id":78,"value":"import { rivFormat } from \"@jwolondon/rivulet-intro\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":1162,"value":"rivFormat()","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W41","stdlib":"1","titling":"auto"}