render_example_test.gno
4.84 Kb · 123 lines
1package shuntingyarddemo
2
3// ExampleRender pins the realm Render output as a testable example.
4//
5// The block below is copied verbatim from what gno printed, never hand typed:
6// every RPN string and every value in it is computed by the library under
7// test, so a change in the parser shows up here as a diff rather than as
8// prose.
9func ExampleRender() {
10 print(Render(""))
11 // Output:
12 // # Shunting-yard
13 //
14 // Dijkstra's 1961 algorithm, demoing the [`p/moul/x/daily/shuntingyard`](/p/moul/x/daily/shuntingyard/v0) library: an infix expression becomes reverse Polish notation in one left-to-right pass, with one stack and no recursion, and the RPN evaluates with one more stack.
15 //
16 // ## Worked examples
17 //
18 // | expression | RPN | value | why it is here |
19 // | --- | --- | --- | --- |
20 // | `2+3*4` | `2 3 4 * +` | `14` | multiplication binds tighter |
21 // | `(2+3)*4` | `2 3 + 4 *` | `20` | parentheses beat precedence |
22 // | `10-3-2` | `10 3 - 2 -` | `5` | subtraction associates left |
23 // | `2^3^2` | `2 3 2 ^ ^` | `512` | but power associates right |
24 // | `-3^2` | `3 2 ^ u-` | `-9` | a prefix minus binds looser than a power |
25 // | `3*-2` | `3 2 u- *` | `-6` | the same byte, now unary, after an operator |
26 // | `-7/2` | `7 u- 2 /` | `-3` | integer division truncates toward zero |
27 // | `-7%2` | `7 u- 2 %` | `-1` | and the remainder keeps the dividend's sign |
28 //
29 // Every cell above is computed by the library at render time. The RPN column is the whole output of the conversion: an expression that groups surprisingly groups visibly.
30 //
31 // ## The precedence table is the parser
32 //
33 // Grouping is data here, not control flow. These eight rows are the only thing that decides how an expression reads, which is why adding an operator is a row rather than a branch.
34 //
35 // | operator | precedence | associativity | arity |
36 // | --- | --- | --- | --- |
37 // | `+` | 1 | left | binary |
38 // | `-` | 1 | left | binary |
39 // | `*` | 2 | left | binary |
40 // | `/` | 2 | left | binary |
41 // | `%` | 2 | left | binary |
42 // | `u-` | 3 | right | unary prefix |
43 // | `u+` | 3 | right | unary prefix |
44 // | `^` | 4 | right | binary |
45 //
46 // `u-` and `u+` are the prefix forms. They are separate operators rather than a flag on `-` and `+` because they take one operand instead of two and sit at a different precedence, and conflating the two is how a parser ends up reading `-3^2` as `9`.
47 //
48 // ## What it refuses
49 //
50 // None of these panics. A realm that evaluates a stored expression inside `Render` cannot be made permanently unreadable by one bad input, and an expression that would wrap `int64` says so instead of returning a plausible wrong amount.
51 //
52 // | expression | error |
53 // | --- | --- |
54 // | `1/0` | shuntingyard: division by zero |
55 // | `2^-1` | shuntingyard: negative exponent |
56 // | `9223372036854775807+1` | shuntingyard: int64 overflow |
57 // | `2^64` | shuntingyard: int64 overflow |
58 // | `1 2` | shuntingyard: unexpected number at offset 2 |
59 // | `(1` | shuntingyard: unbalanced "\(" at offset 0 |
60 // | `1$2` | shuntingyard: unexpected character "$" at offset 1 |
61 //
62 // ## Try one
63 //
64 // [`2+3*4`](/r/moul/x/daily/shuntingyarddemo/v0:?e=2%2B3%2A4) · [`(2+3)*4`](/r/moul/x/daily/shuntingyarddemo/v0:?e=%282%2B3%29%2A4) · [`10-3-2`](/r/moul/x/daily/shuntingyarddemo/v0:?e=10-3-2) · [`2^3^2`](/r/moul/x/daily/shuntingyarddemo/v0:?e=2%5E3%5E2) · [`-3^2`](/r/moul/x/daily/shuntingyarddemo/v0:?e=-3%5E2) · [`3*-2`](/r/moul/x/daily/shuntingyarddemo/v0:?e=3%2A-2) · [`-7/2`](/r/moul/x/daily/shuntingyarddemo/v0:?e=-7%2F2) · [`-7%2`](/r/moul/x/daily/shuntingyarddemo/v0:?e=-7%252)
65 //
66 // Or append your own: `?e=2*(3+4)`.
67}
68
69// ExampleRender_expression pins the per-expression page, which is the one a
70// caller reaches with their own string in it.
71func ExampleRender_expression() {
72 print(Render("?e=2*(3%2B4)"))
73 // Output:
74 // # Shunting-yard: 2\*\(3\+4\)
75 //
76 // [back to the demo](/r/moul/x/daily/shuntingyarddemo/v0:)
77 //
78 // ## Tokens
79 //
80 // | # | kind | token | offset |
81 // | --- | --- | --- | --- |
82 // | 0 | number | `2` | 0 |
83 // | 1 | operator | `*` | 1 |
84 // | 2 | ( | `(` | 2 |
85 // | 3 | number | `3` | 3 |
86 // | 4 | operator | `+` | 4 |
87 // | 5 | number | `4` | 5 |
88 // | 6 | ) | `)` | 6 |
89 //
90 // ## Reverse Polish notation
91 //
92 // `2 3 4 + *`
93 //
94 // ## Value
95 //
96 // `14`
97}
98
99// ExampleRender_rejected pins a refusal, so the page that answers bad input
100// is covered as well as the page that answers good input.
101func ExampleRender_rejected() {
102 print(Render("?e=1/0"))
103 // Output:
104 // # Shunting-yard: 1/0
105 //
106 // [back to the demo](/r/moul/x/daily/shuntingyarddemo/v0:)
107 //
108 // ## Tokens
109 //
110 // | # | kind | token | offset |
111 // | --- | --- | --- | --- |
112 // | 0 | number | `1` | 0 |
113 // | 1 | operator | `/` | 1 |
114 // | 2 | number | `0` | 2 |
115 //
116 // ## Reverse Polish notation
117 //
118 // `1 0 /`
119 //
120 // ## Rejected while evaluating it
121 //
122 // shuntingyard: division by zero
123}