In a Ruby case/in, what does the ^ pin operator do, and what goes wrong when an existing local variable is used without it?

## Bare names bind — always In a pattern, a lower-case identifier is a **variable pattern**. It matches any value and binds it. This is what makes `in {text:}` or `in [first, *rest]` useful, but it has a sharp edge: it applies even when a local with that name already exists. ```ruby expected_team = "T1" case {team: "T9", text: "hi"} in {team: expected_team, text:} "accepted from #{expected_team}" end # => "accepted from T9" — expected_team was overwritten ``` The branch matched a payload from the wrong workspace and clobbered the variable. Ruby's reference uses the same example and labels the real result "local variable just rewritten". No warning is issued: this is the defined meaning of a bare name in a pattern. ## The pin operator `^name` turns a variable into a **value pattern**: its current value is compared with `===`, as for any value pattern. ```ruby case {team: "T9", text: "hi"} in {team: ^expected_team, text:} "accepted" else "rejected" end # => "rejected" ``` | Pattern entry | Meaning | |---|---| | `team:` | require key, bind its value to `team` | | `team: t` | require key, bind its value to `t` | | `team: expected_team` | require key, **rebind** `expected_team` (the trap) | | `team: ^expected_team` | require key, value must `===` the current `expected_team` | | `team: ALLOWED_TEAM` | constant: a value pattern, no pin needed | | `team: ^@team_id` | pin an instance variable (3.1+) | | `team: ^(settings.fetch(:team))` | pin an arbitrary expression (3.1+) | ## What can be pinned The reference's pattern grammar lists the pinnable value patterns: - `^local_variable` - `^instance_variable`, `^class_variable`, `^global_variable` - `^(expression)` — any expression, in parentheses Ruby 3.0 supported only local variables; 3.1 added the other variable kinds and parenthesised expressions. Method calls must go through `^(...)`: a bare `^settings.team` is not a valid pin. ## Equality inside one pattern A pinned name may refer to a variable bound **earlier in the same pattern**. That expresses "these two positions hold the same value" without a guard: ```ruby case event in {user: {id:}, mentions: [*, ^id, *]} "user mentioned themselves" end ``` The reference's example does the same with a school level: it binds `school:` and then requires `level: ^school` inside a later nested hash. ## Pin versus guard Both compare against outside values, but they differ: 1. A **pin** is part of the pattern, so it participates in structural matching, works inside nested arrays and find patterns, and uses `===`. 2. A **guard** (`in {team:} if team == expected_team`) runs after the pattern matched and can express any boolean condition, but only on `case/in` branches, not on the one-line forms. Prefer the pin for simple equality against a known value; use a guard for comparisons such as `ts > cutoff`. ## Webhook example A router that accepts events only from its own workspace and channel: ```ruby def route(event) case event in {team: ^@team_id, channel: ^(@config.fetch(:channel)), type: "message", text:} handle(text) in {team: ^@team_id} :ignored_other_channel else :foreign_workspace end end ``` Without the pins, the first branch would match every message from every workspace and overwrite nothing useful — or, with local variables, overwrite the very values it was meant to check. ## Checklist - Every existing variable you mean to **compare against** needs `^`. - Constants never need `^`. - Use `^(expr)` for method calls and computations. - Reuse a name bound earlier in the pattern with `^name` to require equal values.