@@ -4,25 +4,45 @@ weight = 13
44template = "doc.html"
55+++
66
7−### `++ja`
7+## `++ja`
88
99Jar engine
1010
11−```hoon
12− |_ a=(jar)
13−```
11+A container arm for `jar` operation arms. A `jar` is a `map` of
12+`list`s. The contained arms inherit the sample jar.
1413
15−A container arm for `++jar` operation arms. A `++jar` is a `++map` of
16−`++list`s. The contained arms inherit the sample jar.
14+#### Accepts
1715
1816`a` is a jar.
1917
18+#### Produces
19+
20+A core.
21+
22+#### Source
23+
24+```hoon
25+++ ja
26+ =| a=(tree (pair * (list))) :: (jar)
27+ |@
28+```
29+
30+#### Examples
31+
2032```
2133> ~(. ja (my [a+1 b+2 ~]))
2234< 2.ngd
23− [ a=?(%~ [n=[?(p=%a p=%b) q=@ud] l=nlr([p=?(%a %b) q=@ud]) r=nlr([p=?(%a %b) q=@ud])])
24− <123.zao 45.xig 1.pnw %140>
35+ [ a
36+ ?(
37+ %~
38+ [ n=[?(p=%a p=%b) q=@ud]
39+ l=nlr([p=?(%a %b) q=@ud])
40+ r=nlr([p=?(%a %b) q=@ud])
41+ ]
42+ )
43+ <123.zao 46.hgz 1.pnw %140>
2544 ]
45+>
2646```
2747
2848---
@@ -31,37 +51,41 @@ A container arm for `++jar` operation arms. A `++jar` is a `++map` of
3151
3252Grab value by key
3353
34−```hoon
35− ++ get :: gets list by key
36− |* b=*
37− =+ c=(~(get by a) b)
38− ?~(c ~ u.c)
39−```
54+Produces the list at key `b` in jar `a`.
4055
4156#### Accepts
4257
43−`a` is a `++jar`.
58+`a` is a `jar`, and is the sample of `+ja`.
4459
45−`b` is a key of the same type as the keys in `a`.
60+`b` is a noun.
4661
4762#### Produces
4863
49−A list retrieved from jar `a` using the key `b`.
64+A `list`.
5065
51−Examples
66+#### Source
5267
68+```hoon
69+++ get
70+ |* b=*
71+ =+ c=(~(get by a) b)
72+ ?~(c ~ u.c)
5373```
54−> =l (my [['a' (ly 1 2 3 ~)] ['b' (ly 4 5 6 ~)]~])
55−> l
56−[n=[p='b' q=[i=4 t=~[5 6]]] l={} r={[p='a' q=[i=1 t=~[2 3]]]}]
5774
58−> (~(get ja l) 'a')
59−[i=1 t=[i=2 t=~[3]]]
75+#### Examples
6076
61−> (~(get ja l) 'b')
62−[i=4 t=[i=5 t=~[6]]]
77+```
78+> =j `(jar @t @ud)`(malt ~[['a' `(list @ud)`~[1 2 3]] ['b' `(list @ud)`~[4 5 6]]])
79+> j
80+{[p='b' q=~[4 5 6]] [p='a' q=~[1 2 3]]}
81+
82+> `(list @ud)`(~(get ja j) 'a')
83+~[1 2 3]
6384
64−> (~(get ja l) 'c')
85+> `(list @ud)`(~(get ja j) 'b')
86+~[4 5 6]
87+
88+> `(list @ud)`(~(get ja j) 'c')
6589~
6690```
6791
@@ -71,114 +95,166 @@ Examples
7195
7296Prepend to list
7397
74−#### Source
75−
76−```hoon
77− ++ add :: adds key-list pair
78− |* [b=* c=*]
79− =+ d=(get b)
80− (~(put by a) b [c d])
81−```
98+Adds `c` to the head of the list at key `b` in jar `a`. If `b` does not exist in `a`, a new key-value pair is added with a list containing `c`.
8299
83100#### Accepts
84101
85−`a` is a jar.
102+`a` is a `jar`, and is the sample of `+ja`.
86103
87−`b` is a key of the same type as the keys in `a`.
104+`b` is a noun of the same type as the keys in `a`.
88105
89−`c` is a value of the same type as the values in `a`.
106+`c` is a noun of the same type the lists in `a` contain.
107+
108+#### Produces
109+
110+A `jar`.
111+
112+#### Source
113+
114+```hoon
115+++ add
116+ |* [b=* c=*]
117+ =+ d=(get b)
118+ (~(put by a) b [c d])
119+```
90120
91121#### Examples
92122
93123```
94−> =l (my [['a' (ly 1 2 3 ~)] ['b' (ly 4 5 6 ~)]~])
95−> l
96−[n=[p='b' q=[i=4 t=~[5 6]]] l={} r={[p='a' q=[i=1 t=~[2 3]]]}]
97−> (~(add ja l) 'a' 100)
98−[ n=[p='b' q=[i=4 t=[i=5 t=~[6]]]]
99− l=~
100− r=[n=[p='a' q=[i=100 t=[i=1 t=~[2 3]]]] l=~ r=~]
101−]
102−> (~(add ja l) 'a' 100)
103−[n=[p='b' q=[i=4 t=[i=5 t=~[6]]]] l=~ r=[n=[p='a' q=[i=100 t=[i=1 t=~[2 3]]]] l=~ r=~]]
104−> (~(add ja l) 'b' 7)
105−[n=[p='b' q=[i=7 t=[i=4 t=~[5 6]]]] l=~ r=[n=[p='a' q=[i=1 t=[i=2 t=~[3]]]] l=~ r=~]]
106−> (~(add ja l) 'c' 7)
107−[ n=[p='b' q=[i=4 t=[i=5 t=~[6]]]]
108− l=~
109− r=[n=[p='c' q=[i=7 t=~]] l=[n=[p='a' q=[i=1 t=~[2 3]]] l={} r={}] r=~]
110−]
111−> (~(add ja l) 'c' (ly 7 8 9 ~))
112−mull-grow
113−mull-nice
124+> =j `(jar @t @ud)`(malt ~[['a' `(list @ud)`~[1 2 3]] ['b' `(list @ud)`~[4 5 6]]])
125+> j
126+{[p='b' q=~[4 5 6]] [p='a' q=~[1 2 3]]}
127+
128+> `(jar @t @ud)`(~(add ja j) 'b' 7)
129+{[p='b' q=~[7 4 5 6]] [p='a' q=~[1 2 3]]}
130+
131+> `(jar @t @ud)`(~(add ja j) 'c' 8)
132+{[p='b' q=~[4 5 6]] [p='a' q=~[1 2 3]] [p='c' q=~[8]]}
114133```
115134
116−\*\*
135+---
117136
118−### `++ju`
137+## `++ju`
119138
120139Jug operations
121140
141+Container arm for jug operation arms. A `jug` is a `map` of
142+`set`s. The contained arms inherit its sample jug, `a`.
143+
144+#### Accepts
145+
146+`a` is a `jug`.
147+
148+#### Produces
149+
150+A core.
151+
152+#### Source
153+
122154```hoon
123− ++ ju :: jug engine
124− |/ a=(jug)
155+++ ju
156+ =| a=(tree (pair * (tree))) :: (jug)
157+ |@
125158```
126159
127−Container arm for jug operation arms. A `++jug` is a `++map` of
128−`++sets`. The contained arms inherit its sample jug, `a`.
129−
130−`a` is a jug.
160+#### Example
131161
132162```
133−> ~(. ju (my [[a (sy 1 ~)] [b (sy 2 ~)] ~]))
134−< 5.cws
135− [ a
136− ?(
137− %~
138− [ n=[p=@ub ?(q=%~ q=[?(n=@ud #!) l=nlr(?(@ud #!)) r=nlr(?(@ud #!))])]
139− l=nlr([p=@ub q=?(%~ [?(n=@ud #!) l=nlr(?(@ud #!)) r=nlr(?(@ud #!))])])
140− r=nlr([p=@ub q=?(%~ [?(n=@ud #!) l=nlr(?(@ud #!)) r=nlr(?(@ud #!))])])
141− ]
142− )
143− <123.zao 45.xig 1.pnw %140>
144− ]
163+> =j `(jug @t @ud)`(malt ~[['a' (silt ~[1 2 3])] ['b' (silt ~[4 5 6])]])
164+> j
165+{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
166+
167+> ~(. ju j)
168+<5.cws [a=nlr([p=@t q=nlr(@ud)]) <123.zao 46.hgz 1.pnw %140>]>
145169```
146170
171+---
172+
147173### `++del:ju`
148174
149175Remove
150176
177+Produces jug `a` with value `c` removed from set located at key `b`.
178+
179+#### Accepts
180+
181+`a` is a jug, and is the sample of `+ju`.
182+
183+`b` is a noun of the same type as the keys in `a`.
184+
185+`c` is a noun of the same type as the sets in `a` contain.
186+
151187#### Source
152188
153189```hoon
154− ++ del :: del key-set pair
155− |* [b=* c=*]
156− ^+ a
157− =+ d=(get b)
158− =+ e=(~(del in d) c)
159− ?~ e
160− (~(del by a) b)
161− (~(put by a) b e)
190+++ del
191+ |* [b=* c=*]
192+ ^+ a
193+ =+ d=(get b)
194+ =+ e=(~(del in d) c)
195+ ?~ e
196+ (~(del by a) b)
197+ (~(put by a) b e)
162198```
163199
164−Produces jug `a` with value `c` removed from set located at key `b`.
200+#### Examples
165201
166−`a` is a jug.
202+```
203+> j
204+{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
167205
168−`b` is a key of the same type as the keys in `a`.
206+> `(jug @t @ud)`(~(del ju j) 'b' 6)
207+{[p='b' q={5 4}] [p='a' q={1 2 3}]}
169208
170−`c` is the value of the same type of the keys in `a` that is to be
171−removed.
209+> `(jug @t @ud)`(~(del ju j) 'b' 10)
210+{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
172211
212+> `(jug @t @ud)`(~(del ju j) 'c' 10)
213+{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
173214```
174− > s
175− [[p='a' q={1 3 2}] [p='b' q={5 4 6}]}
176215
177− > (~(del ju s) 'a' 1)
178− {[p='a' q={3 2}] [p='b' q={5 4 6}]}
216+---
217+
218+### `++gas:ju`
219+
220+Concatenate
221+
222+Add each of the key-value pairs in list `b` to jug `a`. The values in `b` are the type the sets in `a` contain. For keys in `b` that exist in `a`, the values will be added to their sets. For keys in `b` that don't exist in `a`, new keys and sets will be added.
223+
224+#### Accepts
225+
226+`a` is a `jug`, and is the sample of `+ju`.
179227
180− > (~(del ju s) 'c' 7)
181− {[p='a' q={1 3 2}] [p='b' q={5 4 6}]}
228+`b` is a `(list [p q])`, where:
229+
230+- `p` is a noun, the type of the keys in `a`.
231+- `q` is a noun, the type the sets in `a` contain.
232+
233+#### Produces
234+
235+A `jug`.
236+
237+#### Source
238+
239+```hoon
240+++ gas
241+ |* b=(list [p=* q=*])
242+ => .(b `(list _?>(?=([[* ^] ^] a) [p=p q=n.q]:n.a))`b)
243+ |- ^+ a
244+ ?~ b
245+ a
246+ $(b t.b, a (put p.i.b q.i.b))
247+```
248+
249+#### Examples
250+
251+```
252+> =j `(jug @t @ud)`(malt ~[['a' (silt ~[1 2 3])] ['b' (silt ~[4 5 6])]])
253+> j
254+{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
255+
256+> `(jug @t @ud)`(~(gas ju j) ~[['a' 10] ['a' 42] ['b' 999] ['c' 7]])
257+{[p='b' q={5 6 4 999}] [p='a' q={10 42 1 2 3}] [p='c' q={7}]}
182258```
183259
184260---
@@ -187,28 +263,42 @@ removed.
187263
188264Retrieve set
189265
266+Produces a set retrieved from jar `a` using key `b`.
267+
268+#### Accepts
269+
270+`a` is a jar, and the sample of `+ju`.
271+
272+`b` is key, a noun of the same type as the keys in `a`.
273+
274+#### Produces
275+
276+A `set`.
277+
278+#### Source
279+
190280```hoon
191− ++ get :: gets set by key
192− |* b=*
193− =+ c=(~(get by a) b)
194− ?~(c ~ u.c)
281+++ get
282+ |* b=*
283+ =+ c=(~(get by a) b)
284+ ?~(c ~ u.c)
195285```
196286
197−Produces a set retrieved from jar `a` using key `b`.
287+#### Examples
198288
199−`a` is a jar.
289+```
290+> =j `(jug @t @ud)`(malt ~[['a' (silt ~[1 2 3])] ['b' (silt ~[4 5 6])]])
291+> j
292+{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
200293
201−`b` is a key of the same type as the keys in `a`.
294+> `(set @ud)`(~(get ju j) 'a')
295+{1 2 3}
202296
203−```
204− > s
205− {[p='a' q={1 3 2}] [p='b' q={5 4 6}]}
206− > (~(get ju s) 'a')
207− {1 3 2}
208− > (~(get ju s) 'b')
209− {5 4 6}
210− > (~(get ju s) 'c')
211− ~
297+> `(set @ud)`(~(get ju j) 'b')
298+{5 6 4}
299+
300+> `(set @ud)`(~(get ju j) 'c')
301+{}
212302```
213303
214304---
@@ -217,37 +307,45 @@ Produces a set retrieved from jar `a` using key `b`.
217307
218308Check contents
219309
310+Computes whether a value `c` exists within the set located at key `b`
311+with jug `a`, producing a flag.
312+
313+#### Accepts
314+
315+`a` is a `jug`, and the sample of `+ju`.
316+
317+`b` is a noun of the same type as the keys in `a`.
318+
319+`c` is a noun of the same type as the sets in `a` contain.
320+
321+#### Produces
322+
323+A `?`.
324+
325+#### Source
326+
220327```hoon
221− ++ has :: existence check
222− |* [b=* c=*]
223− ^- ?
224− (~(has in (get b)) c)
328+++ has
329+ |* [b=* c=*]
330+ ^- ?
331+ (~(has in (get b)) c)
225332```
226333
227−Computes whether a value `c` exists within the set located at key `b`
228−with jar `a`. Produces a loobean.
334+#### Examples
229335
230−`a` is a set.
336+```
337+> =j `(jug @t @ud)`(malt ~[['a' (silt ~[1 2 3])] ['b' (silt ~[4 5 6])]])
338+> j
339+{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
231340
232−`b` is a key as a noun.
341+> (~(has ju j) 'b' 5)
342+%.y
233343
234−`c` is a value as a noun.
344+> (~(has ju j) 'b' 10)
345+%.n
235346
236−```
237− > s
238− {[p='a' q={1 3 2}] [p='b' q={5 4 6}]}
239− > (~(has ju s) 'a' 3)
240− %.y
241− > (~(has ju s) 'b' 6)
242− %.y
243− > (~(has ju s) 'a' 7)
244− %.n
245− > (~(has jus s) 'c' 7)
246− ! -find-limb.jus
247− ! find-none
248− ! exit
249− > (~(has ju s) 'c' 7)
250− %.n
347+> (~(has ju j) 'c' 10)
348+%.n
251349```
252350
253351---
@@ -256,34 +354,44 @@ with jar `a`. Produces a loobean.
256354
257355Add key-set pair
258356
259−```hoon
260− ++ put :: add key-set pair
261− |* [b=* c=*]
262− ^+ a
263− =+ d=(get b)
264− (~(put by a) b (~(put in d) c))
265−```
357+Produces jug `a` with `c` added to the set located at key `b`. If `b` isn't a key in `a`, it will be added and a new set created containing `c`.
358+
359+#### Accepts
266360
267−Produces jar `a` with `c` added to the set value located at key `b`.
361+`a` is a `jug`.
268362
269−`a` is a set.
363+`b` is a noun, the type of the keys in `a`.
270364
271−`b` is a key as a noun.
365+`c` is a noun, the type the sets in `a` contain.
272366
273−`c` is a value.
367+#### Produces
368+
369+A `jug`.
370+
371+#### Source
372+
373+```hoon
374+++ put
375+ |* [b=* c=*]
376+ ^+ a
377+ =+ d=(get b)
378+ (~(put by a) b (~(put in d) c))
379+```
380+
381+#### Examples
274382
275383```
276− > s
277− [p='a' q=[1 3 2]] [p='b' q=[5 4 6]]]
384+> j
385+{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
278386
279− > (~(put ju s) 'a' 7)
280− {[p='a' q={7 1 3 2}] [p='b' q={5 4 6}]}
387+> `(jug @t @ud)`(~(put ju j) 'c' 5)
388+{[p='b' q={5 6 4}] [p='a' q={1 2 3}] [p='c' q={5}]}
281389
282− > (~(put ju s) 'a' 1)
283− {[p='a' q={1 3 2}] [p='b' q={5 4 6}]}
390+> `(jug @t @ud)`(~(put ju j) 'a' 4)
391+{[p='b' q={5 6 4}] [p='a' q={1 2 3 4}]}
284392
285− > (~(put ju s) 'c' 7)
286− {[p='a' q={1 3 2}] [p='c' q={7}] [p='b' q={5 4 6}]}
393+> `(jug @t @ud)`(~(put ju j) 'a' 1)
394+{[p='b' q={5 6 4}] [p='a' q={1 2 3}]}
287395```
288396
289397---