31:T3b46,32:T63f,Let's break it down to understand what's going on. - The entire glyph is enclosed between `╵` and `╷` lexemes. These are used to identify the start and end of the glyph and should not be connected to any other strand. - A _hook_ is indicated by an open-ended short line adjacent to a corner. In this case it is at the top of the strand pointing left. A hook whose open end points left or up indicates a data strand of some kind, meaning it will specify some data value or reference to be inserted into a target list. - Implicit are line numbers that count down from the opening glyph mark `╵`. Unlike more conventional line numbers, they follow the sequence 1, 2, 3, 5, 7, 11 ... (i.e. 1 followed by the prime number sequence). The glyph above therefore has line values 1, 2, 3 and 5. - In a value strand, horizontal dash symbols `─` are used to indicate the magnitude of the value being assigned. This is calculated by counting the number of dashes multiplied by the line number they are on. So 2 dashes on line 5 indicate adding 10 to a list. - Dashes are added when they proceed from left to right (starting from the hook), and subtracted when traversed right to left. The ability both to add and subtract values allows any arbitrary whole number to be assigned to a list by meandering the strand over multiple lines. Here for example is a value strand that adds **16** to a list: (1×2) + (-2×3) + (4×5). The line numbers are added for clarity, but are not required.33:T969,

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

Fig. 2.4: Five ways of adding 16 to a list.

34:T51e,

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

Fig. 2.5: Three value strand glyphs cumulatively adding to list1[0] to give 33.

35:T999,

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

Fig. 2.6: Two value strands adding to list1 followed by three adding to list2.

36:Ta17,

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

Fig. 2.7: The last three strands move from a line 2 hook to line 1 before encoding 16.

37:T628,

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

Fig. 2.8: Five lists each with a single cell containing a 16.

38:T412,In the example above, the five 16s were each created explicitly. Given the repetition, an alternative approach might be to create just one value strand representing 16, then reference it when creating duplicates in the other lists. We can do this by creating _reference strands_. Like value strands, reference strands start with either a leftward or upward pointing hook and the row in which the hook is placed determines the target list that is to be changed. At the other end of a reference strand is a semi-detached half-length line (either horizontal `╴` `╶` or vertical `╵` `╷`) known as a _marker_. The row in which the marker is placed determines the list being referenced (the source list). The element to reference and the element in which the reference is placed are determined by how many other data strand hooks are to the left of the marker (source cell) and hook (target cell) . Consider this example:39:Tec0,

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

Fig. 2.10: Five reference strands and a single value strand adding to cells in list1.

3a:T9f8,

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

Fig. 2.12: Ten ways of representing zero in a value strand.

3b:[] 2f:{"title":"2. Rivulet Data Strands","cells":[{"id":0,"value":"# 2. Rivulet Data Strands\n\n[Introduction to Rivulet](https://observablehq.com/@jwolondon/rivulet-intro)","pinned":false,"hidden":false,"mode":"md"},{"id":1291,"value":"$31","pinned":false,"hidden":false,"mode":"html"},{"id":1150,"value":"Data are represented in Rivulet program as either _value strands_ (direct encodings of numeric values) or _reference strands_ (references to other data strands).","pinned":false,"hidden":false,"mode":"md"},{"id":1153,"value":"## 2.1 Value strands","pinned":false,"hidden":false,"mode":"md"},{"id":16,"value":"A value strand writes values to a target list. By default, the value represented by the strand is _added_ to a value in a target list cell, but since unassigned list values are interpreted as 0s, that addition is initially equivalent to an assignment operation.\n\nHere's a value strand that sets the first element of a target list to be 10:","pinned":false,"hidden":false,"mode":"md"},{"id":234,"value":"

\n╵ ╮\n │\n │\n ╰── ╷\n

Fig. 2.1: Adding 10 to the first cell in a list.

\n","pinned":false,"hidden":false,"mode":"md"},{"id":123,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":249,"value":"

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

Fig. 2.2: Adding 16 to the first cell in a list.

\n","pinned":false,"hidden":false,"mode":"md"},{"id":460,"value":"The example above happened to proceed from top to bottom as the hook was at the top of the strand. But it is the traversal from the hook that always determines what 'left-to-right' or 'right-to-left' means. For example, below the hook is at the bottom of a strand of the same shape, but now it encodes **-16**: (-4×5) + (2×3) + (-1×2).","pinned":false,"hidden":false,"mode":"md"},{"id":471,"value":"

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

Fig. 2.3: Subtracting 16 from the first cell in a list. The hook is at the bottom of the strand on line 5.

\n","pinned":false,"hidden":false,"mode":"md"},{"id":148,"value":"The ability both to add and subtract numbers means the same operation can be applied in multiple ways. For example, all of the following each add a 16 to the list.","pinned":false,"hidden":false,"mode":"md"},{"id":257,"value":"$33","pinned":false,"hidden":false,"mode":"md"},{"id":838,"value":"That flexibility in expression of the same instruction gives rise to a key part of the Rivulet language: _design the strands with an eye to the visual impact of the overall layout._","pinned":false,"hidden":false,"mode":"md"},{"id":188,"value":"## 2.2 List numbers and cells","pinned":false,"hidden":false,"mode":"md"},{"id":232,"value":"Copying the text from Figure 2.4, saving it as a `example.riv` file and running the command **`riv -p example.riv`** generates the following output:\n\n```\nglyph 0\n ╮ ╮ ╮ ╭─╯ ╭───────╯\n ╰─╮ ╰──────── │ │ │\n ╰─╮ ╰─╮ │ │ ────╮\n │ │ ╰──╮ │ │\n │ │ ╰─ ╰─────╯\n ╰─ │\n ╰─ \nGLYPH_SUMMARY\nlevel: 1\nlist1[0] += 16\nlist1[1] += 16\nlist1[2] += 16\nlist1[3] += 16\nlist1[4] += 16\n```\n\nThat should make it clearer that each of the five strands is adding 16 to the list cell corresponding to its ordered left-to-right sequence of strands. The result is a single list (`list1`) containing 5 values.","pinned":false,"hidden":false,"mode":"md"},{"id":499,"value":"We are not limited to a single glyph in a Rivulet program. If more than one glyph appears in a program, they can be applied in sequence in western script 'reading order' (left-to-right and then top-to-bottom). And because the value strand operations we've seen are _additions_, not assignments, the effect of multiple glyphs is cumulative. For example, the following program adds 4, 22 and 7 to the first cell in `list1`. The final result being a single list with just one cell (33).","pinned":false,"hidden":false,"mode":"md"},{"id":501,"value":"$34","pinned":false,"hidden":false,"mode":"md"},{"id":279,"value":"`list1` (indicated by strands with hooks on line 1) has special status to store the output of the Rivulet program. To view the output list with the interpreter use the option `-o numeric` (or `-o unicode` if numbers represent character codes).\n\nTo create other lists, we start the hook on a different line, where the line number (a prime) indicates the list number. For example we could shift the last three strands down one line:","pinned":false,"hidden":false,"mode":"md"},{"id":281,"value":"$35","pinned":false,"hidden":false,"mode":"md"},{"id":288,"value":"Sending this version to `riv -p` generates the following:\n\n```\nglyph 0\n ╮ ╮ \n ╰─╮ ╰──────── ╮ ╭─╯ ╭───────╯\n ╰─╮ │ │ │ \n │ ╰─╮ │ │ ────╮\n │ │ ╰──╮ │ │\n ╰─ │ ╰─ ╰─────╯\n │ \n ╰─ \nGLYPH_SUMMARY\nlevel: 1\nlist1[0] += 16\nlist1[1] += 16\nlist2[0] += 22\nlist2[1] += 23\nlist2[2] += 21\n```","pinned":false,"hidden":false,"mode":"md"},{"id":290,"value":"We now have two lists (`list1` and `list2`) with the first containing two values and the second containing three. But note that because we have moved three strands down a line, the corresponding cells don't contain a `16`, but larger values (the prime number line values used range from 2 to 17 rather than 1 to 13). \n\nIf we want to place 16 in the shifted strands we need to adjust the positions of the horizontal dashes while keeping the hooks on line2. One way of doing this is to move from the new shifted hook position back up to the top before encoding the 16s as we did in Figure 2.4.","pinned":false,"hidden":false,"mode":"md"},{"id":292,"value":"$36","pinned":false,"hidden":false,"mode":"md"},{"id":299,"value":"These shifted strands have now traced a rather convoluted route to encode their 16s, so we could encode more concisely. Here's an example where 16 is added to 5 separate lists, with a more concise strand style:","pinned":false,"hidden":false,"mode":"md"},{"id":301,"value":"$37","pinned":false,"hidden":false,"mode":"md"},{"id":304,"value":"Running this through the `riv` compiler generates the following output, confirming we have created five separate lists, each with a single cell containing a 16:\n\n```\nglyph: 0\n1: [16]\n2: [16]\n3: [16]\n5: [16]\n7: [16]\n```","pinned":false,"hidden":false,"mode":"md"},{"id":325,"value":"## 2.3 Reference strands","pinned":false,"hidden":false,"mode":"md"},{"id":327,"value":"$38","pinned":false,"hidden":false,"mode":"md"},{"id":338,"value":"

\n1 ╵ ╭──╯\n2 ╷ ╰──╮\n3 ╰──── ╷\n

Fig. 2.9: A value strand containing 16 in list 2 and a reference strand that references it in list 1.

\n","pinned":false,"hidden":false,"mode":"md"},{"id":346,"value":"Looking for hooks from left to right, the first strand is the one with a hook on line 2 even though part of the other strand extends to its left. It is the relative hook position that determines the order in which strands are applied. This first-read strand is a value strand storing 16 in `list2[0]`. The next to be read is the strand on line 1 (because its hook is to the right of the other hook). At its other end is a marker, so we know it's a reference strand. This is saying add the value at `list2[0]` (marker is on line 2 with no data strand hooks to its left) to `list1[0]` (hook is on line 1 with no data strand hooks to its left). You can confirm this with the `riv -p` command, which generates the following:\n\n```\nglyph 0\n ╭──╯\n ╷ ╰──╮ \n ╰──── \nGLYPH_SUMMARY\nlevel: 1\nlist2[0] += 16\nlist1[0] += list2[0]\n```","pinned":false,"hidden":false,"mode":"md"},{"id":349,"value":"Unlike value strands, the path between a reference strand's hook and marker does not influence how it is interpreted. The important elements are the locations of each end and how many other strand hooks are to the left of them. This gives us some flexibility in layout. For example, the following creates five duplicates of 16 in list1 by referencing the same value strand five times:","pinned":false,"hidden":false,"mode":"md"},{"id":352,"value":"$39","pinned":false,"hidden":false,"mode":"md"},{"id":363,"value":"The key parts of the `riv -p` output being:\n\n```\nlist2[0] += 16\nlist1[0] += list2[0]\nlist1[1] += list2[0]\nlist1[2] += list2[0]\nlist1[3] += list2[0]\nlist1[4] += list2[0]\n```\n\nThe 'stacked cups' structure is because the reference strands need to be assigned after their source value strand (therefore their hooks appear to the right of the value strand hook), but the markers need to be placed before it in order to reference cell 0. If the markers were to be placed to the right of the assignment, they would then refer to cell 1, which at that point is unassigned.\n\nAn alternative more compact version would be to separate the value strand from the reference strands as two separate glyphs. That way, the reference strands have no hooks to the left of them in line 2 of that glyph, so can correctly reference `list2[0]` that was assigned in the first glyph:","pinned":false,"hidden":false,"mode":"md"},{"id":600,"value":"

\n1 ╵ ╵ ╮╮╮╮╮\n2 ╰──╮ ╷╷╷╷╷ ╷\n3 ╰──── ╷\n

Fig. 2.11: Two glyphs: A value strand and five reference strands.

\n","pinned":false,"hidden":false,"mode":"md"},{"id":871,"value":"Because we often want to reference cells other than at position 0 in a list, it is common to insert 'add zero' data strands to the left of a reference hook or marker. Adding zero has no direct effect on a list, so allows us to insert 'no-op' placeholder hooks to the left of a reference strand. And because zero data strands are often helpful, it's worth recognising some common forms they may take. Below are some minimal zero data strands with hooks on lines 1, 2, 3, 5 and 7. Note the symmetry giving a pair of options for each line and that the lower the hook line (larger prime numbers), the longer the strand has to be to balance positive and negative horizontal dashes.","pinned":false,"hidden":false,"mode":"md"},{"id":873,"value":"$3a","pinned":false,"hidden":false,"mode":"md"},{"id":1220,"value":"Now that we can build lists of numbers with data strands, the [next section](https://observablehq.com/@jwolondon/rivulet-action-strands) considers what we can do with those lists with _action strands_.","pinned":false,"hidden":false,"mode":"md"},{"id":1232,"value":"[Action Strands](https://observablehq.com/@jwolondon/rivulet-action-strands)","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":"$W3b","stdlib":"1","titling":"auto"}