git.iko.soy/urbit.org
on 3fee830 help sign in
urbit.org/docs/programming/twig/flow.md
143 lines 4.1 kB history raw
1---
2sort: 5
3---
5# Subject flow (`=` runes)
7Flow twigs change the subject. (Or more precisely, a flow twig
8compiles at least one of its subtwigs with a different subject.)
9All non-flow twigs (except cores) pass the subject down unchanged.
11## Overview
13The simplest way to change the subject is to compose two twigs,
14`p` and `q`. Let `x` be `(mint subject p)`, with product span
15`p.x` and nock formula `q.x`. Let `y` be `(mint p.x q)`. Then
16their composition is `[p.y [7 q.x q.y]]`.
18This composition is the `$per` twig. A close relative is `$pin`,
19which is `$per` over `[p .]`. The new subject is a cell of `p`
20and the old subject. `$pin` is the simplest Hoon equivalent of
21"declaring a variable" (introducing new data into the subject).
23Another way to change the subject is to mutate it. With the
24`$set` twig, given a wing that resolves to a leg, we can write
25instead of reading, *installing* a new value at that leg. Of
26course, we are creating a copy, not modifying the original.
28## Structures
30### `taco`: name with optional filling
32A `taco` is either a symbol or a symbol-mold cell. The mold is a
33typecheck and cast. For instance, when "initializing a variable"
34with `:var`, we can cast the inferred type of the initial value
35to match an explicit `taco` mold, or just state the symbol and
36use the inferred type.
38The `taco` syntax is `foo` for the symbol foo, or `foo/bar` for
39symbol `foo` and mold `bar`.
41## Definitions
43The rune prefix is `=`. Suffixes: `>` for `:per`, `<` for
44`:rap`, `+` for `:pin`, `-` for `:nip`, `|` for `:new`, `/` for
45`:var`, `;` for `:rev`, `.` for `:set`, and `^` for `:sip`.
47### `:per`, `=>`, "tisgar", `{$per p/twig q/twig}`, "compose"
49The product: `q`, compiled against the product of `p`.
51Intuitively: uses `p` as the subject of `q`.
53### `:rap`, `=<`, "tisgal", `{$rap p/twig q/twig}`, "reverse compose"
55Expands to: `:per(q p)`
57Intuitively: reverse of `:per`.
59### `:pin`, `=+`, "tislus", `{$pin p/twig q/twig}`, "work with"
61Expands to: `:per(:cons(p .) q)`
63Intuitively: uses `[p subject]` as the subject of `q`.
65### `:nip`, `=-`, "tishep", `{$nip p/twig q/twig}`, "work over"
67Expands to: `:pin(q p)`
69Intuitively: reverse of `:pin`.
71### `:var`, `=/`, "tisfas", `{$var p/taco q/twig r/twig}, "with variable"
73Expands to: `?@(p :pin(:name(p q) r) :pin(:cast(:(coat p) q) r)`
75Intuitively: uses `[p=q subject]` as the subject of `r`. If `p`
76contains a mold, cast `q` to that mold.
78### `:rev`, `=;`, "tissem", `{$var p/taco q/twig r/twig}, "over variable"
80Expands to: `:var(p r q)`
82Intuitively: reverse of `:var`.
84### `:new`, `=|`, "tisbar", `{$new p/moss q/twig}`, "with blank"
86Expands to: `:pin(:per($ p) q)`
88Intuitively: pin the default value of `p`.
90### `:set`, `=.`, "tisdot", `{$set p/wing q/twig r/twig}`, "mutate"
92The product: `r`, compiled against a version of the subject
93with wing `p` modified to the product of `q`.
95Intuitively: `r` with `p` set to `q`. Almost an assignment.
97### `:sip`, `=^`, "tisket", `{$sip p/taco q/wing r/twig s/twig}`, "advance"
99The product is `s`, compiled against a version of the subject
100in which the head of `r` is bound to variable `p`, and the tail
101of `r` is assigned into the wing `q`.
103Intuitively: `r` produces a cell; we pin the head and install the
104tail.
106Whyuppose we have a state machine with a function that
107produces a cell, whose head is a result and whose tail is a new
108state. We want to use the head as a new variable, and stuff the
109tail back into wherever we stored the old state. This may also
110remind you of Haskell's State monad.
112## Irregular forms
114### Infix colon, p:q
116Not to be confused with the wing `p.q`. Translation:
117```
118p:q:r :rap(p :rap(q r))
119```
121## Structures
123Using a mold syntax we haven't learned yet:
125```
126|%
127++ taco
128 ?@(term {term moss})
129::
130++ twig
131 {$per p/twig q/twig}
132 {$rap p/twig q/twig}
134 {$pin p/twig q/twig}
135 {$nip p/twig q/twig}
137 {$new p/moss q/twig}
138 {$var p/taco q/twig r/twig}
139 {$rev p/taco q/twig r/twig}
140 {$set p/wing q/twig r/twig}
141 {$sip p/taco q/wing r/twig s/twig}
142--
143```