@@ -3,35 +3,69 @@ title = "Hints ~ ('sig')"
4template = "doc.html"
4template = "doc.html"
6Runes that use Nock `11` to pass non-semantic info to the interpreter. A
7Runes that use Nock `11` to pass non-semantic info to the interpreter. A
7mnemonic to remember what sig runes are for is "we're *sig*naling some
8mnemonic to remember what sig runes are for is "we're *sig*naling some
8information to the interpreter".
9information to the interpreter".
13+Raw hint, applied to computation.
20+<tr><th>Form</th><th>Syntax</th></tr>
15−`[%sggr p=$@(term [p=term q=hoon]) q=hoon]`: raw hint, applied
47+[%sggr p=$@(term [p=term q=hoon]) q=hoon]
18−##### Expands to
50+#### Expands to
22−##### Syntax
54+#### Semantics
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.
26−##### Discussion
60+#### Discussion
28Hoon has no way of telling what hints are used and what aren't.
62Hoon has no way of telling what hints are used and what aren't.
29Hints are all conventions at the interpreter level.
63Hints are all conventions at the interpreter level.
31−##### Examples
65+#### Examples
34−~zod:dojo> ~>(%a 42)
68+> ~>(%a 42)
@@ -45,24 +79,56 @@ Running the compiler:
45[%11 p=[p=97 q=[%4 p=[%1 p=2]]] q=[%1 p=42]]
79[%11 p=[p=97 q=[%4 p=[%1 p=2]]] q=[%1 p=42]]
48−### `~|` "sigbar"
84+## `~|` "sigbar"
93+<tr><th>Form</th><th>Syntax</th></tr>
51−`[%sgbr p=hoon q=hoon]`: tracing printf.
120+[%sgbr p=hoon q=hoon]
53−##### Expands to
123+#### Expands to
57−##### Convention
127+#### Convention
59Prettyprints `p` in stack trace if `q` crashes.
129Prettyprints `p` in stack trace if `q` crashes.
65−##### Examples
131+#### Examples
68> ~|('sample error message' !!)
134> ~|('sample error message' !!)
@@ -75,46 +141,138 @@ dojo: hoon expression failed
75dojo: hoon expression failed
141dojo: hoon expression failed
78−### `~$` "sigbuc"
146+## `~$` "sigbuc"
148+Profiling hit counter.
152+Two arguments, fixed.
155+<tr><th>Form</th><th>Syntax</th></tr>
80−`[%sgbc p=term q=hoon]`: profiling hit counter.
182+[%sgbc p=term q=hoon]
82−##### Expands to
185+#### Expands to
86−##### Convention
189+#### Discussion
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`.
90−##### Syntax
195+#### Examples
92−Regular: **2-fixed**.
197+```
94−##### Examples
202+Assuming we have the binary running with the `-P` flag, if we do this:
97−~zod:dojo> ~$(%foo 3)
205+> =z |= a=@
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:
226+User-formatted tracing printf.
230+Two arguments, fixed.
233+<tr><th>Form</th><th>Syntax</th></tr>
103−`[%sgcb p=hoon q=hoon]`: user-formatted tracing printf.
260+[%sgcb p=hoon q=hoon]
105−##### Expands to
263+#### Expands to
109−##### Convention
267+#### Convention
111Shows `p` in stacktrace if `q` crashes.
269Shows `p` in stacktrace if `q` crashes.
113−##### Discussion
271+#### Discussion
115−`p` must produce a `tank` (prettyprint source).
273+`p` must produce a `tank` (pretty-print source).
117−##### Examples
275+#### Examples
120> ~_([%leaf "sample error message"] !!)
278> ~_([%leaf "sample error message"] !!)
@@ -127,52 +285,81 @@ sample error message
127dojo: hoon expression failed
285dojo: hoon expression failed
130−### `~%` "sigcen"
290+## `~%` "sigcen"
132−`[%sgcn p=term q=wing r=(list [term hoon]) s=hoon]`: jet registration.
294+#### Syntax
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
301+<tr><th>Form</th><th>Syntax</th></tr>
316+<tr><td>Wide</td><td>None.</td></tr>
317+<tr><td>Irregular</td><td>None.</td></tr>
323+[%sgcn p=chum q=hoon r=tyre s=hoon]
134−##### Expands to
326+#### Expands to
138−##### Convention
330+#### Convention
140Register a core with name `p`, with parent at leg `q`, exporting
332Register a core with name `p`, with parent at leg `q`, exporting
141the named formulas `r`, constructed by `s`.
333the named formulas `r`, constructed by `s`.
145−Regular: **4-fixed**. For `r`, use `~` if empty. Otherwise, **jogging**
146−between opening and closing `==`.
148−##### Discussion
335+#### Discussion
150−`~%` is for registering cores. A registered core declares its
337+`~%` is for registering cores. A registered core declares its
151formal identity to the interpreter, which may or may not be able
338formal identity to the interpreter, which may or may not be able
152to recognize and/or accelerate it.
339to recognize and/or accelerate it.
154Registered cores are organized in a containment hierarchy.
341Registered 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
156register a core, we state the leg to its parent, in the form of
343register 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
158must be, if (a) we registered it on creation, (b) the child was
345must be, if (a) we registered it on creation, (b) the child was
159created by an arm defined on the parent.
346created by an arm defined on the parent.
161−(Cores are actually managed by their formula/battery. Any
348+(Cores are actually managed by their formula/battery. Any
162function call will create a new core with a new sample, but
349function 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
164battery -- matching the semantics constrains the payload as well,
351battery -- matching the semantics constrains the payload as well,
165since the semantics of a battery may depend on any parent core
352since the semantics of a battery may depend on any parent core
166and/or payload constant.)
353and/or payload constant.)
168−The purpose of registration is always performance-related. It
355+The purpose of registration is always performance-related. It
169may involve (a) a special-purpose optimizer or "jet", written
356may involve (a) a special-purpose optimizer or "jet", written
170for a specific core and checked with a Merkle hash; (b) a
357for a specific core and checked with a Merkle hash; (b) a
171general-purpose hotspot optimizer or "JIT"; or (c) merely a
358general-purpose hotspot optimizer or "JIT"; or (c) merely a
172hotspot declaration for profiling.
359hotspot declaration for profiling.
174As always with hints, the programmer has no idea which of (a),
361As 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 `~%`
176indiscriminately on all hotspots, bottlenecks, etc, real or
363indiscriminately on all hotspots, bottlenecks, etc, real or
177suspected.
364suspected.
@@ -181,7 +368,7 @@ implementors with named Nock formulas that act on the core.
181In complex systems, jet implementations are often partial and
368In complex systems, jet implementations are often partial and
182want to call back into userspace.
369want to call back into userspace.
184−The child core contains the parent, of course. When we register
371+The child core contains the parent, of course. When we register
185a core, we state the leg to its parent, in the form of wing `q`.
372a core, we state the leg to its parent, in the form of wing `q`.
186We assume that the parent -- any core within the payload -- is
373We assume that the parent -- any core within the payload -- is
187already registered.
374already registered.
@@ -190,55 +377,80 @@ already registered.
191Registers a jet in core `s` so that it can be called when that code is run.
378Registers a jet in core `s` so that it can be called when that code is run.
193−Regular form: **4-fixed**
380+#### Examples
197−Here's the AES
382+Here's the beginning of the AES core in `zuse.hoon`:
200− ++ aesc :: AES-256
385+++ aes !.
201− ~% %aesc + ~
386+ ~% %aes ..part ~
203− ++ en :: ECB enc
388+ ++ ahem
204− ~/ %en
389+ |= [nnk=@ nnb=@ nnr=@]
205− |= [a=@I b=@H] ^- @uxH
390+ =>
206− =+ ahem
391+ =+ => [gr=(ga 8 0x11b 3) few==>(fe .(a 5))]
207− (be & (ex a) b)
392+ [pro=pro.gr dif=dif.gr pow=pow.gr ror=ror.few]
208− ++ de :: ECB dec
393+ => |%
209− ~/ %de
394+ ..........
210− |= [a=@I b=@H] ^- @uxH
212− (be | (ix (ex a)) b)
216−Here we label the entire `++aesc` core for optimization. You can see the
397+Here we label the entire `++aes` core for optimization.
217−jet in `jets/e/aesc.c`.
220−### `~<` "siggal"
401+## `~<` "siggal"
403+Raw hint, applied to product.
223−`[%sggl p=$@(term [p=term q=hoon]) q=hoon]`: raw hint, applied to
405+#### Syntax
226−##### Expands to
407+Two arguments, fixed.
410+<tr><th>Form</th><th>Syntax</th></tr>
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`.
230−##### Syntax
439+```hoon
440+[%sggl p=$@(term [p=term q=hoon]) q=hoon]
232−Regular: **2-fixed**. For the dynamic form, write `%term.hoon`.
443+#### Expands to
234−##### Discussion
447+#### Discussion
236−`~<` is only used for jet hints ([`~/`](#sigfas)
449+`~<` is only used for jet hints ([`~/`](#sigfas) and [`~%`](#sigcen)) at the
237−and [`~%`](#sigcen)) at the moment; we are not telling the
238−interpreter something about the computation we're about to perform, but
450+moment; we are not telling the interpreter something about the computation we're
239−rather about its product.
451+about to perform, but rather about its product.
241−##### Examples
453+#### Examples
244> (make '~<(%a 42)')
456> (make '~<(%a 42)')
@@ -247,64 +459,129 @@ rather about its product.
247[%7 p=[%1 p=42] q=[%11 p=[p=97 q=[%4 p=[%0 p=1]]] q=[%0 p=1]]]
459[%7 p=[%1 p=42] q=[%11 p=[p=97 q=[%4 p=[%0 p=1]]] q=[%0 p=1]]]
250−### `~+` "siglus"
464+## `~+` "siglus"
473+<tr><th>Form</th><th>Syntax</th></tr>
252−`[%sgls p=hoon]`: cache a computation.
499+[%sgls p=hoon]
254−##### Expands to
502+#### Expands to
258−##### Convention
506+#### Convention
260Caches the formula and subject of `p` in a local cache (generally
508Caches the formula and subject of `p` in a local cache (generally
261transient in the current event).
509transient in the current event).
265−Regular: **1-fixed**.
267−##### Examples
511+#### Examples
269This may pause for a second:
513This may pause for a second:
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))))))
276This may make you want to press `ctrl-c`:
520This may make you want to press `ctrl-c`:
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))))))
283This should work fine:
527This should work fine:
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)))))))
287573.147.844.013.817.084.101
531573.147.844.013.817.084.101
290−### `~/` "sigfas"
536+## `~/` "sigfas"
538+Jet registration for gate with registered context.
542+Two arguments, fixed.
545+<tr><th>Form</th><th>Syntax</th></tr>
292−`[%sgfs p=term q=hoon]`: jet registration for gate with
572+[%sgfs p=term q=hoon]
293−registered context.
573+```
295−##### Expands to
575+#### Expands to
298~%(p +7 ~ q)
578~%(p +7 ~ q)
303−Regular: **2-fixed**.
305−##### Examples
581+#### Examples
307From the kernel:
583From the kernel:
@@ -314,139 +591,277 @@ From the kernel:
314 $(a (dec a), b +(b))
591 $(a (dec a), b +(b))
317−### `~&` "sigpam"
596+## `~&` "sigpam"
602+Two arguments, fixed.
605+<tr><th>Form</th><th>Syntax</th></tr>
319−`[%sgpm p=hoon q=hoon]`: debugging printf.
632+[%sgpm p=hoon q=hoon]
321−##### Expands to
635+#### Expands to
325−##### Product
639+#### Product
327Pretty-prints `p` on the console before computing `q`.
641Pretty-prints `p` on the console before computing `q`.
329−##### Discussion
643+#### Discussion
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.
333It's most useful for debugging programs.
648It's most useful for debugging programs.
337−Regular: **2-fixed**.
339−##### Examples
650+#### Examples
342−~zod:dojo> ~&('halp' ~)
653+> ~&('halp' ~)
346−~zod:dojo> ~& 'halp'
657+> ~& 'halp'
352−### `~=` "sigtis"
665+## `~=` "sigtis"
671+Two arguments, fixed.
674+<tr><th>Form</th><th>Syntax</th></tr>
354−`[%sgts p=hoon q=hoon]`: detect duplicate.
701+[%sgts p=hoon q=hoon]
356−##### Expands to
704+#### Expands to
360−##### Convention
708+#### Convention
362If `p` equals `q`, produce `p` instead of `q`.
710If `p` equals `q`, produce `p` instead of `q`.
364−##### Discussion
712+#### Discussion
366Duplicate nouns are especially bad news in Hoon, because comparing them
714Duplicate 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.
369−##### Examples
717+#### Examples
371This code traverses a tree and replaces all instances of `32` with
719This code traverses a tree and replaces all instances of `32` with
375−~zod:dojo> =foo |= a=(tree)
723+> =foo |= a=(tree)
376− ?~(a ~ ~=(a [?:(=(n.a 32) 320 n.a) $(a l.a) $(a r.a)]))
724+ ?~(a ~ ~=(a [?:(=(n.a 32) 320 n.a) $(a l.a) $(a r.a)]))
378−~zod:dojo> (foo 32 ~ ~)
726+> (foo 32 ~ ~)
382−Without `~=`, it would build a copy of a completely unchanged tree. Sad!
730+Without `~=`, it would build a copy of a completely unchanged tree. Sad!
384−### `~?` "sigwut"
734+## `~?` "sigwut"
736+Conditional debug printf.
740+Three arguments, fixed.
743+<tr><th>Form</th><th>Syntax</th></tr>
386−`[%sgwt p=hoon q=hoon r=hoon]`: conditional debug printf.
771+[%sgwt p=hoon q=hoon r=hoon]
388−##### Expands to
774+#### Expands to
392−##### Convention
778+#### Convention
394If `p` is true, prettyprints `q` on the console before computing `r`.
780If `p` is true, prettyprints `q` on the console before computing `r`.
398−Regular: **3-fixed**.
400−##### Examples
782+#### Examples
403−~zod:dojo> ~?((gth 1 2) 'oops' ~)
785+> ~?((gth 1 2) 'oops' ~)
406−~zod:dojo> ~?((gth 1 0) 'oops' ~)
788+> ~?((gth 1 0) 'oops' ~)
410−~zod:dojo> ~? (gth 1 2)
792+> ~? (gth 1 2)
415−~zod:dojo> ~? (gth 1 0)
797+> ~? (gth 1 0)
422−### `~!` "sigzap"
806+## `~!` "sigzap"
808+Print type on compilation fail.
812+Two arguments, fixed.
815+<tr><th>Form</th><th>Syntax</th></tr>
424−`[%sgzp p=hoon q=hoon]`: print type on compilation fail.
842+[%sgzp p=hoon q=hoon]
426−##### Expands to
845+#### Expands to
430−##### Convention
849+#### Convention
432If compilation of `q` fails, prints the type of `p` in the trace.
851If compilation of `q` fails, prints the type of `p` in the trace.
436−Regular: **2-fixed**.
438−##### Examples
853+#### Examples
444−~zod:dojo> ~!('foo' a)
859+> ~!('foo' a)
448−~zod:dojo> ~! 'foo'
863+> ~! 'foo'