Hints ~ ('sig')

Hints ~ ('sig')

Runes that use Nock 11 to pass non-semantic info to the interpreter. A mnemonic to remember what sig runes are for is "we're signaling some information to the interpreter".

Runes

`~>` "siggar"

[%sggr p=$@(term [p=term q=hoon]) q=hoon]: raw hint, applied to computation.

Expands to

q.

Syntax

Regular: 2-fixed. For the dynamic form, write %term.hoon.

Discussion

Hoon has no way of telling what hints are used and what aren't. Hints are all conventions at the interpreter level.

Examples

~zod:dojo> ~>(%a 42)
42

Running the compiler:

~zod:dojo> (make '~>(%a 42)')
[%10 p=97 q=[%1 p=42]]

~zod:dojo> (make '~>(%a.+(2) 42)')
[%10 p=[p=97 q=[%4 p=[%1 p=2]]] q=[%1 p=42]]

`~|` "sigbar"

[%sgbr p=hoon q=hoon]: tracing printf.

Expands to

q.

Convention

Prettyprints p in stack trace if q crashes.

Syntax

Regular: 2-fixed.

Examples

~zod:dojo> ~|('sample error message' !!)
'sample error message'
ford: build failed

~zod:dojo> ~|  'sample error message'
           !!
'sample error message'
ford: build failed

`~$` "sigbuc"

[%sgbc p=term q=hoon]: profiling hit counter.

Expands to

q.

Convention

If profiling is on, adds 1 to the hit counter for p.

Syntax

Regular: 2-fixed.

Examples

~zod:dojo> ~$(%foo 3)
3

`~_` "sigcab"

[%sgcb p=hoon q=hoon]: user-formatted tracing printf.

Expands to

q.

Convention

Shows p in stacktrace if q crashes.

Discussion

p must produce a tank (prettyprint source).

Examples

~zod:dojo> ~_([%leaf "sample error message"] !!)
"sample error message"
ford: build failed

~zod:dojo> ~_  [%leaf "sample error message"]
           !!
"sample error message"
ford: build failed

`~%` "sigcen"

[%sgcn p=term q=wing r=(list [term hoon]) s=hoon]: jet registration.

Expands to

s.

Convention

Syntax

Regular: 4-fixed. For r, use ~ if empty. Otherwise, jogging between opening and closing ==.

Discussion

~% is for registering cores. A registered core declares its formal identity to the interpreter, which may or may not be able to recognize and/or accelerate it.

Registered cores are organized in a containment hierarchy. The parent core is at any leg within the child core. When we register a core, we state the leg to its parent, in the form of wing q. We assume the parent is already registered -- as it must be, if (a) we registered it on creation, (b) the child was created by an arm defined on the parent.

(Cores are actually managed by their formula/battery. Any function call will create a new core with a new sample, but batteries are constant. But it is not sufficient to match the battery -- matching the semantics constrains the payload as well, since the semantics of a battery may depend on any parent core and/or payload constant.)

The purpose of registration is always performance-related. It may involve (a) a special-purpose optimizer or "jet", written for a specific core and checked with a Merkle hash; (b) a general-purpose hotspot optimizer or "JIT"; or (c) merely a hotspot declaration for profiling.

As always with hints, the programmer has no idea which of (a), (b), and (c) will be applied. Use ~% indiscriminately on all hotspots, bottlenecks, etc, real or suspected.

The list r is a way for the Hoon programmer to help jet implementors with named Nock formulas that act on the core. In complex systems, jet implementations are often partial and want to call back into userspace.

The child core contains the parent, of course. When we register a core, we state the leg to its parent, in the form of wing q. We assume that the parent -- any core within the payload -- is already registered.

p is the name of this core within its parent; q is a the leg

Registers a jet in core s so that it can be called when that code is run.

Regular form: 4-fixed

Examples

Here's the AES

++  aesc                                                ::  AES-256
      ~%  %aesc  +  ~
      |%
      ++  en                                                ::  ECB enc
        ~/  %en
        |=  [a=@I b=@H]  ^-  @uxH
        =+  ahem
        (be & (ex a) b)
      ++  de                                                ::  ECB dec
        ~/  %de
        |=  [a=@I b=@H]  ^-  @uxH
        =+  ahem
        (be | (ix (ex a)) b)
      --

Here we label the entire ++aesc core for optimization. You can see the jet in jets/e/aesc.c.

`~<` "siggal"

[%sggl p=$@(term [p=term q=hoon]) q=hoon]: raw hint, applied to product.

Expands to

q.

Syntax

Regular: 2-fixed. For the dynamic form, write %term.hoon.

Discussion

~< is only used for jet hints (~/ and ~%) at the moment; we are not telling the interpreter something about the computation we're about to perform, but rather about its product.

Examples

~zod:dojo> (make '~<(%a 42)')
[%7 p=[%1 p=42] q=[%10 p=97 q=[%0 p=1]]]
~zod:dojo> (make '~<(%a.+(.) 42)')
[%7 p=[%1 p=42] q=[%10 p=[p=97 q=[%4 p=[%0 p=1]]] q=[%0 p=1]]]

`~+` "siglus"

[%sgls p=hoon]: cache a computation.

Expands to

p.

Convention

Caches the formula and subject of p in a local cache (generally transient in the current event).

Syntax

Regular: 1-fixed.

Examples

This may pause for a second:

~zod:dojo> %.(25 |=(a=@ ?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a))))))
121.393

This may make you want to press ctrl-c:

~zod:dojo> %.(30 |=(a=@ ?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a))))))
1.346.269

This should work fine:

~zod:dojo> %.(100 |=(a=@ ~+(?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a)))))))
573.147.844.013.817.084.101

`~/` "sigfas"

[%sgfs p=term q=hoon]: jet registration for gate with registered context.

Expands to

~%(p +7 ~ q)

Syntax

Regular: 2-fixed.

Examples

From the kernel:

++  add
  ~/  %add
  |=  [a=@ b=@]
  ^-  @
  ?:  =(0 a)  b
  $(a (dec a), b +(b))

`~&` "sigpam"

[%sgpm p=hoon q=hoon]: debugging printf.

Expands to

q.

Product

Pretty-prints p on the console before computing q.

Discussion

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.

It's most useful for debugging programs.

Syntax

Regular: 2-fixed.

Examples

~zod:dojo> ~&('halp' ~)
'halp'
~

~zod:dojo> ~&  'halp'
           ~
'halp'
~

`~=` "sigtis"

[%sgts p=hoon q=hoon]: detect duplicate.

Expands to

q.

Convention

If p equals q, produce p instead of q.

Discussion

Duplicate nouns are especially bad news in Hoon, because comparing them takes O(n) time. Use ~= to avoid this inefficiency.

Examples

This code traverses a tree and replaces all instances of 32 with 320:

~zod:dojo> =foo |=  a=(tree)
                ?~(a ~ ~=(a [?:(=(n.a 32) 320 n.a) $(a l.a) $(a r.a)]))

~zod:dojo> (foo 32 ~ ~)
[320 ~ ~]

Without ~=, it would build a copy of a completely unchanged tree. Sad!

`~?` "sigwut"

[%sgwt p=hoon q=hoon r=hoon]: conditional debug printf.

Expands to

r.

Convention

If p is true, prettyprints q on the console before computing r.

Syntax

Regular: 4-fixed.

Examples

~zod:dojo> ~?((gth 1 2) 'oops' ~)
~

~zod:dojo> ~?((gth 1 0) 'oops' ~)
'oops'
~

~zod:dojo> ~?  (gth 1 2)
             'oops'
           ~
~

~zod:dojo> ~?  (gth 1 0)
             'oops'
           ~
'oops'
~

`~!` "sigzap"

[%sgzp p=hoon q=hoon]: print type on compilation fail.

Expands to

q.

Convention

If compilation of q fails, prints the type of p in the trace.

Syntax

Regular: 2-fixed.

Examples

~zod:dojo> a
! -find.a

~zod:dojo> ~!('foo' a)
! @t
! find.a

~zod:dojo> ~!  'foo'
           a
! @t
! find.a

Make ; ('mic')

Terminators -- and ==

Runes

~> "siggar"

Expands to

Syntax

Discussion

Examples

~| "sigbar"

Expands to

Convention

Syntax

Examples

~$ "sigbuc"

Expands to

Convention

Syntax

Examples

~_ "sigcab"

Expands to

Convention

Discussion

Examples

~% "sigcen"

Expands to

Convention

Syntax

Discussion

Examples

~< "siggal"

Expands to

Syntax

Discussion

Examples

~+ "siglus"

Expands to

Convention

Syntax

Examples

~/ "sigfas"

Expands to

Syntax

Examples

~& "sigpam"

Expands to

Product

Discussion

Syntax

Examples

~= "sigtis"

Expands to

Convention

Discussion

Examples

~? "sigwut"

Expands to

Convention

Syntax

Examples

~! "sigzap"

Expands to

Convention

Syntax

Examples

`~>` "siggar"

`~|` "sigbar"

`~$` "sigbuc"

`~_` "sigcab"

`~%` "sigcen"

`~<` "siggal"

`~+` "siglus"

`~/` "sigfas"

`~&` "sigpam"

`~=` "sigtis"

`~?` "sigwut"

`~!` "sigzap"