summaryrefslogtreecommitdiff
path: root/doc/syntax/refinements.rdoc
blob: 5519c47c3733f59dabc4ad5efd0620d576de6687 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
= Refinements

Due to Ruby's open classes you can redefine or add functionality to existing
classes.  This is called a "monkey patch".  Unfortunately the scope of such
changes is global.  All users of the monkey-patched class see the same
changes.  This can cause unintended side-effects or breakage of programs.

Refinements are designed to reduce the impact of monkey patching on other
users of the monkey-patched class.  Refinements provide a way to extend a
class locally.

Here is a basic refinement:

  class C
    def foo
      puts "C#foo"
    end
  end

  module M
    refine C do
      def foo
        puts "C#foo in M"
      end
    end
  end

First, a class +C+ is defined.  Next a refinement for +C+ is created using
Module#refine.  Refinements only modify classes, not modules so the argument
must be a class.

Module#refine creates an anonymous module that contains the changes or
refinements to the class (+C+ in the example).  +self+ in the refine block is
this anonymous module similar to Module#module_eval.

Activate the refinement with #using:

  using M

  c = C.new

  c.foo # prints "C#foo in M"

== Scope

You may activate refinements at top-level, and inside classes and modules.
You may not activate refinements in method scope.  Refinements are activated
until the end of the current class or module definition, or until the end of
the current file if used at the top-level.

You may activate refinements in a string passed to Kernel#eval. Refinements
are active until the end of the eval string.

Refinements are lexical in scope.  Refinements are only active within a scope
after the call to +using+. Any code before the +using+ statement will not have the
refinement activated.

When control is transferred outside the scope, the refinement is deactivated.
This means that if you require or load a file or call a method that is defined
outside the current scope the refinement will be deactivated:

  class C
  end

  module M
    refine C do
      def foo
        puts "C#foo in M"
      end
    end
  end

  def call_foo(x)
    x.foo
  end

  using M

  x = C.new
  x.foo       # prints "C#foo in M"
  call_foo(x) #=> raises NoMethodError

If a method is defined in a scope where a refinement is active, the refinement
will be active when the method is called.  This example spans multiple files:

c.rb:

  class C
  end

m.rb:

  require "c"

  module M
    refine C do
      def foo
        puts "C#foo in M"
      end
    end
  end

m_user.rb:

  require "m"

  using M

  class MUser
    def call_foo(x)
      x.foo
    end
  end

main.rb:

  require "m_user"

  x = C.new
  m_user = MUser.new
  m_user.call_foo(x) # prints "C#foo in M"
  x.foo              #=> raises NoMethodError

Since the refinement +M+ is active in <code>m_user.rb</code> where
<code>MUser#call_foo</code> is defined it is also active when
<code>main.rb</code> calls +call_foo+.

Since #using is a method, refinements are only active when it is called.  Here
are examples of where a refinement +M+ is and is not active.

In a file:

  # not activated here
  using M
  # activated here
  class Foo
    # activated here
    def foo
      # activated here
    end
    # activated here
  end
  # activated here

In a class:

  # not activated here
  class Foo
    # not activated here
    def foo
      # not activated here
    end
    using M
    # activated here
    def bar
      # activated here
    end
    # activated here
  end
  # not activated here

Note that the refinements in +M+ are *not* activated automatically if the class
+Foo+ is reopened later.

In eval:

  # not activated here
  eval <<EOF
    # not activated here
    using M
    # activated here
  EOF
  # not activated here

When not evaluated:

  # not activated here
  if false
    using M
  end
  # not activated here

When defining multiple refinements in the same module inside multiple +refine+ blocks,
all refinements from the same module are active when a refined method
(any of the +to_json+ methods from the example below) is called:

  module ToJSON
    refine Integer do
      def to_json
        to_s
      end
    end

    refine Array do
      def to_json
        "[" + map { |i| i.to_json }.join(",") + "]"
      end
    end

    refine Hash do
      def to_json
        "{" + map { |k, v| k.to_s.dump + ":" + v.to_json }.join(",") + "}"
      end
    end
  end

  using ToJSON

  p [{1=>2}, {3=>4}].to_json # prints "[{\"1\":2},{\"3\":4}]"


== Method Lookup

When looking up a method for an instance of class +C+ Ruby checks:

* If refinements are active for +C+, in the reverse order they were activated:
  * The prepended modules from the refinement for +C+
  * The refinement for +C+
  * The included modules from the refinement for +C+
* The prepended modules of +C+
* +C+
* The included modules of +C+

If no method was found at any point this repeats with the superclass of +C+.

Note that methods in a subclass have priority over refinements in a
superclass.  For example, if the method <code>/</code> is defined in a
refinement for Numeric <code>1 / 2</code> invokes the original Integer#/
because Integer is a subclass of Numeric and is searched before the refinements
for the superclass Numeric. Since the method <code>/</code> is also present
in child +Integer+, the method lookup does not move up to the superclass.

However, if a method +foo+ is defined on Numeric in a refinement, <code>1.foo</code>
invokes that method since +foo+ does not exist on Integer.

== +super+

When +super+ is invoked method lookup checks:

* The included modules of the current class.  Note that the current class may
  be a refinement.
* If the current class is a refinement, the method lookup proceeds as in the
  Method Lookup section above.
* If the current class has a direct superclass, the method proceeds as in the
  Method Lookup section above using the superclass.

Note that +super+ in a method of a refinement invokes the method in the
refined class even if there is another refinement which has been activated in
the same context.

== Indirect Method Calls

When using indirect method access such as Kernel#send, Kernel#method or
Kernel#respond_to? refinements are not honored for the caller context during
method lookup.

This behavior may be changed in the future.

== Refinement inheritance by Module#include

When a module X is included into a module Y, Y inherits refinments from X.

For exmaple, C inherits refinements from A and B in the following code:

  module A
    refine X do ... end
    refine Y do ... end
  end
  module B
    refine Z do ... end
  end
  module C
    include A
    include B
  end

  using C
  # Refinements in A and B are activated here.

Refinements in descendents have higher precedence than those of ancestors.

== Further Reading

See https://bugs.ruby-lang.org/projects/ruby-trunk/wiki/RefinementsSpec for the
current specification for implementing refinements.  The specification also
contains more details.