Hoon has the usual program control branches. It also has the usual logical
operators: AND ?&, OR ?|, and NOT ?!. It also has a ?= rune that tests
whether a value matches a given type. In the course of type inference, Hoon
learns from ?= tests in the test condition of ?: ("wutcol")
expressions.
Overview
All ? runes reduce to ?: and/or ?=.
If the condition of an ?: is a ?=, and the ?= is
testing a leg of the subject, the compiler specializes the subject
type for the branches of the ?:. Branch inference also works
for expressions which expand to ?:.
The test does not have to be a single ?=; the compiler can
analyze arbitrary boolean logic (?& ("wutpam"),
?| ("wutbar"), ?! ("wutzap")) with full
short-circuiting. Equality tests (.= ("dottis")) are not
analyzed.
If the compiler detects that the branch is degenerate (only one side is taken), it fails with an error.
Runes
?> "wutgar"
[%wtgr p=hoon q=hoon]: positive assertion.
Expands to
?.(p !! q)
Syntax
Regular: 2-fixed.
Discussion
?> is used to force a crash when some condition p doesn't yield 'yes', %.y.
It can be used for type inference, with the ?= rune, to specify the type of a value.
Examples
> ?>(=(3 3) %foo)
%foo
> ?>(=(3 4) %foo)
ford: build failed
> =a `*`123
> `@`a
nest-fail
> ?>(?=(@ a) `@`a)
123?| "wutbar"
[%wtbr p=(list hoon)]: logical OR.
Expands to
Pseudocode: a, b, c, ... as elements of p:
?:(a & ?:(b & ?:(c & ?:(... ?:(z & |)))))
Desugaring
|-
?~ p
|
?: i.p
&
$(p t.p)
Syntax
Regular: running.
Irregular: |(foo bar baz) is ?|(foo bar baz).
Examples
~zod:dojo> |(=(6 42) =(42 42))
%.y
~zod:dojo> |(=(6 42) =(42 43))
%.n?: "wutcol"
[%wtcl p=hoon q=hoon r=hoon]: branch on a boolean test.
Produces
If p produces yes, %.y, then q. If p produces no, %.n, then r.
If p is not a boolean, compiler yells at you.
Type inference
The subject types of q and r are constrained to match any pattern-matching algebra in p. The analysis, which is conservative, understands any combination of ?=, ?&, ?|, and ?!, and infers the type of the subject appropriately when compiling.
If test analysis reveals that either branch is never taken, or if p is not a boolean, compilation fails. An untaken branch is indicated with mint-lost.
Syntax
Regular: 3-fixed.
Discussion
Short-circuiting in boolean tests works as you'd expect
and includes the expected inference. For instance,
if you write ?&(a b), b is only executed if a is
positive, and compiled with that assumption.
Note also that all other branching expressions reduce to ?:.
Examples
~zod:dojo> ?:((gth 1 0) 3 4)
3
~zod:dojo> ?: (gth 1 0)
3
4
3
~zod:dojo> ?:((gth 1 2) 3 4)
4
~zod:dojo> ?: (gth 1 2)
3
4
4?. "wutdot"
[%wtdt p=hoon q=hoon r=hoon]: branch on a boolean test, inverted.
Expands to
?:(p r q)
Syntax
Regular: 3-fixed.
Discussion
?. is just like ?:, but with its last two subexpressions reversed.
As is usual with inverted forms, use ?. when the yes-case expression is much taller and/or wider than the no-case expression.
Examples
~zod:dojo> ?.((gth 1 2) 3 4)
3
~zod:dojo> ?.(?=(%a 'a') %not-a %yup)
%yup
~zod:dojo> ?. %.y
'this false case is less heavy than the true case'
?: =(2 3)
'two not equal to 3'
'but see how \'r is much heavier than \'q?'
'but see how \'r is much heavier than \'q?'?- "wuthep"
[%wthp p=wing q=(list (pair spec value))]: switch against a union, with no default.
Expands to
Pseudocode: a, b, c, ... as elements of q:
?: ?=(p.a p) q.a
?: ?=(p.b p) q.b
?: ?=(p.c p) q.c
...
~|(%mint-lost !!)
Desugaring
|-
?. q
~|(%mint-lost !!)
?: ?=(p.i.q p)
q.i.q
$(q t.q)
Syntax
Regular: 1-fixed, then jogging.
Discussion
The ?- rune is for a conditional expression in which the type of p determines which branch is taken. Usually the type of p is a union of other types. There is no default branch.
The compiler makes sure that your code neither misses a case of
the union, nor includes a double case that isn't there. This is
not special handling for ?-, just a consequence of the
semantics of ?:, which ?- reduces to.
A missing case will throw the mint-lost error. An extra case
will throw mint-vain.
Examples
~zod:dojo> =cor |= vat=?(%a %b)
?- vat
%a 20
%b 42
==
~zod:dojo> (cor %a)
20
~zod:dojo> (cor %b)
42
~zod:dojo> (cor %c)
! nest-fail?^ "wutket"
[%wtkt p=wing q=hoon r=hoon]: branch on whether a wing
of the subject is a cell.
Expands to
?:(?=(^ p) q r)
Syntax
Regular: 3-fixed.
Discussion
The type of the wing, p, must not be known to be either an atom or a cell, or else you'll get a mint-vain error at compile time. mint-vain means that one of the ?^ branches, q or r, is never taken.
Examples
~zod:dojo> ?^(0 1 2)
! mint-vain
! exit
~zod:dojo> ?^(`*`0 1 2)
2
~zod:dojo> ?^(`*`[1 2] 3 4)
3?< "wutgal"
[%wtgl p=hoon q=hoon]: negative assertion.
Expands to
?:(p !! q)
Syntax
Regular: 2-fixed.
Discussion
?< is used to force a crash when some condition p doesn't yield 'no', %.n.
It can be used for type inference with the ?= rune, much like the ?> rune.
Examples
> ?<(=(3 4) %foo)
%foo
> ?<(=(3 3) %foo)
ford: build failed
> =a `*`[12 14]
> `^`a
nest-fail
> ?<(?=(@ a) `^`a)
[12 14]?+ "wutlus"
[%wtls p=wing q=hoon r=(list (pair spec hoon))]: switch against
a union, with a default.
Expands to
Pseudocode: a, b, c, ... as elements of r:
?: ?=(p.a p) q.a
?: ?=(p.b p) q.b
?: ?=(p.c p) q.c
...
q
Desugaring
|-
?. r
q
?: ?=(p.i.r p)
q.i.r
$(r t.r)
Syntax
Regular: 2-fixed, then jogging.
Discussion
The ?+ rune is for a conditional expression in which the type of p determines which branch is taken. Usually the type of p is a union of other types. If p's type doesn't match the case for any given branch, the default expression, q, is evaluated.
If there is a case that is never taken you'll get a mint-vain error.
Examples
~zod:dojo> =cor |= vat=@tas
?+ vat 240
%a 20
%b 42
==
~zod:dojo> (cor %a)
20
~zod:dojo> (cor %b)
42
~zod:dojo> (cor %c)
240?& "wutpam"
[%wtpm p=(list hoon)]: logical AND.
Expands to
Pseudocode: a, b, c, ... as elements of p:
?.(a | ?.(b | ?.(c | ?.(... ?.(z | &)))))
Desugaring
|-
?~ p
&
?. i.p
|
$(p t.p)
Syntax
Regular: running.
Irregular: &(foo bar baz) is ?&(foo bar baz).
Examples
~zod:dojo> &(=(6 6) =(42 42))
%.y
~zod:dojo> &(=(6 7) =(42 43))
%.n?~ "wutsig"
[%wtsg p=wing q=hoon r=hoon]: branch on whether a wing of the subject is null.
Expands to
?:(?=($~ p) q r)
Syntax
Regular: 3-fixed.
Discussion
It's bad style to use ?~ to test for any zero atom. Use it only for a true null, ~.
Examples
~zod:dojo> =foo ""
~zod:dojo> ?~(foo 1 2)
1?= "wuttis"
[%wtts p=spec q=wing]: test pattern match.
Produces
%.y (yes) if the noun at q is in the type of p; %.n (no) otherwise.
Syntax
Regular: 2-fixed.
Discussion
?= is not as powerful as it might seem. For instance, it
can't generate a loop -- you cannot (and should not) use it to
test whether a * is a (list @). Nor can it validate atomic
auras.
Patterns should be as weak as possible. Unpack one layer of union at a time. Don't confirm things the type system knows.
For example, when matching from a tagged union for the type [%foo p=@ q=[@ @]], the appropriate pattern is [%foo *]. You have one
question, which is whether the head of the noun is %foo.
A common error is find.$, meaning p is not a type.
Examples
~zod:dojo> =bar [%foo %bar %baz]
~zod:dojo> ?=([%foo *] bar)
%.y?@ "wutpat"
[%wtpt p=wing q=hoon r=hoon]: branch on whether a wing of the subject is an atom.
Expands to
?:(?=(@ p) q r)
Syntax
Regular: 3-fixed.
Discussion
The type of the wing, p, must not be known to be either an atom or a cell, or else you'll get a mint-vain error at compile time. mint-vain means that one of the ?@ branches, q or r, is never taken.
Examples
~zod:dojo> ?@(0 1 2)
! mint-vain
! exit
~zod:dojo> ?@(`*`0 1 2)
1
~zod:dojo> ?@(`*`[1 2] 3 4)
4?! "wutzap"
[%wtzp p=hoon]: logical NOT.
Expands to
.=(| p)
Produces the logical NOT of p.
Syntax
Regular: 1-fixed.
Irregular: !foo is ?!(foo).
Examples
~zod:dojo> ?!(.=(1 2))
%.y
~zod:dojo> !&
%.n
~zod:dojo> !|
%.y
~zod:dojo> !(gth 5 6)
%.y