File: C:/Ruby27-x64/share/doc/ruby/html/syntax/refinements_rdoc.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>refinements - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "../";
var index_rel_prefix = "../";
</script>
<script src="../js/navigation.js" defer></script>
<script src="../js/search.js" defer></script>
<script src="../js/search_index.js" defer></script>
<script src="../js/searcher.js" defer></script>
<script src="../js/darkfish.js" defer></script>
<link href="../css/fonts.css" rel="stylesheet">
<link href="../css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="file">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="../index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="../table_of_contents.html#pages">Pages</a>
<a href="../table_of_contents.html#classes">Classes</a>
<a href="../table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div class="nav-section">
<h3>Table of Contents</h3>
<ul class="link-list" role="directory">
<li><a href="#label-Refinements">Refinements</a>
<li><a href="#label-Scope">Scope</a>
<li><a href="#label-Method+Lookup">Method Lookup</a>
<li><a href="#label-super"><code>super</code></a>
<li><a href="#label-Methods+Introspection">Methods Introspection</a>
<li><a href="#label-Refinement+inheritance+by+Module-23include">Refinement inheritance by Module#include</a>
<li><a href="#label-Further+Reading">Further Reading</a>
</ul>
</div>
<div id="project-metadata">
<div id="fileindex-section" class="nav-section">
<h3>Pages</h3>
<ul class="link-list">
<li><a href="../CONTRIBUTING_md.html">CONTRIBUTING</a>
<li><a href="../COPYING.html">COPYING</a>
<li><a href="../COPYING_ja.html">COPYING.ja</a>
<li><a href="../LEGAL.html">LEGAL</a>
<li><a href="../NEWS.html">NEWS</a>
<li><a href="../NEWS-1_8_7.html">NEWS-1.8.7</a>
<li><a href="../NEWS-1_9_1.html">NEWS-1.9.1</a>
<li><a href="../NEWS-1_9_2.html">NEWS-1.9.2</a>
<li><a href="../NEWS-1_9_3.html">NEWS-1.9.3</a>
<li><a href="../NEWS-2_0_0.html">NEWS-2.0.0</a>
<li><a href="../NEWS-2_1_0.html">NEWS-2.1.0</a>
<li><a href="../NEWS-2_2_0.html">NEWS-2.2.0</a>
<li><a href="../NEWS-2_3_0.html">NEWS-2.3.0</a>
<li><a href="../NEWS-2_4_0.html">NEWS-2.4.0</a>
<li><a href="../NEWS-2_5_0.html">NEWS-2.5.0</a>
<li><a href="../NEWS-2_6_0.html">NEWS-2.6.0</a>
<li><a href="../README_ja_md.html">README.ja</a>
<li><a href="../README_md.html">README</a>
<li><a href="../bug_triaging_rdoc.html">bug_triaging</a>
<li><a href="../contributing_rdoc.html">contributing</a>
<li><a href="../contributors_rdoc.html">contributors</a>
<li><a href="../dtrace_probes_rdoc.html">dtrace_probes</a>
<li><a href="../extension_ja_rdoc.html">extension.ja</a>
<li><a href="../extension_rdoc.html">extension</a>
<li><a href="../globals_rdoc.html">globals</a>
<li><a href="../keywords_rdoc.html">keywords</a>
<li><a href="../lib/racc/pre-setup.html">pre-setup</a>
<li><a href="../lib/racc/rdoc/grammar_en_rdoc.html">grammar.en</a>
<li><a href="../maintainers_rdoc.html">maintainers</a>
<li><a href="../marshal_rdoc.html">marshal</a>
<li><a href="../regexp_rdoc.html">regexp</a>
<li><a href="../security_rdoc.html">security</a>
<li><a href="../signals_rdoc.html">signals</a>
<li><a href="../standard_library_rdoc.html">standard_library</a>
<li><a href="../syntax_rdoc.html">syntax</a>
<li><a href="../syntax/assignment_rdoc.html">assignment</a>
<li><a href="../syntax/calling_methods_rdoc.html">calling_methods</a>
<li><a href="../syntax/comments_rdoc.html">comments</a>
<li><a href="../syntax/control_expressions_rdoc.html">control_expressions</a>
<li><a href="../syntax/exceptions_rdoc.html">exceptions</a>
<li><a href="../syntax/literals_rdoc.html">literals</a>
<li><a href="../syntax/methods_rdoc.html">methods</a>
<li><a href="../syntax/miscellaneous_rdoc.html">miscellaneous</a>
<li><a href="../syntax/modules_and_classes_rdoc.html">modules_and_classes</a>
<li><a href="../syntax/precedence_rdoc.html">precedence</a>
<li><a href="../syntax/refinements_rdoc.html">refinements</a>
<li><a href="../win32/README_win32.html">README.win32</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-label="Page syntax/refinements.rdoc">
<h1 id="label-Refinements">Refinements<span><a href="#label-Refinements">¶</a> <a href="#top">↑</a></span></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="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">C</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">foo</span>
<span class="ruby-identifier">puts</span> <span class="ruby-string">"C#foo"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">module</span> <span class="ruby-constant">M</span>
<span class="ruby-identifier">refine</span> <span class="ruby-constant">C</span> <span class="ruby-keyword">do</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">foo</span>
<span class="ruby-identifier">puts</span> <span class="ruby-string">"C#foo in M"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
</pre>
<p>First, a class <code>C</code> is defined. Next a refinement for <code>C</code> is created using <a href="../Module.html#method-i-refine"><code>Module#refine</code></a>.</p>
<p><a href="../Module.html#method-i-refine"><code>Module#refine</code></a> 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 <a href="../Module.html#method-i-module_eval"><code>Module#module_eval</code></a>.</p>
<p>Activate the refinement with using:</p>
<pre class="ruby"><span class="ruby-identifier">using</span> <span class="ruby-constant">M</span>
<span class="ruby-identifier">c</span> = <span class="ruby-constant">C</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">c</span>.<span class="ruby-identifier">foo</span> <span class="ruby-comment"># prints "C#foo in M"</span>
</pre>
<h2 id="label-Scope">Scope<span><a href="#label-Scope">¶</a> <a href="#top">↑</a></span></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 <a href="../Kernel.html#method-i-eval"><code>Kernel#eval</code></a>. 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="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">C</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">module</span> <span class="ruby-constant">M</span>
<span class="ruby-identifier">refine</span> <span class="ruby-constant">C</span> <span class="ruby-keyword">do</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">foo</span>
<span class="ruby-identifier">puts</span> <span class="ruby-string">"C#foo in M"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">call_foo</span>(<span class="ruby-identifier">x</span>)
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">foo</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">using</span> <span class="ruby-constant">M</span>
<span class="ruby-identifier">x</span> = <span class="ruby-constant">C</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">foo</span> <span class="ruby-comment"># prints "C#foo in M"</span>
<span class="ruby-identifier">call_foo</span>(<span class="ruby-identifier">x</span>) <span class="ruby-comment">#=> raises NoMethodError</span>
</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="ruby"><span class="ruby-keyword">class</span> <span class="ruby-constant">C</span>
<span class="ruby-keyword">end</span>
</pre>
<p>m.rb:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">"c"</span>
<span class="ruby-keyword">module</span> <span class="ruby-constant">M</span>
<span class="ruby-identifier">refine</span> <span class="ruby-constant">C</span> <span class="ruby-keyword">do</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">foo</span>
<span class="ruby-identifier">puts</span> <span class="ruby-string">"C#foo in M"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
</pre>
<p>m_user.rb:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">"m"</span>
<span class="ruby-identifier">using</span> <span class="ruby-constant">M</span>
<span class="ruby-keyword">class</span> <span class="ruby-constant">MUser</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">call_foo</span>(<span class="ruby-identifier">x</span>)
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">foo</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
</pre>
<p>main.rb:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">"m_user"</span>
<span class="ruby-identifier">x</span> = <span class="ruby-constant">C</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">m_user</span> = <span class="ruby-constant">MUser</span>.<span class="ruby-identifier">new</span>
<span class="ruby-identifier">m_user</span>.<span class="ruby-identifier">call_foo</span>(<span class="ruby-identifier">x</span>) <span class="ruby-comment"># prints "C#foo in M"</span>
<span class="ruby-identifier">x</span>.<span class="ruby-identifier">foo</span> <span class="ruby-comment">#=> raises NoMethodError</span>
</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="ruby"><span class="ruby-comment"># not activated here</span>
<span class="ruby-identifier">using</span> <span class="ruby-constant">M</span>
<span class="ruby-comment"># activated here</span>
<span class="ruby-keyword">class</span> <span class="ruby-constant">Foo</span>
<span class="ruby-comment"># activated here</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">foo</span>
<span class="ruby-comment"># activated here</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># activated here</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># activated here</span>
</pre>
<p>In a class:</p>
<pre class="ruby"><span class="ruby-comment"># not activated here</span>
<span class="ruby-keyword">class</span> <span class="ruby-constant">Foo</span>
<span class="ruby-comment"># not activated here</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">foo</span>
<span class="ruby-comment"># not activated here</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">using</span> <span class="ruby-constant">M</span>
<span class="ruby-comment"># activated here</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">bar</span>
<span class="ruby-comment"># activated here</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># activated here</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># not activated here</span>
</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="ruby"><span class="ruby-comment"># not activated here</span>
<span class="ruby-identifier">eval</span> <span class="ruby-identifier"><<EOF</span>
<span class="ruby-value"> # not activated here
using M
# activated here
</span><span class="ruby-identifier">EOF</span>
<span class="ruby-comment"># not activated here</span>
</pre>
<p>When not evaluated:</p>
<pre class="ruby"><span class="ruby-comment"># not activated here</span>
<span class="ruby-keyword">if</span> <span class="ruby-keyword">false</span>
<span class="ruby-identifier">using</span> <span class="ruby-constant">M</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># not activated here</span>
</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="ruby"><span class="ruby-keyword">module</span> <span class="ruby-constant">ToJSON</span>
<span class="ruby-identifier">refine</span> <span class="ruby-constant">Integer</span> <span class="ruby-keyword">do</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">to_json</span>
<span class="ruby-identifier">to_s</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">refine</span> <span class="ruby-constant">Array</span> <span class="ruby-keyword">do</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">to_json</span>
<span class="ruby-string">"["</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">map</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">i</span><span class="ruby-operator">|</span> <span class="ruby-identifier">i</span>.<span class="ruby-identifier">to_json</span> }.<span class="ruby-identifier">join</span>(<span class="ruby-string">","</span>) <span class="ruby-operator">+</span> <span class="ruby-string">"]"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">refine</span> <span class="ruby-constant">Hash</span> <span class="ruby-keyword">do</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">to_json</span>
<span class="ruby-string">"{"</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">map</span> { <span class="ruby-operator">|</span><span class="ruby-identifier">k</span>, <span class="ruby-identifier">v</span><span class="ruby-operator">|</span> <span class="ruby-identifier">k</span>.<span class="ruby-identifier">to_s</span>.<span class="ruby-identifier">dump</span> <span class="ruby-operator">+</span> <span class="ruby-string">":"</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">v</span>.<span class="ruby-identifier">to_json</span> }.<span class="ruby-identifier">join</span>(<span class="ruby-string">","</span>) <span class="ruby-operator">+</span> <span class="ruby-string">"}"</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">using</span> <span class="ruby-constant">ToJSON</span>
<span class="ruby-identifier">p</span> [{<span class="ruby-value">1</span><span class="ruby-operator">=></span><span class="ruby-value">2</span>}, {<span class="ruby-value">3</span><span class="ruby-operator">=></span><span class="ruby-value">4</span>}].<span class="ruby-identifier">to_json</span> <span class="ruby-comment"># prints "[{\"1\":2},{\"3\":4}]"</span>
</pre>
<h2 id="label-Method+Lookup"><a href="../Method.html"><code>Method</code></a> Lookup<span><a href="#label-Method+Lookup">¶</a> <a href="#top">↑</a></span></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 <a href="../Numeric.html"><code>Numeric</code></a> <code>1 / 2</code> invokes the original Integer#/ because <a href="../Integer.html"><code>Integer</code></a> is a subclass of <a href="../Numeric.html"><code>Numeric</code></a> and is searched before the refinements for the superclass <a href="../Numeric.html"><code>Numeric</code></a>. 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 <a href="../Numeric.html"><code>Numeric</code></a> in a refinement, <code>1.foo</code> invokes that method since <code>foo</code> does not exist on <a href="../Integer.html"><code>Integer</code></a>.</p>
<h2 id="label-super"><code>super</code><span><a href="#label-super">¶</a> <a href="#top">↑</a></span></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 <a href="../Method.html"><code>Method</code></a> Lookup section above.</p>
</li><li>
<p>If the current class has a direct superclass, the method proceeds as in the <a href="../Method.html"><code>Method</code></a> 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<span><a href="#label-Methods+Introspection">¶</a> <a href="#top">↑</a></span></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 <a href="../Module.html#method-i-include"><code>Module#include</code></a><span><a href="#label-Refinement+inheritance+by+Module-23include">¶</a> <a href="#top">↑</a></span></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>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.</pre>
<p>Refinements in descendants have higher precedence than those of ancestors.</p>
<h2 id="label-Further+Reading">Further Reading<span><a href="#label-Further+Reading">¶</a> <a href="#top">↑</a></span></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>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>