|
 |
|
| |
|
class Module
|
|
Parent:
|
Object
|
|
Version:
|
1.6
|
|
Index:
constants
nesting
new
<, <=, >, >=
<=>
===
ancestors
class_eval
class_variables
clone
const_defined?
const_get
const_set
constants
included_modules
instance_methods
method_defined?
module_eval
name
private_class_method
private_instance_methods
protected_instance_methods
public_class_method
public_instance_methods
alias_method
append_features
attr
attr_accessor
attr_reader
attr_writer
extend_object
include
method_added
module_function
private
protected
public
remove_const
remove_method
undef_method
Subclasses: Class
A Module is a collection of methods and constants. The methods
in a module may be instance methods or module methods. Instance
methods appear as methods in a class when the module is included,
module methods do not. Conversely, module methods may be called
without creating an encapsulating object, while instance methods may
not. See
Module#module_function
on page 346.
In the descriptions that follow, the
parameter aSymbol refers to a symbol, which is either a
quoted string or a Symbol (such as :name).
module Mod
|
include Math
|
CONST = 1
|
def meth
|
# ...
|
end
|
end
|
Mod.type
|
� |
Module
|
Mod.constants
|
� |
["CONST", "E", "PI"]
|
Mod.instance_methods
|
� |
["meth"]
|
|
class methods
|
|
constants
|
Module.constants -> anArray
|
|
Returns an array of the names of all constants defined in the
system. This list includes the names of all modules and classes.
p Module.constants.sort[1..5]
|
produces:
["ARGV", "ArgumentError", "Array", "Bignum", "Binding"]
|
|
|
nesting
|
Module.nesting -> anArray
|
|
Returns the list of Modules nested at the point of call.
module M1
|
module M2
|
$a = Module.nesting
|
end
|
end
|
$a
|
� |
[M1::M2, M1]
|
$a[0].name
|
� |
"M1::M2"
|
|
|
new
|
Module.new -> aModule
|
|
Creates a new anonymous module.
|
|
instance methods
|
|
<, <=, >, >=
|
mod
relop
aModule
-> true or false
|
|
Hierarchy Query---One module is considered greater than
another if it is included in (or is a
parent class of) the other module.
The other operators are
defined accordingly. If there is no relationship
between the modules, returns false for all operators.
module Mixin
|
end
|
|
module Parent
|
include Mixin
|
end
|
|
module Unrelated
|
end
|
|
Parent > Mixin
|
� |
false
|
Parent < Mixin
|
� |
true
|
Parent <= Parent
|
� |
true
|
Parent < Unrelated
|
� |
false
|
Parent > Unrelated
|
� |
false
|
|
|
<=>
|
mod <=> aModule
-> -1, 0, +1
|
|
Comparison---Returns -1 if mod includes aModule, 0 if mod is
the same as aModule, and +1 if mod is included by
aModule or if mod has no relationship with
aModule.
|
|
===
|
mod === anObject
-> true or false
|
|
Case Equality---Returns true if anObject is an instance of mod
or one of mod's descendents. Of limited use for modules, but
can be used in case statements to classify objects by class.
|
|
ancestors
|
mod.ancestors -> anArray
|
|
Returns a list of modules included in mod (including mod
itself).
module Mod
|
include Math
|
include Comparable
|
end
|
|
Mod.ancestors
|
� |
[Mod, Comparable, Math]
|
Math.ancestors
|
� |
[Math]
|
|
|
class_eval
|
mod.class_eval( aString ) -> anObject
mod.class_eval {| | block }
-> anObject
|
|
Synonym for Module.module_eval.
|
|
class_variables
|
mod.class_variables
-> anArray
|
|
Returns an array of the names of class variables in
mod and the ancestors of mod.
class One
|
@@var1 = 1
|
end
|
class Two < One
|
@@var2 = 2
|
end
|
One.class_variables
|
� |
["@@var1"]
|
Two.class_variables
|
� |
["@@var2", "@@var1"]
|
|
|
clone
|
mod.clone -> aModule
|
|
Creates a new copy of a module.
m = Math.clone
|
� |
Math
|
m.constants
|
� |
["E", "PI"]
|
m == Math
|
� |
false
|
|
|
const_defined?
|
mod.const_defined?( aSymbol ) -> true or false
|
|
Returns true if a constant with
the given name is defined by mod.
Math.const_defined? "PI"
|
� |
true
|
|
|
const_get
|
mod.const_get( aSymbol ) -> anObject
|
|
Returns the value of the named constant in mod.
Math.const_get :PI
|
� |
3.141592654
|
|
|
const_set
|
mod.const_set( aSymbol, anObject )
-> anObject
|
|
Sets the named constant to the given object, returning that
object. Creates a new constant if no constant with the given
name previously existed.
Math.const_set("HIGH_SCHOOL_PI", 22.0/7.0)
|
� |
3.142857143
|
Math::HIGH_SCHOOL_PI - Math::PI
|
� |
0.001264489267
|
|
|
constants
|
mod.constants -> anArray
|
|
Returns an array of the names of the constants accessible
in mod. This includes the names of constants in any
included modules (example at start of section).
|
|
included_modules
|
mod.included_modules
-> anArray
|
|
Returns the list of modules included in mod.
module Mixin
|
end
|
|
module Outer
|
include Mixin
|
end
|
|
Mixin.included_modules
|
� |
[]
|
Outer.included_modules
|
� |
[Mixin]
|
|
|
instance_methods
|
mod.instance_methods(
includeSuper=false ) -> anArray
|
|
Returns an array containing the names of public instance methods
in the receiver. For a module, these are the public methods; for
a class, they are the instance (not singleton) methods. With no
argument, or with an argument that is
false, the instance methods in mod are returned,
otherwise the methods in mod and mod's superclasses
are returned.
module A
def method1() end
end
class B
def method2() end
end
class C < B
def method3() end
end
|
A.instance_methods
|
� |
["method1"]
|
B.instance_methods
|
� |
["method2"]
|
C.instance_methods
|
� |
["method3"]
|
C.instance_methods(true).length
|
� |
39
|
|
|
method_defined?
|
mod.method_defined?( aSymbol ) -> true or false
|
|
Returns true if the named method is defined by mod
(or its included modules and, if mod is a class, its
ancestors).
module A
|
def method1() end
|
end
|
class B
|
def method2() end
|
end
|
class C < B
|
include A
|
def method3() end
|
end
|
|
A.method_defined? :method1
|
� |
true
|
C.method_defined? "method1"
|
� |
true
|
C.method_defined? "method2"
|
� |
true
|
C.method_defined? "method3"
|
� |
true
|
C.method_defined? "method4"
|
� |
false
|
|
|
module_eval
|
mod.module_eval( aString ) -> anObject
mod.module_eval {| | block }
-> anObject
|
|
Evaluates the string or block in the context of mod. This can
be used to add methods to a class. module_eval returns
the result of evaluating its argument.
class Thing
|
end
|
a = %q{def hello() "Hello there!" end}
|
Thing.module_eval(a)
|
� |
nil
|
Thing.new.hello()
|
� |
"Hello there!"
|
|
|
name
|
mod.name -> aString
|
|
Returns the name of the module mod.
|
|
private_class_method
|
mod.private_class_method( [
aSymbol
]+
)
-> nil
|
|
Makes existing class methods private.
Often used to hide the
default constructor new.
class SimpleSingleton # Not thread safe
private_class_method :new
def SimpleSingleton.create(*args, &block)
@me = new(*args, &block) if ! @me
@me
end
end
|
|
|
private_instance_methods
|
mod.private_instance_methods(
includeSuper=false )
-> anArray
|
|
Returns a list of the private instance methods defined in mod.
If the optional parameter is not false, the methods
of any ancestors are included.
module Mod
|
def method1() end
|
private :method1
|
def method2() end
|
end
|
Mod.instance_methods
|
� |
["method2"]
|
Mod.private_instance_methods
|
� |
["method1"]
|
|
|
protected_instance_methods
|
mod.protected_instance_methods(
includeSuper=false )
-> anArray
|
|
Returns a list of the protected instance methods defined in mod.
If the optional parameter is not false, the methods
of any ancestors are included.
|
|
public_class_method
|
mod.public_class_method( [
aSymbol
]+
)
-> nil
|
|
Makes a list of existing class methods public.
|
|
public_instance_methods
|
mod.public_instance_methods(
includeSuper=false )
-> anArray
|
|
Returns a list of the public instance methods defined in mod.
If the optional parameter is not false, the methods
of any ancestors are included.
|
|
private methods
|
|
alias_method
|
alias_method( newID, oldID )
-> mod
|
|
Makes newID a new copy of the method
oldID. This can be used to retain access to methods that
are overridden.
module Mod
alias_method :origExit, :exit
def exit(code=0)
print "Exiting with code #{code}\n"
origExit(code)
end
end
include Mod
exit(99)
|
produces:
|
|
append_features
|
append_features( aModule )
-> mod
|
|
When this module is included in
another, Ruby calls append_features in this module,
passing it the receiving module in aModule. Ruby's default
implementation is to add the constants, methods, and module
variables of this module to aModule if this
module has not already been added to aModule or one of its
ancestors. See also
Module#include
on page 345.
|
|
attr
|
attr( aSymbol, writable=false )
-> nil
|
|
Defines a named attribute for this module, where the name is
aSymbol.
id2name, creating an instance variable
(@name) and a corresponding access method to read it.
If the optional writable
argument is true, also creates a method called name= to
set the attribute.
module Mod
attr :size, true
end
|
is equivalent to:
module Mod
def size
@size
end
def size=(val)
@size = val
end
end
|
|
|
attr_accessor
|
attr_accessor( [
aSymbol
]+
)
-> nil
|
|
Equivalent to calling ``attr
aSymbol
, true'' on each
aSymbol in turn.
module Mod
|
attr_accessor(:one, :two)
|
end
|
Mod.instance_methods.sort
|
� |
["one", "one=", "two", "two="]
|
|
|
attr_reader
|
attr_reader( [
aSymbol
]+
)
-> nil
|
|
Creates instance variables and corresponding methods that
return the value of each instance variable.
Equivalent to calling ``attr
:name'' on each name
in turn.
|
|
attr_writer
|
attr_writer( [
aSymbol
]+
)
-> nil
|
|
Creates an accessor method to allow assignment to the attribute
aSymbol
.id2name.
|
|
extend_object
|
extend_object( anObject )
-> anObject
|
|
Extends the specified object by adding this module's constants
and methods (which are added as singleton methods). This is the
callback method used by
Object#extend
.
module Picky
def Picky.extend_object(o)
if String === o
print "Can't add Picky to a String\n"
else
print "Picky added to ", o.type, "\n"
super
end
end
end
(s = Array.new).extend Picky # Call Object.extend
(s = "quick brown fox").extend Picky
|
produces:
Picky added to Array
Can't add Picky to a String
|
|
|
include
|
include( [
aModule
]+
)
-> mod
|
|
Invokes Module.append_features
(documented on page 344)
on each parameter in turn.
|
|
method_added
|
method_added( aSymbol )
|
|
Invoked as a callback whenever a method is added to the receiver.
module Chatty
def Chatty.method_added(id)
print "Adding ", id.id2name, "\n"
end
def one() end
end
module Chatty
def two() end
end
|
produces:
|
|
module_function
|
module_function( [
aSymbol
]*
) -> mod
|
|
Creates module functions for the named methods. These
functions may be called with the module as a receiver, and also
become available as instance methods to classes that mix in the
module. Module functions are copies of the original, and so may
be changed independently. The instance-method versions are made
private. If used with no arguments, subsequently defined methods
become module functions.
module Mod
|
def one
|
"This is one"
|
end
|
module_function :one
|
end
|
class Cls
|
include Mod
|
def callOne
|
one
|
end
|
end
|
Mod.one
|
� |
"This is one"
|
c = Cls.new
|
c.callOne
|
� |
"This is one"
|
module Mod
|
def one
|
"This is the new one"
|
end
|
end
|
Mod.one
|
� |
"This is one"
|
c.callOne
|
� |
"This is the new one"
|
|
|
private
|
private( [
aSymbol
]*
)
-> mod
|
|
With no arguments, sets the default visibility for subsequently
defined methods to private.
With arguments, sets the named
methods to have private visibility. See Access Control
starting on page 233.
module Mod
|
def a() end
|
def b() end
|
private
|
def c() end
|
private :a
|
end
|
Mod.private_instance_methods
|
� |
["a", "c"]
|
|
|
protected
|
protected( [
aSymbol
]*
)
-> mod
|
|
With no arguments, sets the default visibility for subsequently
defined methods to protected.
With arguments, sets the named
methods to have protected visibility. See Access Control starting
on page 233.
|
|
public
|
public( [
aSymbol
]*
)
-> mod
|
|
With no arguments, sets the default visibility for subsequently
defined methods to public.
With arguments, sets the named
methods to have public visibility. See Access Control starting
on page 233.
|
|
remove_const
|
remove_const( aSymbol )
-> anObject
|
|
Removes the definition of the given constant, returning that
constant's value. Predefined classes and singleton objects (such
as true) cannot be removed.
|
|
remove_method
|
remove_method( aSymbol )
-> mod
|
|
Removes the method identified by
aSymbol
from the current class.
For an example, see Module.undef_method.
|
|
undef_method
|
undef_method( aSymbol )
-> mod
|
|
Prevents the current class from responding to calls to the named
method. Contrast this with
remove_method, which
deletes the method from the particular class; Ruby will still
search superclasses and mixed-in modules for a possible
receiver.
class Parent
def hello
print "In parent\n"
end
end
class Child < Parent
def hello
print "In child\n"
end
end
c = Child.new
c.hello
class Child
remove_method :hello # remove from child, still in parent
end
c.hello
class Child
undef_method :hello # prevent any calls to 'hello'
end
c.hello
|
produces:
In child
In parent
prog.rb:23: undefined method `hello' for #<Child:0x401b5928> (NameError)
|
|
|
|
|
