~. sigdot Positive Assertion Rune

UIPS/UIP-0120.md

@@ -0,0 +1,79 @@
+---
+uip: 0120
+title: Assertion Rune
+description: "Add a ~: sigcol 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 `~:` sigcol rune.
+
+```
+~:  test-to-pass
+  'message-on-fail'
+continuation if pass
+```
+
+## Specification
+
+The `~:` rune should desugar as follows:
+
+```
+~:  test-to-pass
+  'message-on-fail'
+continuation if pass
+```
+
+```
+?:  test-to-pass
+  ~|  'message-on-fail'  !!
+continuation if pass
+```
+
+`~:` differs from `~?` in that it crashes with the error message (rather than the
+conditional printf).
+
+Alternatively, it could desugar via `?>`, for instance:
+
+```
+~|  'message-on-fail'
+  ?>  test-to-pass
+continuation-if-pass
+```
+
+This latter branch would preserve the message in the stack trace if another element
+of the tail fails.  There may be a cleaner way to compose an expression using `?>`,
+but the `?:` variant seems to satisfy our need.
+
+This involves two modest changes, one to the parser and another to the AST in
+`/sys/hoon`.  It does not collide with any known Hoon or atom literal syntax.
+
+## Rationale
+
+- Producing code that cleanly wraps an error message around an implicit crash is
+  clear to read and write for many programmers.
+
+## Backwards Compatibility
+
+- This should be bundled into a Hoon decrement.  It will not break any known
+  existing code.
+
+## Copyright
+
+Copyright and related rights waived via [CC0](../LICENSE.md).