@@ -3,35 +3,69 @@ title = "Hints ~ ('sig')"
33weight = 14
44template = "doc.html"
55+++
6+
67Runes that use Nock `11` to pass non-semantic info to the interpreter. A
78mnemonic to remember what sig runes are for is "we're *sig*naling some
89information to the interpreter".
910
11+## `~>` "siggar"
12+
13+Raw hint, applied to computation.
14+
15+#### Syntax
16+
17+Two arguments, fixed.
18+
19+<table>
20+<tr><th>Form</th><th>Syntax</th></tr>
21+<tr>
22+<td>Tall</td>
23+<td>
24+<pre>
25+~> p
26+q
27+</pre>
28+</td>
29+</tr>
30+<tr>
31+<td>Wide</td>
32+<td>
33+<pre>
34+~>(p q)
35+</pre>
36+</td>
37+</tr>
38+<tr>
39+<td>Irregular</td>
40+<td>None.</td>
41+</tr>
42+</table>
43+
44+#### AST
1045
11−## Runes
12−
13−### `~>` "siggar"
14−
15−`[%sggr p=$@(term [p=term q=hoon]) q=hoon]`: raw hint, applied
16−to computation.
46+```hoon
47+[%sggr p=$@(term [p=term q=hoon]) q=hoon]
48+```
1749
18−##### Expands to
50+#### Expands to
1951
2052`q`.
2153
22−##### Syntax
54+#### Semantics
2355
24−Regular: **2-fixed**. For the dynamic form, write `%term.hoon`.
56+`p` may either be a single `%term` or a pair of `[term hoon]`, the latter of
57+which may optionally be be written `%foo.some-hoon`. `p` will be passed to the
58+interpreter and `q` will be evaluated and its result produced like normal.
2559
26−##### Discussion
60+#### Discussion
2761
2862Hoon has no way of telling what hints are used and what aren't.
2963Hints are all conventions at the interpreter level.
3064
31−##### Examples
65+#### Examples
3266
3367```
34−~zod:dojo> ~>(%a 42)
68+> ~>(%a 42)
356942
3670```
3771
@@ -45,24 +79,56 @@ Running the compiler:
4579[%11 p=[p=97 q=[%4 p=[%1 p=2]]] q=[%1 p=42]]
4680```
4781
48−### `~|` "sigbar"
49−
82+---
83+
84+## `~|` "sigbar"
85+
86+Tracing printf.
87+
88+#### Syntax
89+
90+Two arguments, fixed.
91+
92+<table>
93+<tr><th>Form</th><th>Syntax</th></tr>
94+<tr>
95+<td>Tall</td>
96+<td>
97+<pre>
98+~| p
99+q
100+</pre>
101+</td>
102+</tr>
103+<tr>
104+<td>Wide</td>
105+<td>
106+<pre>
107+~|(p q)
108+</pre>
109+</td>
110+</tr>
111+<tr>
112+<td>Irregular</td>
113+<td>None.</td>
114+</tr>
115+</table>
116+
117+#### AST
50118
51−`[%sgbr p=hoon q=hoon]`: tracing printf.
119+```hoon
120+[%sgbr p=hoon q=hoon]
121+```
52122
53−##### Expands to
123+#### Expands to
54124
55125`q`.
56126
57−##### Convention
127+#### Convention
58128
59129Prettyprints `p` in stack trace if `q` crashes.
60130
61−##### Syntax
62−
63−Regular: **2-fixed**.
64−
65−##### Examples
131+#### Examples
66132
67133```
68134> ~|('sample error message' !!)
@@ -75,46 +141,138 @@ dojo: hoon expression failed
75141dojo: hoon expression failed
76142```
77143
78−### `~$` "sigbuc"
144+---
145+
146+## `~$` "sigbuc"
147+
148+Profiling hit counter.
149+
150+#### Syntax
151+
152+Two arguments, fixed.
153+
154+<table>
155+<tr><th>Form</th><th>Syntax</th></tr>
156+<tr>
157+<td>Tall</td>
158+<td>
159+<pre>
160+~& p
161+q
162+</pre>
163+</td>
164+</tr>
165+<tr>
166+<td>Wide</td>
167+<td>
168+<pre>
169+~&(p q)
170+</pre>
171+</td>
172+</tr>
173+<tr>
174+<td>Irregular</td>
175+<td>None.</td>
176+</tr>
177+</table>
178+
179+#### AST
79180
80−`[%sgbc p=term q=hoon]`: profiling hit counter.
181+```hoon
182+[%sgbc p=term q=hoon]
183+```
81184
82−##### Expands to
185+#### Expands to
83186
84187`q`.
85188
86−##### Convention
189+#### Discussion
87190
88−If profiling is on, adds 1 to the hit counter for `p`.
191+If profiling is on, adds 1 to the hit counter `p`, which is a `term` like
192+`%foo`. Profiling is enabled by passing the `-P` flag to the `urbit` binary.
193+Profiling results are saved in `/path/to/pier/.urb/put/profile/~some.date.txt`.
89194
90−##### Syntax
195+#### Examples
91196
92−Regular: **2-fixed**.
197+```
198+> ~$(%foo 3)
199+3
200+```
93201
94−##### Examples
202+Assuming we have the binary running with the `-P` flag, if we do this:
95203
96204```
97−~zod:dojo> ~$(%foo 3)
98−3
205+> =z |= a=@
206+ ?: =(a 0)
207+ a
208+ ~$ %my-hit-counter
209+ $(a (dec a))
210+
211+> (z 42)
212+0
99213```
100214
101−### `~_` "sigcab"
215+...then look in `/path/to/pier/.urb/put/profile/~some.date.txt`, we'll see this
216+line near the top of the file:
102217
103−`[%sgcb p=hoon q=hoon]`: user-formatted tracing printf.
218+```
219+my-hit-counter: 42
220+```
221+
222+---
223+
224+## `~_` "sigcab"
225+
226+User-formatted tracing printf.
227+
228+#### Syntax
229+
230+Two arguments, fixed.
231+
232+<table>
233+<tr><th>Form</th><th>Syntax</th></tr>
234+<tr>
235+<td>Tall</td>
236+<td>
237+<pre>
238+~_ p
239+q
240+</pre>
241+</td>
242+</tr>
243+<tr>
244+<td>Wide</td>
245+<td>
246+<pre>
247+~_(p q)
248+</pre>
249+</td>
250+</tr>
251+<tr>
252+<td>Irregular</td>
253+<td>None.</td>
254+</tr>
255+</table>
256+
257+#### AST
258+
259+```hoon
260+[%sgcb p=hoon q=hoon]
261+```
104262
105−##### Expands to
263+#### Expands to
106264
107265`q`.
108266
109−##### Convention
267+#### Convention
110268
111269Shows `p` in stacktrace if `q` crashes.
112270
113−##### Discussion
271+#### Discussion
114272
115−`p` must produce a `tank` (prettyprint source).
273+`p` must produce a `tank` (pretty-print source).
116274
117−##### Examples
275+#### Examples
118276
119277```
120278> ~_([%leaf "sample error message"] !!)
@@ -127,52 +285,81 @@ sample error message
127285dojo: hoon expression failed
128286```
129287
130−### `~%` "sigcen"
288+---
289+
290+## `~%` "sigcen"
291+
292+Jet registration.
131293
132−`[%sgcn p=term q=wing r=(list [term hoon]) s=hoon]`: jet registration.
294+#### Syntax
133295
134−##### Expands to
296+Four arguments. Two fixed arguments, then a third which may be `~` if empty or
297+else a variable number of pairs sandwiched between two `==`s, then a fourth
298+fixed argument.
299+
300+<table>
301+<tr><th>Form</th><th>Syntax</th></tr>
302+<tr>
303+<td>Tall</td>
304+<td>
305+<pre>
306+~% p q
307+ ==
308+ r1a r1b
309+ r2a r2b
310+ rna rnb
311+ ==
312+s
313+</pre>
314+</td>
315+</tr>
316+<tr><td>Wide</td><td>None.</td></tr>
317+<tr><td>Irregular</td><td>None.</td></tr>
318+</table>
319+
320+#### AST
321+
322+```hoon
323+[%sgcn p=chum q=hoon r=tyre s=hoon]
324+```
325+
326+#### Expands to
135327
136328`s`.
137329
138−##### Convention
330+#### Convention
139331
140332Register a core with name `p`, with parent at leg `q`, exporting
141333the named formulas `r`, constructed by `s`.
142334
143−##### Syntax
144−
145−Regular: **4-fixed**. For `r`, use `~` if empty. Otherwise, **jogging**
146−between opening and closing `==`.
147−
148−##### Discussion
335+#### Discussion
149336
150−`~%` is for registering cores. A registered core declares its
337+`~%` is for registering cores. A registered core declares its
151338formal identity to the interpreter, which may or may not be able
152339to recognize and/or accelerate it.
153340
154341Registered cores are organized in a containment hierarchy.
155−The parent core is at any leg within the child core. When we
342+The parent core is at any leg within the child core. When we
156343register a core, we state the leg to its parent, in the form of
157−wing `q`. We assume the parent is already registered -- as it
344+wing `q`. We assume the parent is already registered -- as it
158345must be, if (a) we registered it on creation, (b) the child was
159346created by an arm defined on the parent.
160347
161−(Cores are actually managed by their formula/battery. Any
348+(Cores are actually managed by their formula/battery. Any
162349function call will create a new core with a new sample, but
163−batteries are constant. But it is not sufficient to match the
350+batteries are constant. But it is not sufficient to match the
164351battery -- matching the semantics constrains the payload as well,
165352since the semantics of a battery may depend on any parent core
166353and/or payload constant.)
167354
168−The purpose of registration is always performance-related. It
355+The purpose of registration is always performance-related. It
169356may involve (a) a special-purpose optimizer or "jet", written
170357for a specific core and checked with a Merkle hash; (b) a
171358general-purpose hotspot optimizer or "JIT"; or (c) merely a
172359hotspot declaration for profiling.
173360
174361As always with hints, the programmer has no idea which of (a),
175−(b), and (c) will be applied. Use `~%`
362+(b), and (c) will be applied. Use `~%`
176363indiscriminately on all hotspots, bottlenecks, etc, real or
177364suspected.
178365
@@ -181,7 +368,7 @@ implementors with named Nock formulas that act on the core.
181368In complex systems, jet implementations are often partial and
182369want to call back into userspace.
183370
184−The child core contains the parent, of course. When we register
371+The child core contains the parent, of course. When we register
185372a core, we state the leg to its parent, in the form of wing `q`.
186373We assume that the parent -- any core within the payload -- is
187374already registered.
@@ -190,55 +377,80 @@ already registered.
190377
191378Registers a jet in core `s` so that it can be called when that code is run.
192379
193−Regular form: **4-fixed**
380+#### Examples
194381
195−##### Examples
196−
197−Here's the AES
382+Here's the beginning of the AES core in `zuse.hoon`:
198383
199384```hoon
200− ++ aesc :: AES-256
201− ~% %aesc + ~
202− |%
203− ++ en :: ECB enc
204− ~/ %en
205− |= [a=@I b=@H] ^- @uxH
206− =+ ahem
207− (be & (ex a) b)
208− ++ de :: ECB dec
209− ~/ %de
210− |= [a=@I b=@H] ^- @uxH
211− =+ ahem
212− (be | (ix (ex a)) b)
213− --
385+++ aes !.
386+ ~% %aes ..part ~
387+ |%
388+ ++ ahem
389+ |= [nnk=@ nnb=@ nnr=@]
390+ =>
391+ =+ => [gr=(ga 8 0x11b 3) few==>(fe .(a 5))]
392+ [pro=pro.gr dif=dif.gr pow=pow.gr ror=ror.few]
393+ => |%
394+ ..........
214395```
215396
216−Here we label the entire `++aesc` core for optimization. You can see the
217−jet in `jets/e/aesc.c`.
397+Here we label the entire `++aes` core for optimization.
218398
399+---
219400
220−### `~<` "siggal"
401+## `~<` "siggal"
221402
403+Raw hint, applied to product.
222404
223−`[%sggl p=$@(term [p=term q=hoon]) q=hoon]`: raw hint, applied to
224−product.
405+#### Syntax
225406
226−##### Expands to
407+Two arguments, fixed.
227408
228−`q`.
409+<table>
410+<tr><th>Form</th><th>Syntax</th></tr>
411+<tr>
412+<td>Tall</td>
413+<td>
414+<pre>
415+~< p
416+q
417+</pre>
418+</td>
419+</tr>
420+<tr>
421+<td>Wide</td>
422+<td>
423+<pre>
424+~<(p q)
425+</pre>
426+</td>
427+</tr>
428+<tr>
429+<td>Irregular</td>
430+<td>None.</td>
431+</tr>
432+</table>
433+
434+`p` may either be a a `term` or a pair of `[term hoon]`. If it's the latter, `p`
435+may optionally be written as `%foo.some-hoon`.
436+
437+#### AST
229438
230−##### Syntax
439+```hoon
440+[%sggl p=$@(term [p=term q=hoon]) q=hoon]
441+```
231442
232−Regular: **2-fixed**. For the dynamic form, write `%term.hoon`.
443+#### Expands to
444+
445+`q`.
233446
234−##### Discussion
447+#### Discussion
235448
236−`~<` is only used for jet hints ([`~/`](#sigfas)
237−and [`~%`](#sigcen)) at the moment; we are not telling the
238−interpreter something about the computation we're about to perform, but
239−rather about its product.
449+`~<` is only used for jet hints ([`~/`](#sigfas) and [`~%`](#sigcen)) at the
450+moment; we are not telling the interpreter something about the computation we're
451+about to perform, but rather about its product.
240452
241−##### Examples
453+#### Examples
242454
243455```
244456> (make '~<(%a 42)')
@@ -247,64 +459,129 @@ rather about its product.
247459[%7 p=[%1 p=42] q=[%11 p=[p=97 q=[%4 p=[%0 p=1]]] q=[%0 p=1]]]
248460```
249461
250−### `~+` "siglus"
462+---
463+
464+## `~+` "siglus"
465+
466+Cache a computation.
467+
468+#### Syntax
469+
470+One argument, fixed.
471+
472+<table>
473+<tr><th>Form</th><th>Syntax</th></tr>
474+<tr>
475+<td>Tall</td>
476+<td>
477+<pre>
478+~+ p
479+</pre>
480+</td>
481+</tr>
482+<tr>
483+<td>Wide</td>
484+<td>
485+<pre>
486+~+(p)
487+</pre>
488+</td>
489+</tr>
490+<tr>
491+<td>Irregular</td>
492+<td>None.</td>
493+</tr>
494+</table>
495+
496+#### AST
251497
252−`[%sgls p=hoon]`: cache a computation.
498+```hoon
499+[%sgls p=hoon]
500+```
253501
254−##### Expands to
502+#### Expands to
255503
256504`p`.
257505
258−##### Convention
506+#### Convention
259507
260508Caches the formula and subject of `p` in a local cache (generally
261509transient in the current event).
262510
263−##### Syntax
264−
265−Regular: **1-fixed**.
266−
267−##### Examples
511+#### Examples
268512
269513This may pause for a second:
270514
271515```
272−~zod:dojo> %.(25 |=(a=@ ?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a))))))
516+> %.(25 |=(a=@ ?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a))))))
273517121.393
274518```
275519
276520This may make you want to press `ctrl-c`:
277521
278522```
279−~zod:dojo> %.(30 |=(a=@ ?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a))))))
523+> %.(30 |=(a=@ ?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a))))))
2805241.346.269
281525```
282526
283527This should work fine:
284528
285529```
286−~zod:dojo> %.(100 |=(a=@ ~+(?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a)))))))
530+> %.(100 |=(a=@ ~+(?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a)))))))
287531573.147.844.013.817.084.101
288532```
289533
290−### `~/` "sigfas"
534+---
535+
536+## `~/` "sigfas"
537+
538+Jet registration for gate with registered context.
539+
540+#### Syntax
541+
542+Two arguments, fixed.
543+
544+<table>
545+<tr><th>Form</th><th>Syntax</th></tr>
546+<tr>
547+<td>Tall</td>
548+<td>
549+<pre>
550+~/ p
551+q
552+</pre>
553+</td>
554+</tr>
555+<tr>
556+<td>Wide</td>
557+<td>
558+<pre>
559+~/(p q)
560+</pre>
561+</td>
562+</tr>
563+<tr>
564+<td>Irregular</td>
565+<td>None.</td>
566+</tr>
567+</table>
568+
569+#### AST
291570
292−`[%sgfs p=term q=hoon]`: jet registration for gate with
293−registered context.
571+```hoon
572+[%sgfs p=term q=hoon]
573+```
294574
295−##### Expands to
575+#### Expands to
296576
297577```hoon
298578~%(p +7 ~ q)
299579```
300580
301−##### Syntax
302−
303−Regular: **2-fixed**.
304−
305−##### Examples
581+#### Examples
306582
307583From the kernel:
584+
308585```hoon
309586++ add
310587 ~/ %add
@@ -314,139 +591,277 @@ From the kernel:
314591 $(a (dec a), b +(b))
315592```
316593
317−### `~&` "sigpam"
594+---
595+
596+## `~&` "sigpam"
597+
598+Debugging printf.
599+
600+#### Syntax
601+
602+Two arguments, fixed.
603+
604+<table>
605+<tr><th>Form</th><th>Syntax</th></tr>
606+<tr>
607+<td>Tall</td>
608+<td>
609+<pre>
610+~& p
611+q
612+</pre>
613+</td>
614+</tr>
615+<tr>
616+<td>Wide</td>
617+<td>
618+<pre>
619+~&(p q)
620+</pre>
621+</td>
622+</tr>
623+<tr>
624+<td>Irregular</td>
625+<td>None.</td>
626+</tr>
627+</table>
628+
629+#### AST
318630
319−`[%sgpm p=hoon q=hoon]`: debugging printf.
631+```hoon
632+[%sgpm p=hoon q=hoon]
633+```
320634
321−##### Expands to
635+#### Expands to
322636
323637`q`.
324638
325−##### Product
639+#### Product
326640
327641Pretty-prints `p` on the console before computing `q`.
328642
329−##### Discussion
643+#### Discussion
330644
331−This rune has no semantic effect beyond the Hoon expression `q`. It's used solely to create a side-effect: printing the value of `p` to the console.
645+This rune has no semantic effect beyond the Hoon expression `q`. It's used
646+solely to create a side-effect: printing the value of `p` to the console.
332647
333648It's most useful for debugging programs.
334649
335−##### Syntax
336−
337−Regular: **2-fixed**.
338−
339−##### Examples
650+#### Examples
340651
341652```
342−~zod:dojo> ~&('halp' ~)
653+> ~&('halp' ~)
343654'halp'
344655~
345656
346−~zod:dojo> ~& 'halp'
347− ~
657+> ~& 'halp'
658+ ~
348659'halp'
349660~
350661```
351662
352−### `~=` "sigtis"
663+---
664+
665+## `~=` "sigtis"
666+
667+Detect duplicate.
668+
669+#### Syntax
670+
671+Two arguments, fixed.
672+
673+<table>
674+<tr><th>Form</th><th>Syntax</th></tr>
675+<tr>
676+<td>Tall</td>
677+<td>
678+<pre>
679+~= p
680+q
681+</pre>
682+</td>
683+</tr>
684+<tr>
685+<td>Wide</td>
686+<td>
687+<pre>
688+~=(p q)
689+</pre>
690+</td>
691+</tr>
692+<tr>
693+<td>Irregular</td>
694+<td>None.</td>
695+</tr>
696+</table>
697+
698+#### AST
353699
354−`[%sgts p=hoon q=hoon]`: detect duplicate.
700+```hoon
701+[%sgts p=hoon q=hoon]
702+```
355703
356−##### Expands to
704+#### Expands to
357705
358706`q`.
359707
360−##### Convention
708+#### Convention
361709
362710If `p` equals `q`, produce `p` instead of `q`.
363711
364−##### Discussion
712+#### Discussion
365713
366714Duplicate nouns are especially bad news in Hoon, because comparing them
367−takes O(n) time. Use `~=` to avoid this inefficiency.
715+takes O(n) time. Use `~=` to avoid this inefficiency.
368716
369−##### Examples
717+#### Examples
370718
371719This code traverses a tree and replaces all instances of `32` with
372720`320`:
373721
374722```
375−~zod:dojo> =foo |= a=(tree)
376− ?~(a ~ ~=(a [?:(=(n.a 32) 320 n.a) $(a l.a) $(a r.a)]))
723+> =foo |= a=(tree)
724+ ?~(a ~ ~=(a [?:(=(n.a 32) 320 n.a) $(a l.a) $(a r.a)]))
377725
378−~zod:dojo> (foo 32 ~ ~)
726+> (foo 32 ~ ~)
379727[320 ~ ~]
380728```
381729
382−Without `~=`, it would build a copy of a completely unchanged tree. Sad!
383−
384−### `~?` "sigwut"
730+Without `~=`, it would build a copy of a completely unchanged tree. Sad!
731+
732+---
733+
734+## `~?` "sigwut"
735+
736+Conditional debug printf.
737+
738+#### Syntax
739+
740+Three arguments, fixed.
741+
742+<table>
743+<tr><th>Form</th><th>Syntax</th></tr>
744+<tr>
745+<td>Tall</td>
746+<td>
747+<pre>
748+~? p
749+ q
750+r
751+</pre>
752+</td>
753+</tr>
754+<tr>
755+<td>Wide</td>
756+<td>
757+<pre>
758+~?(p q r)
759+</pre>
760+</td>
761+</tr>
762+<tr>
763+<td>Irregular</td>
764+<td>None.</td>
765+</tr>
766+</table>
767+
768+#### AST
385769
386−`[%sgwt p=hoon q=hoon r=hoon]`: conditional debug printf.
770+```hoon
771+[%sgwt p=hoon q=hoon r=hoon]
772+```
387773
388−##### Expands to
774+#### Expands to
389775
390776`r`.
391777
392−##### Convention
778+#### Convention
393779
394780If `p` is true, prettyprints `q` on the console before computing `r`.
395781
396−##### Syntax
397−
398−Regular: **3-fixed**.
399−
400−##### Examples
782+#### Examples
401783
402784```
403−~zod:dojo> ~?((gth 1 2) 'oops' ~)
785+> ~?((gth 1 2) 'oops' ~)
404786~
405787
406−~zod:dojo> ~?((gth 1 0) 'oops' ~)
788+> ~?((gth 1 0) 'oops' ~)
407789'oops'
408790~
409791
410−~zod:dojo> ~? (gth 1 2)
411− 'oops'
412− ~
792+> ~? (gth 1 2)
793+ 'oops'
794+ ~
413795~
414796
415−~zod:dojo> ~? (gth 1 0)
416− 'oops'
417− ~
797+> ~? (gth 1 0)
798+ 'oops'
799+ ~
418800'oops'
419801~
420802```
421803
422−### `~!` "sigzap"
804+---
805+
806+## `~!` "sigzap"
807+
808+Print type on compilation fail.
809+
810+#### Syntax
811+
812+Two arguments, fixed.
813+
814+<table>
815+<tr><th>Form</th><th>Syntax</th></tr>
816+<tr>
817+<td>Tall</td>
818+<td>
819+<pre>
820+~! p
821+q
822+</pre>
823+</td>
824+</tr>
825+<tr>
826+<td>Wide</td>
827+<td>
828+<pre>
829+~!(p q)
830+</pre>
831+</td>
832+</tr>
833+<tr>
834+<td>Irregular</td>
835+<td>None.</td>
836+</tr>
837+</table>
838+
839+#### AST
423840
424−`[%sgzp p=hoon q=hoon]`: print type on compilation fail.
841+```hoon
842+[%sgzp p=hoon q=hoon]
843+```
425844
426−##### Expands to
845+#### Expands to
427846
428847`q`.
429848
430−##### Convention
849+#### Convention
431850
432851If compilation of `q` fails, prints the type of `p` in the trace.
433852
434−##### Syntax
435−
436−Regular: **2-fixed**.
437−
438−##### Examples
853+#### Examples
439854
440855```
441−~zod:dojo> a
856+> a
442857! -find.a
443858
444−~zod:dojo> ~!('foo' a)
859+> ~!('foo' a)
445860! @t
446861! find.a
447862
448−~zod:dojo> ~! 'foo'
449− a
863+> ~! 'foo'
864+ a
450865! @t
451866! find.a
452867```