[ruby-core:125828] [Ruby Feature#22097] Add Proc#with_refinements

23 Jun 2026

      Issue #22097 has been updated by shugo (Shugo Maeda).

Thank you for your feedback, and I'm glad to hear your concerns are mostly addressed.

Eregon (Benoit Daloze) wrote in #note-16:
...
I'm not sure it's really needed though and might be surprising, is it needed?
`with_refinements` is semantically equivalent to having `using M` at the beginning of the proc body. With `using`, refinements are active through `class`/`module`/`def` — this is the existing, documented behavior (see `doc/syntax/refinements.rdoc`). Keeping `with_refinements` consistent with `using` is a deliberate design choice: users who understand `using` should be able to predict `with_refinements` behavior without learning new scoping rules.

I also don't think this is action-at-a-distance. The action-at-a-distance I described in #note-9 was about mutating shared state: calling `with_refinements(A)` would cause a *separate* call to `original.call` to raise, depending on call order. That is a non-local, unpredictable side effect. In contrast, refinements applying inside `def` within the proc body are deterministic and local — the `def` is lexically inside the scope where refinements are active, so its behavior is fully determined by the lexical structure, not by runtime call order.
...
`module`/`class` would still be boundaries, right?
No, `module`/`class` are not boundaries for refinements either. With `using`, refinements apply through `class`/`module`/`def`:

```ruby
using StringExt

class Foo
  def bar
    "hello".shout  # works
  end
end
```

I have also fixed the JRuby implementation to apply refinements inside `class`/`module` bodies in: https://github.com/jruby/jruby/pull/9486/commits/f3b31e935241a44faa49c4a345f...
...
`define_method` would also not use those refinements.
Calling `define_method` inside a proc body with refinements is the same as calling it under `using` — the block passed to `define_method` sees the refinements from the surrounding lexical scope:

```ruby
using StringExt

define_method(:foo) do
  "hello".shout  # works
end
```

The method defined this way retains the refinements after the proc returns, because they are captured in the block's iseq at definition time — exactly as with `using`.

Note that this is different from passing a `with_refinements`-applied Proc directly to `define_method`, which raises `ArgumentError` as documented in Limitations. The distinction is: calling `define_method` *inside* a refined proc body is normal `using` behavior; passing a refined Proc *as* the method body is not supported.
...
I think we should limit it to nested blocks
Restricting `with_refinements` to blocks only, excluding `def`/`class`/`module`, would make it inconsistent with `using` without a clear safety benefit — the refined behavior is still deterministic and lexically scoped in all cases.

It would also hurt usability. For example, as mentioned in #note-9, a convenience helper can be built on top of `with_refinements`:

```ruby
using_refinements(StringExt) do
  class Foo
    def bar
      "hello".shout
    end
  end
end
```

If refinements were limited to nested blocks, this natural pattern would not work.

I don't think we should introduce restrictions that `using` doesn't have.

----------------------------------------
Feature #22097: Add Proc#with_refinements
https://bugs.ruby-lang.org/issues/22097#change-117743

* Author: shugo (Shugo Maeda)
* Status: Open
----------------------------------------
## Abstract

I propose `Proc#with_refinements(mod, ...)` to support block-level refinements.

```ruby
module StringExt
  refine String do
    def shout = upcase + "!"
  end
end

original = ->(s) { s.shout }
refined = original.with_refinements(StringExt)
p refined.call("hello")  # "HELLO!"
p original.call("hello") # NoMethodError
```

When no argument is given, `ArgumentError` is raised.
When a non-`Module` argument is given, `TypeError` is raised.

## Background and Motivation

I previously proposed `Proc#using` in [Feature #16461], but it introduced semantic complexities because it mutated existing blocks.

Instead of mutating the existing block, `Proc#with_refinements` returns a new `Proc` object with its own isolated call sites.
This approach makes its semantics much simpler than `Proc#using`, and it avoids thread-safety issues and plays nicely with inline caches.

## Use Cases

`Proc#with_refinements` is useful to implement internal DSLs applying refinements implicitly.

* [activerecord-refinements](https://github.com/shugo/activerecord-refinements/blob/8869717fcba96fae3965d...)
  * DSL for SQL
  * Example: `User.where { :name == 'matz' }`
* [radd_djur](https://github.com/shugo/radd_djur/blob/proc-with_refinements/lib/radd_djur/...)
  * DSL for monadic parser combinators

## Limitations

* Similar to `Proc#binding`, `Proc#with_refinements` raises `ArgumentError` if the
  receiver is not created from a Ruby block.

```ruby
:to_s.to_proc.with_refinements(StringExt) #=> ArgumentError
```

* Chained application of `Proc#with_refinements` is not allowed. `ArgumentError` is
  raised if the receiver is a `Proc` returned by `Proc#with_refinements`.

```ruby
refined = prc.with_refinements(StringExt)
refined.with_refinements(IntegerExt) #=> ArgumentError
```

* `define_method` (and `define_singleton_method`) rejects a `Proc` with refinements.
  `ArgumentError` is raised if the return value of `Proc#with_refinements` is given to
  `define_method`.

```ruby
refined = prc.with_refinements(StringExt)
define_method(:foo, &refined) #=> ArgumentError
```

## Implementation

I've opened a pull request: https://github.com/ruby/ruby/pull/17248

A PoC for JRuby is also available at: https://github.com/jruby/jruby/pull/9486

### Data structure changes

* Added a bit field `has_refinements` to `rb_proc_t`.
* Added a hidden instance variable to `Proc` to store a `cref` with the applied refinements.
* Added a single-entry cache `refinement_memo` to `rb_iseq_constant_body`.

### Deep copy of iseq and caching

`Proc#with_refinements` performs a deep copy of the receiver's `iseq` to isolate its call sites from the original `Proc`.
While a deep copy can be an expensive operation, the single-entry cache in `rb_iseq_constant_body` mitigates this overhead effectively for most practical use cases where the same refinements are applied repeatedly.

### Overhead for code not using Proc#with_refinements

* Memory footprint: Neither internal structure grows in size. `has_refinements` is a 1-bit field added to rb_proc_t's existing bit field, and `refinement_memo` shares a union with `mandatory_only_iseq` in rb_iseq_constant_body.
* Execution speed: The common `Proc#call` path is kept frameless and only adds a single `has_refinements` bit check.
* GC: The mark/free/memsize functions add a single branch per `iseq` to select the union member.

Benchmark results: https://gist.github.com/shugo/ddfe92f28ea31e6527a2f270e6daee7c

Here's an excerpt from the results, where `compare-ruby` is master and `built-ruby` is the branch for this feature (focusing on Proc/Block operations):

|                                     |compare-ruby|built-ruby|
|:------------------------------------|-----------:|---------:|
|vm_proc                              |     47.215M|   46.149M|
|                                     |       1.02x|         -|
|vm_yield                             |       1.649|     1.754|
|                                     |           -|     1.06x|

-- 
https://bugs.ruby-lang.org/