Why can a shorthand that substitutes argument text before parsing compute the wrong value inside a larger expression?

## What the toolchain actually receives A text-level shorthand is a rule applied **before** the language's grammar is applied. The characters of the call site are replaced by the characters of the body, with every occurrence of a parameter replaced by the characters of the matching argument, and only then is the whole file parsed. Nothing in that sequence knows about operators, operands, precedence or values: at substitution time the program is still text. That is the whole source of the surprise. The mental model most people carry — "the shorthand works out a value and hands it back, like a call" — is right about intent and wrong about mechanism, and the bug lives at the mechanism. ## The two boundaries where grouping leaks - **The argument boundary.** A parameter appears inside the body beside the body's own operators. A squaring shorthand whose body is `v * v` turns the argument `a + b` into `a + b * a + b`, because the multiplication the body supplied binds tighter than the addition the argument contained. - **The result boundary.** The body's outermost operator meets whatever surrounds the call. A body that ends in a loosely binding construct loses to a tighter operator written after the call. - **Neither is visible at the definition.** The definition parses fine on its own; the damage depends entirely on what the call site looks like, which is why a shorthand can be used correctly a hundred times and wrongly on the hundred-and-first. - **The result is often *partly* right.** That is what keeps it alive in a codebase. ## A worked expansion ``` define LARGER(a, b) as if a > b then a else b scaled = LARGER(width, height) * 2 // what the parser sees, and how it groups it scaled = if width > height then width else (height * 2) ``` Trace both branches. When `height` is the larger value, the else branch fires and the result is `height * 2` — exactly what was intended. When `width` is the larger value, the then branch fires and the result is `width`, never scaled. The shorthand is correct for half its inputs. A test that only ever exercises the second ordering passes, and the defect ships. ## The textual discipline, and what it does not cover Where only a text-level facility is available, the convention that closes the precedence hole is mechanical: 1. Parenthesise **every use of every parameter** inside the body, so each substituted argument becomes one grouped operand. 2. Wrap the **entire body** in parentheses, so the expansion becomes one grouped expression to whatever surrounds it. 3. Keep the body a **single expression** — never a sequence of statements. Applied to the worked example, the body becomes `( if (a) > (b) then (a) else (b) )` and the call site groups as `( ... ) * 2` whichever branch wins. Three honest limits. The discipline is a convention that nothing enforces, so one shorthand written in a hurry reopens the hole. Parentheses are an expression-level device, so they do nothing for a body that expands to more than one statement. And the diagnostics, when the paste does produce something ungrammatical, are reported where the failing characters are — inside text the author never typed. ## Why a tree-level rewrite does not have this class of bug A transformer that works on a parsed tree is handed the call as a node, with its arguments already parsed into nodes of their own, and returns a node. Grafting a node into the caller's tree cannot change how the caller's operators were grouped, because that grouping was decided by the parser before the transformer ran, and there is no second parse in which it could be re-decided. | | Text substitution | Tree rewrite | |---|---|---| | What it receives | characters at the call site | the call and its arguments as parsed nodes | | When grouping is decided | after substitution, by parsing the result | before the rewrite, by the parse that produced the nodes | | What it produces | a run of characters | one node, grafted whole | | Accidental precedence surprise | possible at both boundaries | does not arise | | Where a diagnostic points | into the expanded characters | wherever the transformer chooses to point it | The guarantee is precise and worth stating precisely: the *accidental* regrouping disappears. A transformer can still build a subtree that means the wrong thing — it simply cannot do so by having its output re-parsed in a context it did not anticipate.