git.iko.soy/urbit.org
on 3fee830 help sign in
urbit.org/docs/programming/twig/test.md
143 lines 3.4 kB history raw
1---
2sort: 9
3---
5# Tests (`?` runes)
6
7Hoon has the usual branches and logical tests. For pattern
8matching, it also has a `$fits` twig that tests whether a value
9matches the icon of a mold. And it has branch inference,
10learning from `$fits` tests in the condition of `:if` twigs.
12## Overview
14All `?` runes expand to `$if` (`?:`) and/or `$fits` (`?=`).
16If the condition of an `$if` is a `$fits`, *and* the `$fits` is
17testing a leg of the subject, the compile specializes the subject
18span for the branches of the `$if`. Branch inference also works
19for twigs which expand to `$if`.
21The test does not have to be a single `$fits`; the compiler can
22analyze arbitrary boolean logic (`$and`, `$or`, `$not`) with full
23short-circuiting. Equality tests (`=`) are *not* analyzed.
25If the compiler detects that the branch is degenerate (only one
26side is taken), it fails with an error.
28## Regular forms
30The rune prefix is `?`. Suffixes: `=` for `:fits`, `:` for
31`:if`, `.` for `:lest`, `-` for `:case`, `+` for `:deft`, `|` for
32`:or`, `&` for `:and`, `!` for `:not`, `>` for `$sure`, `<` for
33`$deny`, `^` for `:ifcl`, `@` for `:ifat`, `~` for `:ifno`.
35### `:fits`, `?=`, "wuttis", `{$fits p/moss q/twig}`
37Syntax: *2-fixed*.
39The product: `&` if the product of `q` is in the icon of `p`,
40`|` otherwise.
42The icon of `p` must be finite / nonrecursive. In general,
43always match one layer of a data structure at a time.
45### `:if`, `?:`, "wutcol", `{$if p/twig q/twig r/twig}`
47Syntax: *3-fixed*.
49The product: `q` if `p` has the value `&` (0), `r` for `|` (1).
50`p` must be statically boolean.
52### `:lest`, `?.`, "wutdot", `{$lest p/twig q/twig r/twig}`
54Syntax: *3-fixed*.
56Expands to: `:if(p r q)`.
58### `:case`, `?-`, "wuthep", `{$case p/twig q/(list (pair moss twig))}`
60Syntax: *1-fixed*, then *jogging*.
62Expands by:
64```
65|-(?~(q [%lost p] [%if [%fits p.i.q p] q.i.q $(q t.q)]))
66```
68A pattern-matching switch. Fails to compile if the pattern is
69incomplete or irrelevant.
71### `:deft`, `?+`, "wutlus", `{$case p/twig q/twig r/(list (pair moss twig))}`
73Syntax: *1-fixed*, then *jogging*.
75Expands by: `[%case p (weld r [[%base %noun] q])]`
77A pattern-matching switch, with default.
79### `:or`, `?|`, "wutbar", `{$or p/(list twig)}`
81Syntax: *running*.
83Expands by: `|-(?~(p [%rock %f |] [%if i.p [%rock %f &]] $(p t.p)))`
85Logical or (`&` (`0`) is yes, `|` (`1`) is no).
87### `:and`, `?&`, "wutpam", `{$and p/(list twig)}`
89Syntax: *running*.
91Expands by: `|-(?~(p [%rock %f &] [%if i.p $(p t.p) [%rock %f |]]))`
93Logical and (`&` (`0`) is yes, `|` (`1`) is no).
95### `:not`, `?!`, "wutzap", `{$not p/twig}`
97Syntax: *1-fixed*.
99Expands to: `:if(p %| %&)`.
101Logical not (`&` (`0`) is yes, `|` (`1`) is no).
103### `:sure`, `?>`, "wutgar", `{$sure p/twig q/twig}`
105Expands to: `:if(p q !!)`.
107An assertion.
109### `:deny`, `?<`, "wutgal", `{$deny p/twig q/twig}`
111Expands to: `:if(p !! q)`.
113A negative assertion.
115### `:ifno`, `?~`, "wutsig", `{$ifno p/twig q/twig r/twig}`
117Expands to: `:if(:fits($~ p) q r)`.
119Branches on whether `p` is null.
121### `:ifat`, `?@`, "wutpat", `{$ifat p/twig q/twig r/twig}`
123Expands to: `:if(:fits(@ p) q r)`.
125Branches on whether `p` is atomic.
127### `:ifcl`, `?^`, "wutket", `{$ifat p/twig q/twig r/twig}`
129Expands to: `:if(:fits(^ p) q r)`.
131Branches on whether `p` is cellular.
133## Irregular forms
135### Light logic
137Translations:
139```
140&(a b c) ?&(a b c)
141|(a b c) ?|(a b c)
142!a ?!(a)
143```