@@ -4,72 +4,85 @@ navhome: /docs/
44
55
66# 1b: tree addressing
7+
8+Check out the Nock [explanation](docs/nock/explanation/) for more
9+information on the tree-addressing system.
10+
711### `++cap`
812
913Tree head
1014
11−Tests whether an `a` is in the head or tail of a noun. Produces the
12−cube `%2` if it is within the head, or the cube `%3` if it is
13−within the tail.
15+Tests whether the tree address `a` is in the head or the tail of a noun.
16+Produces the constant atom `%2` if it is within the head (subtree `+2`), or
17+the constant atom `%3` if it is within the tail (subtree `+3`).
18+
1419
15−Accepts
16−-------
20+#### Accepts
1721
1822`a` is an atom.
1923
20−Produces
21−--------
24+#### Produces
2225
23−A cube.
26+A constant atom.
2427
25−Source
26−------
28+#### Source
2729
28− ++ cap :: tree head
30+ ++ cap
2931 ~/ %cap
3032 |= a=@
31− ^- ?(%2 %3)
33+ ^- ?($2 $3)
3234 ?- a
33− %2 %2
34− %3 %3
35+ $2 %2
36+ $3 %3
3537 ?(%0 %1) !!
3638 * $(a (div a 2))
3739 ==
38− ::
3940
40−Examples
41−--------
41+
42+#### Examples
4243
4344 > (cap 4)
4445 %2
46+
4547 > (cap 6)
4648 %3
49+
4750 > (cap (add 10 9))
4851 %2
4952
53+ > (cap 1) ::address '1' is in neither the head nor the tail
54+ ! exit
55+
56+ > (cap 0x40))
57+ %2
58+ > `@`0x40
59+ 64
60+
61+ > (cap 'a')
62+ %3
63+ > `@`'a'
64+ 97
5065
5166
5267***
5368### `++mas`
5469
55−Axis within head/tail?
70+Address within head/tail
5671
57−Computes the axis of `a` within either the head or tail of a noun (depends whether `a` lies within the the head or tail).
72+Computes the tree address of atom `a` within either the head (`+2`) or tail
73+(`+3`) of a noun.
5874
59−Accepts
60−-------
75+#### Accepts
6176
62−`a` is an [atom]().
77+`a` is an atom.
6378
64−Produces
65−--------
79+#### Produces
6680
6781An atom.
6882
69−Source
70−------
83+#### Source
7184
72− ++ mas :: tree body
85+ ++ mas
7386 ~/ %mas
7487 |= a=@
7588 ^- @
@@ -79,69 +92,170 @@ Source
7992 3 1
8093 * (add (mod a 2) (mul $(a (div a 2)) 2))
8194 ==
82− ::
8395
84−Examples
85−--------
96+
97+#### Examples
8698
8799 > (mas 3)
88100 1
101+
89102 > (mas 4)
90103 2
104+
91105 > (mas 5)
92106 3
93− > (mas 6)
94− 2
95− > (mas 0)
96− ! exit
107+ > (cap 5) ::`(cap a)` computes whether address `a` is in the head or the tail
108+ %2
109+
110+ > (mas 7)
111+ 3
112+ > (cap 7)
113+ %3
114+
115+ > (mas 11)
116+ 7
117+
118+ > (mas (mas 11))
119+ 3
120+
121+ > (cap (mas 6))
122+ %3
123+
124+ > (mas 0)
125+ ! exit ::address `0` is in neither the head nor the tail
126+
97127 > (mas 1)
98− ! exit
128+ ! exit ::address `1` is in neither the head nor the tail
129+
130+
131+#### Discussion
132+
133+
134+ 1
135+ / \
136+ / \
137+ 2 3 <--here are the head (`+2`) and the tail (`+3`)
138+ / \ /\
139+ 4 5 6 7
140+ /\ /\ /\ /\
141+ (continues...)
99142
143+Running `(mas 7)` in the Dojo will return `3`, because address `+3` is what
144+`+7` now occupies. The tree below helps illustrate the relationship. With
145+parentheses are `a` values (if `a` is in subtree `+3`), and without parentheses
146+are the values returned with `(mas a)`.
100147
148+ 1(3) ::new/(old) addresses
149+ / \
150+ 2 3
151+ (6) (7)
152+ / \ /\
153+ / \ / \
154+ 4 5 6 7
155+ (12) (13) (14) (15)
156+ / \ / \ / \ / \
157+ (continues...)
158+
159+Notice how the old values in the head (subtree `+2`) were not illustrated in
160+this case, because `+7` is within the tail (subtree `+3`).
101161
102162***
103163### `++peg`
104164
105−Axis within axis
165+Address within address
106166
107−Computes the axis of `b` within axis `a`.
167+Computes the absolute address of `b`, a relative address within the subtree
168+`a`.
108169
109−Accepts
110−-------
170+#### Accepts
111171
112172`a` is an atom.
113173
114174`b` is an atom.
115175
116−Produces
117−--------
176+#### Produces
118177
119178An atom.
120179
121−Source
122−------
180+#### Source
123181
124− ++ peg :: tree connect
182+ ++ peg
125183 ~/ %peg
126− |= {a/@ b/@}
127− ^- @
128− ?- b
184+ |= [a=@ b=@]
185+ ?< =(0 a)
186+ ^- @
187+ ?- b
129188 $1 a
130189 $2 (mul a 2)
131190 $3 +((mul a 2))
132191 * (add (mod b 2) (mul $(b (div b 2)) 2))
133192 ==
134193
135−Examples
136−--------
194+#### Examples
195+
196+ > (peg 4 1)
197+ 4
137198
138− > (peg 4 1)
199+ > (peg 1 4)
139200 4
140− > (peg 4 2)
201+
202+ > (peg 4 2)
141203 8
142− > (peg 8 45)
204+
205+ > (peg 4 8)
206+ 32
207+
208+ > (peg 4 (4 2))
209+ 32
210+
211+ > (peg 8 45)
143212 269
144213
214+ > (cap (peg 4 2)) ::`(cap a)` computes whether address `a` is in the head or the tail
215+ %2
216+
217+
218+#### Discussion
219+
220+In other words, the subtree at address `a` is treated as a tree in its own
221+right (starting with root `+1`, head `+2`, and tail `+3`). Relative address
222+`b` is found with respect to `a`, and then its absolute address, within the
223+greater tree, is returned.
224+
225+Running `(peg 3 4)` in the Dojo, for example, will return `12`. Looking at
226+a tree diagram makes it easy to see why.
227+
228+ 1
229+ / \
230+ / \
231+ / \
232+ 2 3 <- here is the subtree `+3`. The subtree address is `a` in `(peg a b)`
233+ / \ / \
234+ / \ / \
235+ 4 5 6 7
236+ / \ / \ / \ / \
237+ 8 9 10 11 12 13 14 15
238+ /\ /\ /\ /\ /\ /\ /\ /\
239+ (continues...)
240+
241+
242+When we consider subtree at address `+3` by itself, it has relative addresses
243+that are structured in the same way as its parent tree's absolute addresses.
244+The absolute addresses are given in parentheses in the diagram below.
245+Notice how relative address `+4` is at the same position as absolute address
246+`+12`.
247+
248+ 1(3) ::new/(old) addresses
249+ / \
250+ 2 3
251+ (6) (7)
252+ / \ /\
253+ / \ / \
254+ 4 5 6 7
255+ (12) (13) (14) (15)
256+ / \ / \ / \ / \
257+ (continues...)
258+
145259
146260
147261***