-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathfile.refinements.html
327 lines (247 loc) · 19.2 KB
/
file.refinements.html
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
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
<!DOCTYPE html>
<html>
<head>
<meta charset='UTF-8'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, user-scalable=no'>
<meta name='apple-touch-fullscreen' content='yes'>
<meta name='apple-mobile-web-app-capable' content='yes'>
<meta name='apple-mobile-web-app-status-bar-style' content='rgba(228,228,228,1.0)'>
<title>File: Refinements — Ruby-2.6.10</title>
<link rel='stylesheet' type='text/css' href='../css/y_fonts.css' />
<link rel='stylesheet' type='text/css' href='../css/highlight.github.css' />
<link rel='stylesheet' type='text/css' href='../css/y_style.css' />
<link rel='stylesheet' type='text/css' href='../css/y_list.css' />
<link rel='stylesheet' type='text/css' href='../css/y_color.css' />
<script type='text/javascript'>
var pathId = "refinements",
relpath = '';
var t2Info = {
CSEP: '.',
ISEP: '#',
NSEP: '::'
};
</script>
<script type='text/javascript' charset='utf-8' src='../js/highlight.pack.js'></script>
<script type='text/javascript' charset='utf-8' src='../js/y_app.js'></script>
</head>
<body>
<svg id='y_wait' class viewBox='0 0 90 90'></svg>
<div id='settings' class='hidden'></div>
<div id='y_list' class='d h'>
<header id='list_header'></header>
<nav id= 'list_nav' class='y_nav l_nav'>
<ul id='list_items'></ul>
</nav>
</div>
<div id='y_toc' class='f h'>
<header id='toc_header'></header>
<nav id= 'toc_nav' class='y_nav t_nav'>
<ol id='toc_items'></ol>
</nav>
</div>
<div id='y_main' tabindex='-1'>
<header id='y_header'>
<div id='y_menu'>
<a id='home_no_xhr' href='/'>Home</a> »
<a href='.'>Ruby-2.6.10</a> »
<a href='_index.html'>Index</a> »
<span class='title'><a id='t2_doc_top' href='#'>File: Refinements ▲</a></span>
</div>
<a id='list_href' href="file_list.html"></a>
<div id='y_measure_em' class='y_measure'></div>
<div id='y_measure_vh' class='y_measure'></div>
<span id='y_measure_50pre' class='y_measure'><code>123456789_123456789_123456789_123456789_123456789_</code></span>
</header>
<div id='content' class='file'>
<h1 id="label-Refinements">Refinements</h1>
<p>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.</p>
<p>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. Refinements can modify both classes and modules.</p>
<p>Here is a basic refinement:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>C</span>
<span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span>
<span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>C#foo</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='kw'>module</span> <span class='const'>M</span>
<span class='id identifier rubyid_refine'>refine</span> <span class='const'>C</span> <span class='kw'>do</span>
<span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span>
<span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>C#foo in M</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='kw'>end</span></code></pre>
<p>First, a class <code>C</code> is defined. Next a refinement for <code>C</code> is created using Module#refine.</p>
<p>Module#refine creates an anonymous module that contains the changes or refinements to the class (<code>C</code> in the example). <code>self</code> in the refine block is this anonymous module similar to Module#module_eval.</p>
<p>Activate the refinement with #using:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_using'>using</span> <span class='const'>M</span>
<span class='id identifier rubyid_c'>c</span> <span class='op'>=</span> <span class='const'>C</span>.<span class='id identifier rubyid_new'>new</span>
<span class='id identifier rubyid_c'>c</span>.<span class='id identifier rubyid_foo'>foo</span> <span class='comment'># prints "C#foo in M"</span></code></pre>
<h2 id="label-Scope">Scope</h2>
<p>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.</p>
<p>You may activate refinements in a string passed to Kernel#eval. Refinements are active until the end of the eval string.</p>
<p>Refinements are lexical in scope. Refinements are only active within a scope after the call to <code>using</code>. Any code before the <code>using</code> statement will not have the refinement activated.</p>
<p>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:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>C</span>
<span class='kw'>end</span>
<span class='kw'>module</span> <span class='const'>M</span>
<span class='id identifier rubyid_refine'>refine</span> <span class='const'>C</span> <span class='kw'>do</span>
<span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span>
<span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>C#foo in M</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_call_foo'>call_foo</span>(<span class='id identifier rubyid_x'>x</span>)
<span class='id identifier rubyid_x'>x</span>.<span class='id identifier rubyid_foo'>foo</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_using'>using</span> <span class='const'>M</span>
<span class='id identifier rubyid_x'>x</span> <span class='op'>=</span> <span class='const'>C</span>.<span class='id identifier rubyid_new'>new</span>
<span class='id identifier rubyid_x'>x</span>.<span class='id identifier rubyid_foo'>foo</span> <span class='comment'># prints "C#foo in M"
</span><span class='id identifier rubyid_call_foo'>call_foo</span>(<span class='id identifier rubyid_x'>x</span>) <span class='comment'>#=> raises NoMethodError</span></code></pre>
<p>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:</p>
<p>c.rb:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>C</span>
<span class='kw'>end</span></code></pre>
<p>m.rb:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>c</span><span class='tstring_end'>"</span></span>
<span class='kw'>module</span> <span class='const'>M</span>
<span class='id identifier rubyid_refine'>refine</span> <span class='const'>C</span> <span class='kw'>do</span>
<span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span>
<span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>C#foo in M</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='kw'>end</span></code></pre>
<p>m_user.rb:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>m</span><span class='tstring_end'>"</span></span>
<span class='id identifier rubyid_using'>using</span> <span class='const'>M</span>
<span class='kw'>class</span> <span class='const'>MUser</span>
<span class='kw'>def</span> <span class='id identifier rubyid_call_foo'>call_foo</span>(<span class='id identifier rubyid_x'>x</span>)
<span class='id identifier rubyid_x'>x</span>.<span class='id identifier rubyid_foo'>foo</span>
<span class='kw'>end</span>
<span class='kw'>end</span></code></pre>
<p>main.rb:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_require'>require</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>m_user</span><span class='tstring_end'>"</span></span>
<span class='id identifier rubyid_x'>x</span> <span class='op'>=</span> <span class='const'>C</span>.<span class='id identifier rubyid_new'>new</span>
<span class='id identifier rubyid_m_user'>m_user</span> <span class='op'>=</span> <span class='const'>MUser</span>.<span class='id identifier rubyid_new'>new</span>
<span class='id identifier rubyid_m_user'>m_user</span>.<span class='id identifier rubyid_call_foo'>call_foo</span>(<span class='id identifier rubyid_x'>x</span>) <span class='comment'># prints "C#foo in M"
</span><span class='id identifier rubyid_x'>x</span>.<span class='id identifier rubyid_foo'>foo</span> <span class='comment'>#=> raises NoMethodError</span></code></pre>
<p>Since the refinement <code>M</code> 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 <code>call_foo</code>.</p>
<p>Since #using is a method, refinements are only active when it is called. Here are examples of where a refinement <code>M</code> is and is not active.</p>
<p>In a file:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># not activated here
</span><span class='id identifier rubyid_using'>using</span> <span class='const'>M</span>
<span class='comment'># activated here
</span><span class='kw'>class</span> <span class='const'>Foo</span>
<span class='comment'># activated here
</span> <span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span>
<span class='comment'># activated here
</span> <span class='kw'>end</span>
<span class='comment'># activated here
</span><span class='kw'>end</span>
<span class='comment'># activated here</span></code></pre>
<p>In a class:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># not activated here
</span><span class='kw'>class</span> <span class='const'>Foo</span>
<span class='comment'># not activated here
</span> <span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span>
<span class='comment'># not activated here
</span> <span class='kw'>end</span>
<span class='id identifier rubyid_using'>using</span> <span class='const'>M</span>
<span class='comment'># activated here
</span> <span class='kw'>def</span> <span class='id identifier rubyid_bar'>bar</span>
<span class='comment'># activated here
</span> <span class='kw'>end</span>
<span class='comment'># activated here
</span><span class='kw'>end</span>
<span class='comment'># not activated here</span></code></pre>
<p>Note that the refinements in <code>M</code> are <strong>not</strong> activated automatically if the class <code>Foo</code> is reopened later.</p>
<p>In eval:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># not activated here
</span><span class='id identifier rubyid_eval'>eval</span> <span class='heredoc_beg'><<EOF</span>
<span class='tstring_content'> # not activated here
using M
# activated here
</span><span class='heredoc_end'>EOF
</span><span class='comment'># not activated here</span></code></pre>
<p>When not evaluated:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># not activated here
</span><span class='kw'>if</span> <span class='kw'>false</span>
<span class='id identifier rubyid_using'>using</span> <span class='const'>M</span>
<span class='kw'>end</span>
<span class='comment'># not activated here</span></code></pre>
<p>When defining multiple refinements in the same module inside multiple <code>refine</code> blocks, all refinements from the same module are active when a refined method (any of the <code>to_json</code> methods from the example below) is called:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>module</span> <span class='const'>ToJSON</span>
<span class='id identifier rubyid_refine'>refine</span> <span class='const'>Integer</span> <span class='kw'>do</span>
<span class='kw'>def</span> <span class='id identifier rubyid_to_json'>to_json</span>
<span class='id identifier rubyid_to_s'>to_s</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_refine'>refine</span> <span class='const'>Array</span> <span class='kw'>do</span>
<span class='kw'>def</span> <span class='id identifier rubyid_to_json'>to_json</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>[</span><span class='tstring_end'>"</span></span> <span class='op'>+</span> <span class='id identifier rubyid_map'>map</span> { <span class='op'>|</span><span class='id identifier rubyid_i'>i</span><span class='op'>|</span> <span class='id identifier rubyid_i'>i</span>.<span class='id identifier rubyid_to_json'>to_json</span> }.<span class='id identifier rubyid_join'>join</span>(<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>,</span><span class='tstring_end'>"</span></span>) <span class='op'>+</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>]</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_refine'>refine</span> <span class='const'>Hash</span> <span class='kw'>do</span>
<span class='kw'>def</span> <span class='id identifier rubyid_to_json'>to_json</span>
<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>{</span><span class='tstring_end'>"</span></span> <span class='op'>+</span> <span class='id identifier rubyid_map'>map</span> { <span class='op'>|</span><span class='id identifier rubyid_k'>k</span><span class='comma'>,</span> <span class='id identifier rubyid_v'>v</span><span class='op'>|</span> <span class='id identifier rubyid_k'>k</span>.<span class='id identifier rubyid_to_s'>to_s</span>.<span class='id identifier rubyid_dump'>dump</span> <span class='op'>+</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>:</span><span class='tstring_end'>"</span></span> <span class='op'>+</span> <span class='id identifier rubyid_v'>v</span>.<span class='id identifier rubyid_to_json'>to_json</span> }.<span class='id identifier rubyid_join'>join</span>(<span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>,</span><span class='tstring_end'>"</span></span>) <span class='op'>+</span> <span class='tstring'><span class='tstring_beg'>"</span><span class='tstring_content'>}</span><span class='tstring_end'>"</span></span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='kw'>end</span>
<span class='id identifier rubyid_using'>using</span> <span class='const'>ToJSON</span>
<span class='id identifier rubyid_p'>p</span> [{<span class='int'>1</span><span class='op'>=></span><span class='int'>2</span>}<span class='comma'>,</span> {<span class='int'>3</span><span class='op'>=></span><span class='int'>4</span>}].<span class='id identifier rubyid_to_json'>to_json</span> <span class='comment'># prints "[{\"1\":2},{\"3\":4}]"</span></code></pre>
<h2 id="label-Method+Lookup">Method Lookup</h2>
<p>When looking up a method for an instance of class <code>C</code> Ruby checks:</p>
<ul><li>
<p>If refinements are active for <code>C</code>, in the reverse order they were activated:</p>
<ul><li>
<p>The prepended modules from the refinement for <code>C</code></p>
</li><li>
<p>The refinement for <code>C</code></p>
</li><li>
<p>The included modules from the refinement for <code>C</code></p>
</li></ul>
</li><li>
<p>The prepended modules of <code>C</code></p>
</li><li>
<p><code>C</code></p>
</li><li>
<p>The included modules of <code>C</code></p>
</li></ul>
<p>If no method was found at any point this repeats with the superclass of <code>C</code>.</p>
<p>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 <code>Integer</code>, the method lookup does not move up to the superclass.</p>
<p>However, if a method <code>foo</code> is defined on Numeric in a refinement, <code>1.foo</code> invokes that method since <code>foo</code> does not exist on Integer.</p>
<h2 id="label-super"><code>super</code></h2>
<p>When <code>super</code> is invoked method lookup checks:</p>
<ul><li>
<p>The included modules of the current class. Note that the current class may be a refinement.</p>
</li><li>
<p>If the current class is a refinement, the method lookup proceeds as in the Method Lookup section above.</p>
</li><li>
<p>If the current class has a direct superclass, the method proceeds as in the Method Lookup section above using the superclass.</p>
</li></ul>
<p>Note that <code>super</code> 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.</p>
<h2 id="label-Methods+Introspection">Methods Introspection</h2>
<p>When using introspection methods such as Kernel#method or Kernel#methods refinements are not honored.</p>
<p>This behavior may be changed in the future.</p>
<h2 id="label-Refinement+inheritance+by+Module-23include">Refinement inheritance by Module#include</h2>
<p>When a module X is included into a module Y, Y inherits refinements from X.</p>
<p>For example, C inherits refinements from A and B in the following code:</p>
<pre class="code ruby"><code class="ruby">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.</code></pre>
<p>Refinements in descendants have higher precedence than those of ancestors.</p>
<h2 id="label-Further+Reading">Further Reading</h2>
<p>See <a href="https://bugs.ruby-lang.org/projects/ruby-trunk/wiki/RefinementsSpec">bugs.ruby-lang.org/projects/ruby-trunk/wiki/RefinementsSpec</a> for the current specification for implementing refinements. The specification also contains more details.</p>
<div id='footer'></div>
</div> <!-- content -->
</div> <!-- y_main -->
</body>
</html>