Scoped Refinements

## Lexical scope in one sentence A **lexically scoped** feature depends on where code is *written*; a **dynamically scoped** one depends on who is *calling* at run time. Ruby refinements are lexical: whether `text.to_slug` sees the `Slugs` refinement is decided by whether that call's source text follows a `using Slugs` in the same file, class body or module body. ## The classic surprise 1. `slugs.rb` declares `refine String` with `to_slug`. 2. `slugger.rb` defines `Slugger.call(text)`, which returns `text.to_slug`. It has no `using`. 3. `app.rb` requires both files, runs `using Slugs`, and calls `Slugger.call("Hello World")`. 4. Ruby raises `NoMethodError` inside `Slugger.call`, because that call site in `slugger.rb` was never refined. The caller's activation does not flow into the callee. This is deliberate: a library cannot be broken by refinements that its callers happen to activate. ## What does carry the refinement | Code | Refined? | Why | |---|---|---| | a call written after `using` in the same file | yes | the call site is inside the activated scope | | a method defined after `using`, called from another file | yes | the method's body was written in the activated scope | | a block written after `using`, passed to a method elsewhere | yes | the block's body is written in the activated scope | | a method in another file, called from the refined file | no | its body was written outside the scope | | a later reopening of the same class without its own `using` | no | each class body activates separately | | code in a file loaded with `require` after `using` | no | refinements do not cross file boundaries | The second row is the useful half of the rule: a class can `using Slugs` inside its own body and offer methods such as `Article#slug` that work for every caller, while the rest of the program never sees `String#to_slug`. ## Precedence when refinements overlap - **Several refinements of the same class**: the refinements active at a call site are searched in reverse order of activation, so the most recent `using` wins. - **Refinements versus the class hierarchy**: lookup checks, for each class in turn, its refinements, then its prepended modules, the class itself and its included modules, before moving to the superclass. A method defined in a **subclass** therefore beats a refinement of a **superclass**: refining `Numeric#/` does not change `1 / 2`, because `Integer#/` is found first. A refinement of `Numeric` that adds a method `Integer` lacks does apply to integers. - **`super` in a refined method** calls the refined class's original method, even if another refinement of it is active in the same scope. ## Why Ruby chose lexical scope Dynamic scoping would let any caller change how code it calls behaves. A library method that calls `to_s` could return something different depending on which application file happened to call it — exactly the global-patch problem refinements were designed to avoid. With lexical scope, the author of each file controls which refinements that file's code sees, and a reader can tell by looking at the `using` lines above the code. The cost is the surprise in this question: refinements do not flow into helpers, so a helper that depends on a refined method must activate the refinement itself. ## Consequences for design - Refinements cannot change how third-party code behaves: a gem that calls `to_s` internally keeps calling the unrefined method. - Helpers that rely on refined methods must activate the refinement in their own file. - Methods that a library defines and later calls on your objects run in the library's scope, not yours. - A refinement never leaks into other files, which is exactly why it is safe to use in a library. ## Debugging checklist - Find the file and body where the failing call is *written*, not the caller. - Check that a `using` for the right module appears above it in that scope. - If the call lives in a reopened class, add `using` to that body as well. - If behaviour differs between two refinements, check which `using` ran last.