From 3f40b3459f3a02c57cc02098349fb291d4e761a2 Mon Sep 17 00:00:00 2001 From: Sigilante <57601680+sigilante@users.noreply.github.com> Date: Sun, 3 Mar 2024 13:02:28 -0600 Subject: [PATCH 1/7] Create UIP-0120.md --- UIPS/UIP-0120.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 UIPS/UIP-0120.md diff --git a/UIPS/UIP-0120.md b/UIPS/UIP-0120.md new file mode 100644 index 0000000..23276d1 --- /dev/null +++ b/UIPS/UIP-0120.md @@ -0,0 +1,74 @@ +--- +uip: 0120 +title: Assertion Rune +description: Add a ~? 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. +- `?>` 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. + +``` +~? 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 +``` + +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). From 5eccb28a09790307858170f6a1a9890b182a9ba0 Mon Sep 17 00:00:00 2001 From: Sigilante <57601680+sigilante@users.noreply.github.com> Date: Wed, 20 Mar 2024 09:43:23 -0500 Subject: [PATCH 2/7] Update UIP-0120.md --- UIPS/UIP-0120.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/UIPS/UIP-0120.md b/UIPS/UIP-0120.md index 23276d1..dcc2ecb 100644 --- a/UIPS/UIP-0120.md +++ b/UIPS/UIP-0120.md @@ -1,7 +1,7 @@ --- uip: 0120 title: Assertion Rune -description: Add a ~? rune to handle positive assertions cleanly +description: Add a ~! sigzap rune to handle positive assertions cleanly author: ~lagrev-nocfep (@sigilante) status: Draft type: Standards Track @@ -15,25 +15,27 @@ 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 `~!` sigzap rune. ``` -~? test-to-pass +~! test-to-pass 'message-on-fail' continuation if pass ``` ## Specification -The `~?` rune should desugar as follows: +The `~!` rune should desugar as follows: ``` -~? test-to-pass +~! test-to-pass 'message-on-fail' continuation if pass ``` @@ -44,6 +46,9 @@ continuation if pass 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: ``` From 49c4a2ed303f454aaa931e3f970942d1e1c3eaf4 Mon Sep 17 00:00:00 2001 From: Sigilante <57601680+sigilante@users.noreply.github.com> Date: Wed, 20 Mar 2024 09:46:10 -0500 Subject: [PATCH 3/7] Update UIP-0120.md --- UIPS/UIP-0120.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/UIPS/UIP-0120.md b/UIPS/UIP-0120.md index dcc2ecb..32931c8 100644 --- a/UIPS/UIP-0120.md +++ b/UIPS/UIP-0120.md @@ -1,7 +1,7 @@ --- uip: 0120 title: Assertion Rune -description: Add a ~! sigzap rune to handle positive assertions cleanly +description: Add a ~: sigcol rune to handle positive assertions cleanly author: ~lagrev-nocfep (@sigilante) status: Draft type: Standards Track @@ -22,20 +22,20 @@ Hoon supports several related runes for error handling and debugging: 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 `~!` sigzap rune. +We propose to call this the `~:` sigcol rune. ``` -~! test-to-pass +~: test-to-pass 'message-on-fail' continuation if pass ``` ## Specification -The `~!` rune should desugar as follows: +The `~:` rune should desugar as follows: ``` -~! test-to-pass +~: test-to-pass 'message-on-fail' continuation if pass ``` @@ -46,7 +46,7 @@ continuation if pass continuation if pass ``` -`~!` differs from `~?` in that it crashes with the error message (rather than the +`~:` differs from `~?` in that it crashes with the error message (rather than the conditional printf). Alternatively, it could desugar via `?>`, for instance: From c3710c18ca44e2fc6d1891c7ade6edfc18e41af5 Mon Sep 17 00:00:00 2001 From: Sigilante <57601680+sigilante@users.noreply.github.com> Date: Wed, 20 Mar 2024 09:46:26 -0500 Subject: [PATCH 4/7] Update UIP-0120.md --- UIPS/UIP-0120.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/UIPS/UIP-0120.md b/UIPS/UIP-0120.md index 32931c8..11448e4 100644 --- a/UIPS/UIP-0120.md +++ b/UIPS/UIP-0120.md @@ -1,7 +1,7 @@ --- uip: 0120 title: Assertion Rune -description: Add a ~: sigcol rune to handle positive assertions cleanly +description: "Add a ~: sigcol rune to handle positive assertions cleanly" author: ~lagrev-nocfep (@sigilante) status: Draft type: Standards Track From 7f016e52e9c157db34f958cee4d1bc2a7d9b169f Mon Sep 17 00:00:00 2001 From: Sigilante <57601680+sigilante@users.noreply.github.com> Date: Mon, 15 Jul 2024 13:11:28 -0500 Subject: [PATCH 5/7] Update UIP-0120.md --- UIPS/UIP-0120.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/UIPS/UIP-0120.md b/UIPS/UIP-0120.md index 11448e4..33c1bc4 100644 --- a/UIPS/UIP-0120.md +++ b/UIPS/UIP-0120.md @@ -1,5 +1,5 @@ --- -uip: 0120 +uip: "013X" title: Assertion Rune description: "Add a ~: sigcol rune to handle positive assertions cleanly" author: ~lagrev-nocfep (@sigilante) From 067811fffad89e28551312c04eb7eb5c60e1ff57 Mon Sep 17 00:00:00 2001 From: Sigilante Date: Mon, 15 Jul 2024 15:06:53 -0500 Subject: [PATCH 6/7] Update numbering and proposal. --- UIPS/{UIP-0120.md => UIP-0129.md} | 45 +++++++++++++++---------------- 1 file changed, 22 insertions(+), 23 deletions(-) rename UIPS/{UIP-0120.md => UIP-0129.md} (59%) diff --git a/UIPS/UIP-0120.md b/UIPS/UIP-0129.md similarity index 59% rename from UIPS/UIP-0120.md rename to UIPS/UIP-0129.md index 33c1bc4..2f0b9a4 100644 --- a/UIPS/UIP-0120.md +++ b/UIPS/UIP-0129.md @@ -1,7 +1,7 @@ --- -uip: "013X" +uip: "0129" title: Assertion Rune -description: "Add a ~: sigcol rune to handle positive assertions cleanly" +description: "Add a ~. sigdot rune to handle positive assertions cleanly" author: ~lagrev-nocfep (@sigilante) status: Draft type: Standards Track @@ -22,7 +22,8 @@ Hoon supports several related runes for error handling and debugging: 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. +We propose to call this the `~.` sigdot rune (patterned after `?.` wutdot +"lest"). ``` ~: test-to-pass @@ -30,49 +31,47 @@ We propose to call this the `~:` sigcol rune. 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 as follows: +The `~.` rune should desugar from: ``` -~: test-to-pass +~. test-to-pass 'message-on-fail' continuation if pass ``` +to: + ``` -?: test-to-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. +`~:` 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`. It does not collide with any known Hoon or atom literal syntax. +`/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 decrement. It will not break any known - existing code. +- This should be bundled into a Hoon kelvin decrement. It will not break any + known existing code. ## Copyright From ae651ed9a637ec37671be4a6522233667cf24a1f Mon Sep 17 00:00:00 2001 From: Sigilante Date: Mon, 15 Jul 2024 15:08:00 -0500 Subject: [PATCH 7/7] Include in table. --- README.md | 1 + 1 file changed, 1 insertion(+) 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