2c:null 2d:["$","title",null,{"children":"1. Introduction to Rivulet | Jo Wood | Observable"}] 32:T3b58,33:T451,[Rivulet](https://github.com/rottytooth/Rivulet) is an [esolang](https://esolangs.org/wiki/Esoteric_programming_language) ('esoteric language') written by [Daniel Temkin](https://github.com/rottytooth) that uses gylphs to represent programming instructions. While it would not be a practical basis for most programming tasks, it does represent an interesting space between text-encoded programming languages and graphically encoded data visualization. As a language it invites careful thought about 'code layout', as its design offers much more flexibility in visual form than most languages. It encourages us to consider the role that design choices and aesthetics play in helping construct visual schemata. It challenges notions of 'efficiency' in the construction and interpretation of computer code, much like the [Atypography movement](https://www.atypography.com) does with text. These pages introduce the language and then explore some ideas around visual encoding (expressiveness) and decoding (effectiveness), giving us some insights around the schemata we construct from visual representations.34:T1197,

╵ ╰─ ╮╰─╮ ╮ ╮ ╮ ╵ ─╮ ╰─ ╰─╰──╰─╮ │ ──╮ ─╮ │╭── ╰─╰── ╷╰───╰────╯╰───╯╰──╰──╯╯ ╷ ╵ ╭─╯╮ ╭─╯╭─ ╮ ╭─╯╭─ ╮ ╭─╯╭─ ╮ ╭─╯╭─ ╮ ╭─╯╭─ ╮ ╭─╯ │╭─╯╭─╯ │╭─╯╭─╯ │╭─╯╭─╯ │╭─╯╭─╯ │╭─╯╭─╯ │ ╰─ ╴╯╰─ ╰─╯ ╴╯╰─ ╰─╯ ╴╯╰─ ╰─╯ ╴╯╰─ ╰─╯ ╴╯╰─ ╰─╯ ╴╯ ╭ ╭ ╭ ╭ ╭ │ │ │ │ │ ╷

Fig. 1.3: A Rivulet program that zips two lists together

35:T8be,rivFormat = () => html``36:[] 30:{"id":"dbfe40931519d0b6","slug":"rivulet-intro","title":"1. Introduction to Rivulet","thumbnail":"68b6a8de2354072c989be5bbc25c8e8a16c7c1bcf48761a224e1969c3132a368","access_level":"public","create_time":"$D2025-05-20T15:32:36.013Z","update_time":"$D2025-08-13T04:11:59.466Z","view_time":null,"first_public_time":"$D2025-06-15T06:15:34.548Z","fork":false,"stars":8,"starred":false,"owner":{"type":"team","id":"9461f58b209074d5","login":"jwolondon","name":"Jo Wood","avatar_url":"https://avatars-next.observableusercontent.com/27f72cecd1ac20853a533421fab228ce5f611cbc0986c1e420f7d3b1eb49ef50","tier":"starter_2024"},"version":1404,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"e2432cc13dc447d3","login":"jwolondon","name":"Jo Wood","avatar_url":"https://avatars-next.observableusercontent.com/27f72cecd1ac20853a533421fab228ce5f611cbc0986c1e420f7d3b1eb49ef50","tier":null}],"members":[{"type":"individual","id":"e2432cc13dc447d3","login":"jwolondon","name":"Jo Wood","avatar_url":"https://avatars-next.observableusercontent.com/27f72cecd1ac20853a533421fab228ce5f611cbc0986c1e420f7d3b1eb49ef50","tier":null,"role":"editor"},{"type":"team","id":"9461f58b209074d5","login":"jwolondon","name":"Jo Wood","avatar_url":"https://avatars-next.observableusercontent.com/27f72cecd1ac20853a533421fab228ce5f611cbc0986c1e420f7d3b1eb49ef50","tier":"starter_2024","role":"viewer"}],"comments":[{"id":"020aac77a39059f0","reply_to_id":null,"content":"Have you already attempted to run rivulet via Pyodide, by any chance?","create_time":"$D2025-06-15T10:32:47.955Z","update_time":null,"resolved":true,"user":{"type":"individual","id":"07362516b5994994","login":"mootari","name":"Fabian Iwand","avatar_url":"https://avatars-next.observableusercontent.com/0d7defa821f38094c03bad23b9b360a5364e6e97e21fc238c39ddc48db7994ad","tier":null}},{"id":"87888134400ee0be","reply_to_id":"020aac77a39059f0","content":"I haven't yet. Rivulet is under active development from Daniel at the moment (it's only been around for a couple of months). I am not a Python programmer, so I don't know how easy the port would be, especially if we'd need to update several times a week at the moment. Any advice welcome.","create_time":"$D2025-06-15T10:53:47.601Z","update_time":null,"resolved":true,"user":{"type":"individual","id":"e2432cc13dc447d3","login":"jwolondon","name":"Jo Wood","avatar_url":"https://avatars-next.observableusercontent.com/27f72cecd1ac20853a533421fab228ce5f611cbc0986c1e420f7d3b1eb49ef50","tier":null}}],"custom_thumbnail":true,"trashed":false,"subscribed":null,"forks":2,"collection":{"id":"b719155d9d613f18","slug":"rivulet","title":"Rivulet","owner":{"id":"9461f58b209074d5","login":"jwolondon","name":"Jo Wood"}},"type":"notebook","body":{"title":"1. Introduction to Rivulet","cells":[{"id":0,"value":"# 1. Introduction to Rivulet","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":316,"value":"$32","pinned":false,"hidden":false,"mode":"html","author":"$undefined","summary":"$undefined"},{"id":5,"value":"$33","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":9,"value":"## 1.1 Installation\n\nYou don't have to have a Rivulet interpreter to explore the ideas on these pages, but it can help, especially if you want to experiment. The interpreter is written in Python and accessible via the command line. Assuming you have git and at least Python 3.12 installed on your system, the following should allow you to install and run it:\n\n```zsh\ngit clone https://github.com/rottytooth/Rivulet\ncd Rivulet\npython -m pip install -r requirements.txt\npython -m pip install -e . \n```\n\nTo test the interpreter with some of the sample code:\n\n```zsh\nriv -o unicode programs/hello.riv\n```\n\nwhich, if successful, should display the text `HELLO WORLD!`\n\nFor the full set of interpreter command-line options, type \n\n```\nriv --help\n```\n","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":754,"value":"Rivulet files are simply text files containing character symbols. You can create these with a normal text editor or with my [rivulet editor](https://observablehq.com/@jwolondon/rivulet-editor) that makes the task a little easier.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":164,"value":"## 1.2 The Rivulet language\n\nRivulet is a list-based language. Meaning it applies operations on ordered lists of numbers. It is constructed by assembling line-based characters (the _lexemes_ of the language) that are joined together to form linear strands. For easy reference, here's the complete lexeme set:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":422,"value":"

\n ╴ ╭─╮\n ╵╷│ \n ╶ ╰ ╯\n

","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":763,"value":"Lexemes are considered connected if they are adjacent to another with the same line direction at the adjoining edge. Note that some lexemes have a small gap in their dominant direction: `╴` `╵` `╶` `╷`, but can still be considered connected to an adjacent lexeme. For example, below the lexemes on the left form ten connected pairs, but the ones on the right do not:\n\n

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

Fig. 1.1: Left: 10 connected pairs of lexemes; right: unconnected lexemes.

\n","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":374,"value":"Code is expressed as a sequence of _strands_ – meandering lines of connected lexemes that encode instructions to manipulate lists. Many strands have a _hook_ at one end that looks like a corner with a short open end. Spotting these hooks is important because they determine both what its strand does and the order in which strands are interpreted.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":1268,"value":"

\n ╮ │ ╰── ╭ │ ──╮\n │ ╯ ──╯ │ ╰ ╭──\n

Fig. 1.2: Pairs of strand hooks pointing left, up, right and down.

\n","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":179,"value":"_In these pages, lexemes that make up the strands are coloured by strand type and shown as slightly separated with an alternating line background colour. More typically they are displayed as continuous connected strands on a plain background such as the top image on this page._","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":1288,"value":"Multiple strands can be associated together as a _glyph_ which is indicated by a starting glyph marker (one or more `╵` lexemes) at the top-left of the strands and an end glyph marker `╷` at the bottom-right.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":1266,"value":"In the example Rivulet program below (which takes two lists and interleaves them into a single list), there are three glyphs – each one between a pair of grey `╵` `╷` glyph markers. Within the glyphs every strand has a hook either pointing up or left (the top two rows of strands), or to the right (the bottom blue row of strands).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":1214,"value":"$34","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":1212,"value":"There are several types of strand, determined by the presence/absence and direction of the strand's hook and sometimes its position relative to other strands. ","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":1314,"value":"_A note about glyph style:_ In most of the examples in this tutorial, I am adopting a parsimonious style of strand design and layout. As we shall see, Rivulet allows the same strand to be drawn in many different ways, which is part of the appeal of the language. This allows us to create elaborate intertwined maze-like glyphs that have an intrinsic aesthetic appeal. But such designs may be harder to decode, especially as you learn the language. For these tutorial pages, I am instead using shorter more grid-like arrangements to emphasise the function of different strands. As you become more comfortable with creating glyphs, a rewarding part of the design process becomes the interplay of traditional coding/algorithm creation with visually appealing strand layout.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":1312,"value":"In the [next section](https://observablehq.com/@jwolondon/rivulet-data-strands) we will consider the first category of strands used for storing numeric values – _data strands_.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":1304,"value":"[Data Strands](https://observablehq.com/@jwolondon/rivulet-data-strands)","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":76,"value":"---\n\n## Appendices","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":1185,"value":"_For formatting Rivulet code snippets:_","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined"},{"id":78,"value":"$35","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":1192,"value":"rivFormat()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined"},{"id":1362,"value":"","pinned":false,"hidden":false,"mode":"html","author":"$undefined","summary":"$undefined"}],"files":"$W36","stdlib":"1","titling":"auto"}} 31:"$30:body"