| blob | 17d5e67c21a3779d00c03a308c567122cbece563 |
1 = Refinements
3 Due to Ruby's open classes you can redefine or add functionality to existing
4 classes. This is called a "monkey patch". Unfortunately the scope of such
5 changes is global. All users of the monkey-patched class see the same
6 changes. This can cause unintended side-effects or breakage of programs.
8 Refinements are designed to reduce the impact of monkey patching on other
9 users of the monkey-patched class. Refinements provide a way to extend a
10 class locally. Refinements can modify both classes and modules.
12 Here is a basic refinement:
14 class C
15 def foo
16 puts "C#foo"
17 end
18 end
20 module M
21 refine C do
22 def foo
23 puts "C#foo in M"
24 end
25 end
26 end
28 First, a class +C+ is defined. Next a refinement for +C+ is created using
29 Module#refine.
31 Module#refine creates an anonymous module that contains the changes or
32 refinements to the class (+C+ in the example). +self+ in the refine block is
33 this anonymous module similar to Module#module_eval.
35 Activate the refinement with #using:
37 using M
39 c = C.new
41 c.foo # prints "C#foo in M"
43 == Scope
45 You may activate refinements at top-level, and inside classes and modules.
46 You may not activate refinements in method scope. Refinements are activated
47 until the end of the current class or module definition, or until the end of
48 the current file if used at the top-level.
50 You may activate refinements in a string passed to Kernel#eval. Refinements
51 are active until the end of the eval string.
53 Refinements are lexical in scope. Refinements are only active within a scope
54 after the call to +using+. Any code before the +using+ statement will not have the
55 refinement activated.
57 When control is transferred outside the scope, the refinement is deactivated.
58 This means that if you require or load a file or call a method that is defined
59 outside the current scope the refinement will be deactivated:
61 class C
62 end
64 module M
65 refine C do
66 def foo
67 puts "C#foo in M"
68 end
69 end
70 end
72 def call_foo(x)
73 x.foo
74 end
76 using M
78 x = C.new
79 x.foo # prints "C#foo in M"
80 call_foo(x) #=> raises NoMethodError
82 If a method is defined in a scope where a refinement is active, the refinement
83 will be active when the method is called. This example spans multiple files:
85 c.rb:
87 class C
88 end
90 m.rb:
92 require "c"
94 module M
95 refine C do
96 def foo
97 puts "C#foo in M"
98 end
99 end
100 end
102 m_user.rb:
104 require "m"
106 using M
108 class MUser
109 def call_foo(x)
110 x.foo
111 end
112 end
114 main.rb:
116 require "m_user"
118 x = C.new
119 m_user = MUser.new
120 m_user.call_foo(x) # prints "C#foo in M"
121 x.foo #=> raises NoMethodError
123 Since the refinement +M+ is active in <code>m_user.rb</code> where
124 <code>MUser#call_foo</code> is defined it is also active when
125 <code>main.rb</code> calls +call_foo+.
127 Since #using is a method, refinements are only active when it is called. Here
128 are examples of where a refinement +M+ is and is not active.
130 In a file:
132 # not activated here
133 using M
134 # activated here
135 class Foo
136 # activated here
137 def foo
138 # activated here
139 end
140 # activated here
141 end
142 # activated here
144 In a class:
146 # not activated here
147 class Foo
148 # not activated here
149 def foo
150 # not activated here
151 end
152 using M
153 # activated here
154 def bar
155 # activated here
156 end
157 # activated here
158 end
159 # not activated here
161 Note that the refinements in +M+ are *not* activated automatically if the class
162 +Foo+ is reopened later.
164 In eval:
166 # not activated here
167 eval <<EOF
168 # not activated here
169 using M
170 # activated here
171 EOF
172 # not activated here
174 When not evaluated:
176 # not activated here
177 if false
178 using M
179 end
180 # not activated here
182 When defining multiple refinements in the same module inside multiple +refine+ blocks,
183 all refinements from the same module are active when a refined method
184 (any of the +to_json+ methods from the example below) is called:
186 module ToJSON
187 refine Integer do
188 def to_json
189 to_s
190 end
191 end
193 refine Array do
194 def to_json
195 "[" + map { |i| i.to_json }.join(",") + "]"
196 end
197 end
199 refine Hash do
200 def to_json
201 "{" + map { |k, v| k.to_s.dump + ":" + v.to_json }.join(",") + "}"
202 end
203 end
204 end
206 using ToJSON
208 p [{1=>2}, {3=>4}].to_json # prints "[{\"1\":2},{\"3\":4}]"
211 == Method Lookup
213 When looking up a method for an instance of class +C+ Ruby checks:
215 * If refinements are active for +C+, in the reverse order they were activated:
216 * The prepended modules from the refinement for +C+
217 * The refinement for +C+
218 * The included modules from the refinement for +C+
219 * The prepended modules of +C+
220 * +C+
221 * The included modules of +C+
223 If no method was found at any point this repeats with the superclass of +C+.
225 Note that methods in a subclass have priority over refinements in a
226 superclass. For example, if the method <code>/</code> is defined in a
227 refinement for Numeric <code>1 / 2</code> invokes the original Integer#/
228 because Integer is a subclass of Numeric and is searched before the refinements
229 for the superclass Numeric. Since the method <code>/</code> is also present
230 in child +Integer+, the method lookup does not move up to the superclass.
232 However, if a method +foo+ is defined on Numeric in a refinement, <code>1.foo</code>
233 invokes that method since +foo+ does not exist on Integer.
235 == +super+
237 When +super+ is invoked method lookup checks:
239 * The included modules of the current class. Note that the current class may
240 be a refinement.
241 * If the current class is a refinement, the method lookup proceeds as in the
242 Method Lookup section above.
243 * If the current class has a direct superclass, the method proceeds as in the
244 Method Lookup section above using the superclass.
246 Note that +super+ in a method of a refinement invokes the method in the
247 refined class even if there is another refinement which has been activated in
248 the same context. This is only true for +super+ in a method of a refinement, it
249 does not apply to +super+ in a method in a module that is included in a refinement.
251 == Methods Introspection
253 When using introspection methods such as Kernel#method or Kernel#methods refinements are not honored.
255 This behavior may be changed in the future.
257 == Refinement inheritance by Module#include
259 When a module X is included into a module Y, Y inherits refinements from X.
261 For example, C inherits refinements from A and B in the following code:
263 module A
264 refine X do ... end
265 refine Y do ... end
266 end
267 module B
268 refine Z do ... end
269 end
270 module C
271 include A
272 include B
273 end
275 using C
276 # Refinements in A and B are activated here.
278 Refinements in descendants have higher precedence than those of ancestors.
280 == Further Reading
282 See https://github.com/ruby/ruby/wiki/Refinements-Spec for the
283 current specification for implementing refinements. The specification also
284 contains more details.