fc1a9ce · urbit.org · git.iko.soy

docs/reference/rune/wut/ban.udon+18−4

compare with master

unifiedsplit

@@ -5,9 +5,9 @@

5 ==

6;>

7

8−# `?> "wutgar"`

8+# `?> "wutban"`

9

10−`[%wtgr p=hoon q=hoon]`: positive assertion.

10+`[%wtbn p=hoon q=hoon]`: positive assertion.

11

12## Expands to

13

@@ -19,12 +19,26 @@

19

20Regular: *2-fixed*.

21

22+## Discussion

23+

24+`?>` is used to force a crash when some condition `p` doesn't yield 'yes', `%.y`.

25+

26+It can be used for type inference, with the `?=` rune, to specify the type of a value.

27+

22## Examples

28## Examples

23

29

24```

30```

25−~zod:dojo> ?>(=(3 3) %foo)

31+> ?>(=(3 3) %foo)

26%foo

32%foo

27

33

28−~zod:dojo> ?>(=(3 4) %foo)

34+> ?>(=(3 4) %foo)

29ford: build failed

35ford: build failed

36+

37+> =a `*`123

38+

39+> `@`a

40+nest-fail

41+

42+> ?>(?=(@ a) `@`a)

43+123

30```

44```

docs/reference/rune/wut/col.udon+5−10

@@ -14,16 +14,11 @@

14If `p` produces yes, `%.y`, then `q`. If `p` produces no, `%.n`, then `r`.

15If `p` is not a boolean, compiler yells at you.

16

17−The subjects of `q` and `r` are constrained to match any

17+### Type inference

18−pattern-matching algebra in `p`. The analysis, which is

19−conservative, understands any combination of [`?=` ("wuttis")](../tis/),

20−[`?&` ("wutpad")](../pad/), [`?|` ("wutbar")](../bar/), and

21−[`?!` ("wutzap")](../zap/), and reduces the subject appropriately when

22−compiling.

23

18

19+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 [`?=`](../tis/), [`?&`](../pad/), [`?|`](../bar/), and [`?!`](../zap/), and infers the type of the subject appropriately when compiling.

20+

24−If test analysis reveals that either branch is not taken,

21+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`.

25−or if `p` is not a boolean, compilation fails. However,

26−an untaken branch can be indicated with the `%lost` hoon.

27

22

28## Syntax

23## Syntax

29

24

@@ -36,7 +31,7 @@ and includes the expected inference. For instance,

36if you write `?&(a b)`, `b` is only executed if `a` is

31if you write `?&(a b)`, `b` is only executed if `a` is

37positive, and compiled with that assumption.

32positive, and compiled with that assumption.

38

33

39−Note also that all other branching hoons reduce to `?:`.

34+Note also that all other branching expressions reduce to `?:`.

40

35

41## Examples

36## Examples

42

37

docs/reference/rune/wut/dot.udon+3−2

@@ -21,8 +21,9 @@ Regular: *3-fixed*.

21

22## Discussion

23

24−As usual with inverted forms, use `?.` ("wutdot") when the yes-case

24+`?.` is just like `?:`, but with its last two subexpressions reversed.

25+

25−expression is much taller and/or wider than the no-case expression.

26+As is usual with inverted forms, use `?.` when the yes-case expression is much taller and/or wider than the no-case expression.

26

27

27## Examples

28## Examples

28

29

docs/reference/rune/wut/hep.udon+8−7

@@ -7,8 +7,7 @@

7

8# `?- "wuthep"`

9

10−`[%wthp p=wing q=(list (pair model value))]`: switch against a

10+`[%wthp p=wing q=(list (pair spec value))]`: switch against a union, with no default.

11−union, with no default.

12

11

13## Expands to

12## Expands to

14

13

@@ -39,10 +38,12 @@ Regular: *1-fixed*, then *jogging*.

39

38

40## Discussion

39## Discussion

41

40

41+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.

42+

42The compiler makes sure that your code neither misses a case of

43The compiler makes sure that your code neither misses a case of

43the union, nor includes a double case that isn't there. This is

44the union, nor includes a double case that isn't there. This is

44−not special handling for `?-` ("wuthep"), just a consequence of the

45+not special handling for `?-`, just a consequence of the

45−semantics of `?:` ("wutcol"), which `?-` reduces to.

46+semantics of `?:`, which `?-` reduces to.

46

47

47A missing case will throw the `mint-lost` error. An extra case

48A missing case will throw the `mint-lost` error. An extra case

48will throw `mint-vain`.

49will throw `mint-vain`.

@@ -50,10 +51,10 @@ will throw `mint-vain`.

50## Examples

51## Examples

51

52

52```

53```

53−~zod:dojo> =cor |= vat=?($a $b)

54+~zod:dojo> =cor |= vat=?(%a %b)

54 ?- vat

55 ?- vat

55− $a 20

56+ %a 20

56− $b 42

57+ %b 42

57 ==

58 ==

58

59

59~zod:dojo> (cor %a)

60~zod:dojo> (cor %a)

docs/reference/rune/wut/ket.udon+1−1

@@ -22,7 +22,7 @@ Regular: *3-fixed*.

22

23## Discussion

24

25−Regular form: *3-fixed*

25+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.

26

27## Examples

28

docs/reference/rune/wut/led.udon+16−2

@@ -19,12 +19,26 @@

19

20Regular: *2-fixed*.

21

22+## Discussion

23+

24+`?<` is used to force a crash when some condition `p` doesn't yield 'no', `%.n`.

25+

26+It can be used for type inference with the `?=` rune, much like the `?>` rune.

27+

22## Examples

28## Examples

23

29

24```

30```

25−~zod:dojo> ?<(=(3 4) %foo)

31+> ?<(=(3 4) %foo)

26%foo

32%foo

27

33

28−~zod:dojo> ?<(=(3 3) %foo)

34+> ?<(=(3 3) %foo)

29ford: build failed

35ford: build failed

36+

37+> =a `*`[12 14]

38+

39+> `^`a

40+nest-fail

41+

42+> ?<(?=(@ a) `^`a)

43+[12 14]

30```

44```

docs/reference/rune/wut/lus.udon+6−4

@@ -39,15 +39,17 @@ Regular: *2-fixed*, then *jogging*.

39

40## Discussion

41

42−An extra case will throw `mint-vain`. A lost case defaults.

42+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.

43+

44+If there is a case that is never taken you'll get a `mint-vain` error.

43

45

44## Examples

46## Examples

45

47

46```

48```

47−~zod:dojo> =cor |= vat=?($a $b)

49+~zod:dojo> =cor |= vat=?(%a %b)

48 ?+ vat 240

50 ?+ vat 240

49− $a 20

51+ %a 20

50− $b 42

52+ %b 42

51 ==

53 ==

52

54

53~zod:dojo> (cor %a)

55~zod:dojo> (cor %a)

docs/reference/rune/wut/pad.udon+1−1

@@ -7,7 +7,7 @@

7

8# `?& "wutpad"`

9

10−`[%wtpm p=(list hoon)]`: logical AND.

10+`[%wtpd p=(list hoon)]`: logical AND.

11

12## Expands to

13

docs/reference/rune/wut/sig.udon+2−4

@@ -7,8 +7,7 @@

7

8# `?~ "wutsig"`

9

10−`[%wtsg p=wing q=hoon r=hoon]`: branch on whether a wing

10+`[%wtsg p=wing q=hoon r=hoon]`: branch on whether a wing of the subject is null.

11−of the subject is null.

12

11

13## Expands to

12## Expands to

14

13

@@ -22,8 +21,7 @@ Regular: *3-fixed*.

22

21

23## Discussion

22## Discussion

24

23

25−It's bad style to use `?~` to test for any zero atom. Use it

24+It's bad style to use `?~` to test for any zero atom. Use it only for a true null, `~`.

26−only for a true null, `~`.

27

25

28## Examples

26## Examples

29

27

docs/reference/rune/wut/tis.udon+5−6

@@ -11,8 +11,7 @@

11

12## Produces

13

14−`%.y` (yes) if the noun at `q` is in the type of `p`;

14+`%.y` (yes) if the noun at `q` is in the type of `p`; `%.n` (no) otherwise.

15−`%.n` (no) otherwise.

16

15

17## Syntax

16## Syntax

18

17

@@ -20,7 +19,7 @@ Regular: *2-fixed*.

20

19

21## Discussion

20## Discussion

22

21

23−`?=` ("wuttis") is not as powerful as it might seem. For instance, it

22+`?=` is not as powerful as it might seem. For instance, it

24can't generate a loop -- you cannot (and should not) use it to

23can't generate a loop -- you cannot (and should not) use it to

25test whether a `*` is a `(list @)`. Nor can it validate atomic

24test whether a `*` is a `(list @)`. Nor can it validate atomic

26auras.

25auras.

@@ -28,11 +27,11 @@ auras.

28Patterns should be as weak as possible. Unpack one layer of

27Patterns should be as weak as possible. Unpack one layer of

29union at a time. Don't confirm things the type system knows.

28union at a time. Don't confirm things the type system knows.

30

29

31−For example, when matching a book containing a page `[%foo p=@

30+For example, when matching from a tagged union for the type `[%foo p=@

32−q=[@ @]]`, the proper pattern is `[%foo *]`. You have one

31+q=[@ @]]`, the appropriate pattern is `[%foo *]`. You have one

33question, which is whether the head of the noun is `%foo`.

32question, which is whether the head of the noun is `%foo`.

34

33

35−A common error is `find.$`, meainng `p` is not a type.

34+A common error is `find.$`, meaning `p` is not a type.

36

35

37## Examples

36## Examples

38

37

docs/reference/rune/wut/vat.udon+5−2

@@ -7,8 +7,7 @@

7

8# `?@ "wutvat"`

9

10−`[%wtpt p=wing q=hoon r=hoon]`: branch on whether a wing

10+`[%wtpt p=wing q=hoon r=hoon]`: branch on whether a wing of the subject is an atom.

11−of the subject is an atom.

12

11

13## Expands to

12## Expands to

14

13

@@ -20,6 +19,10 @@ of the subject is an atom.

20

19

21Regular: *3-fixed*.

20Regular: *3-fixed*.

22

21

22+## Discussion

23+

24+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.

25+

23## Examples

26## Examples

24

27

25```

28```

docs/reference/rune/wut/zap.udon+1−1

@@ -15,7 +15,7 @@

15.=(| p)

16```

17

18−Produces the logical "not" of `p`.

18+Produces the logical NOT of `p`.

19

20## Syntax

21