Programming Ruby

The Pragmatic Programmer's Guide

Previous < Contents ^
Next >
class Module
Parent: Object
Version: 1.6


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
    #  ...
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]
["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
$a [M1::M2, M1]
$a[0].name "M1::M2"

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
module Parent
  include Mixin
module Unrelated
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
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
class Two < One
  @@var2 = 2
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
module Outer
  include Mixin
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
class B
  def method2()  end
class C < B
  def method3()  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
class B
  def method2()  end
class C < B
  include A
  def method3()  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
a = %q{def hello() "Hello there!" end}
Thing.module_eval(a) nil "Hello there!"

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

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
Mod.instance_methods ["method2"]
Mod.private_instance_methods ["method1"]

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.

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"
include Mod
Exiting with code 99

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
is equivalent to:

module Mod
  def size
  def size=(val)
    @size = val

attr_accessor attr_accessor( [ aSymbol ]+ ) -> nil

Equivalent to calling ``attr  aSymbol , true'' on each aSymbol in turn.

module Mod
  attr_accessor(:one, :two)
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( [ 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"
      print "Picky added to ", o.type, "\n"
(s = Picky  # Call Object.extend
(s = "quick brown fox").extend Picky
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"
  def one()   end
module Chatty
  def two()   end
Adding one
Adding two

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"
  module_function :one
class Cls
  include Mod
  def callOne
end "This is one"
c =
c.callOne "This is one"
module Mod
  def one
    "This is the new one"
end "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
  def c()  end
  private :a
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"
class Child < Parent
  def hello
    print "In child\n"

c = 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
In child
In parent
prog.rb:23: undefined method `hello' for #<Child:0x401b5928> (NameError)

Previous < Contents ^
Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2001 by Addison Wesley Longman, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.