mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
284 lines
6.8 KiB
Text
284 lines
6.8 KiB
Text
= 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. Refinements can modify both classes and modules.
|
|
|
|
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.
|
|
|
|
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. This is only true for +super+ in a method of a refinement, it
|
|
does not apply to +super+ in a method in a module that is included in a refinement.
|
|
|
|
== Methods Introspection
|
|
|
|
When using introspection methods such as Kernel#method or Kernel#methods refinements are not honored.
|
|
|
|
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 refinements from X.
|
|
|
|
For example, 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 descendants have higher precedence than those of ancestors.
|
|
|
|
== Further Reading
|
|
|
|
See https://bugs.ruby-lang.org/projects/ruby-master/wiki/RefinementsSpec for the
|
|
current specification for implementing refinements. The specification also
|
|
contains more details.
|