diff --git a/README.md b/README.md index 7a13271..4e21737 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ UIPs can be divided into the following categories: | [0126](./UIPS/UIP-0126.md) | Pierport Protocol | ~littul-pocdev | Draft | Process | | [0127](./UIPS/UIP-0127.md) | Lagoon IEEE 754 Reals | ~lagrev-nocfep | Draft | Standards | | [0128](./UIPS/UIP-0128.md) | Monadic Scry Interface | ~fodwyt-ragful, ~mastyr-bottec | Draft | Standards | +| [0129](./UIPS/UIP-0129.md) | Positive Assertion Rune | ~lagrev-nocfep | Draft | Standards | ## Background diff --git a/UIPS/UIP-0129.md b/UIPS/UIP-0129.md new file mode 100644 index 0000000..2f0b9a4 --- /dev/null +++ b/UIPS/UIP-0129.md @@ -0,0 +1,78 @@ +--- +uip: "0129" +title: Assertion Rune +description: "Add a ~. sigdot rune to handle positive assertions cleanly" +author: ~lagrev-nocfep (@sigilante) +status: Draft +type: Standards Track +category: Hoon +created: 2024-03-25 +--- + +## Abstract + +Hoon supports several related runes for error handling and debugging: + +- `~&` is the classic `printf` side-effect rune. +- `~|` adds a stack annotation in case of crash. +- `~?` adds a debugging printf +- `?>` is a positive assertion (crash if fail). +- `?<` is a negative assertion (crash if pass). + +A common design pattern in Hoon is to have an assertion to succeed, then to wrap +an intended error mesage with `~|` around `!!`. By coupling the `?:`, `~|`, and +`!!` together, we can achieve a more lapidary yet still clear code expression. +We propose to call this the `~.` sigdot rune (patterned after `?.` wutdot +"lest"). + +``` +~: test-to-pass + 'message-on-fail' +continuation if pass +``` + +The advantage of this rune is that it will avoid the footgun of an assertion +passing but the message still printing. (I.e. you can do other things in a +`~|`-gated branch.) + +## Specification + +The `~.` rune should desugar from: + +``` +~. test-to-pass + 'message-on-fail' +continuation if pass +``` + +to: + +``` +?. test-to-pass + ~| 'message-on-fail' !! +continuation if pass +``` + +`~:` differs from `~?` in that it crashes with the error message (rather than +the conditional printf). + +This involves two modest changes, one to the parser and another to the AST in +`/sys/hoon`. `~.` collides with the empty `@ta`, `*knot`, but should be +generally distinguishable through precedence rules in syntax. + +## Rationale + +- Producing code that cleanly wraps an error message around an implicit crash is + clear to read and write for many programmers. +- Offering a rune which allows `?.`-like assertion checks without incorrectly + invoking other `~|` stack trace messages in case of error will make failures + more clear to process. + +## Backwards Compatibility + +- This should be bundled into a Hoon kelvin decrement. It will not break any + known existing code. + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE.md).