<ppdoc>
<copyright>
Copyright (c) 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 http://www.opencontent.org/openpub/).
<p/>
Distribution of substantively modified versions of this document is
prohibited without the explicit permission of the copyright holder.
<p/>
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.
</copyright>
<class name="Module" super="Object" type="class" ref="xref-000001">  <subclasses>Class</subclasses>
<p/>
  A <tt>Module</tt> 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 <cim><file>module</file><front>Module</front><back>module_function</back><mref>module_function</mref></cim>
  on page 346.
<p/>
  In the descriptions that follow, the
  parameter <obj>aSymbol</obj> refers to a symbol, which is either a
  quoted string or a <classname>Symbol</classname> (such as <tt>:name</tt>).
<p/>
<codefragment>
<fullcode><![CDATA[    module Mod
      include Math
      CONST = 1
      def meth
        #  ...
      end
    end
    Mod.type
    Mod.constants
    Mod.instance_methods
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>module<nbsp/>Mod</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>include<nbsp/>Math</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>CONST<nbsp/>=<nbsp/>1</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>meth</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>#<nbsp/><nbsp/>...</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
  <td><tt>Mod.type</tt></td>
  <td>&#187;</td>
  <td><tt>Module</tt></td>
</tr>
<tr>
  <td><tt>Mod.constants</tt></td>
  <td>&#187;</td>
  <td><tt>["CONST",<nbsp/>"E",<nbsp/>"PI"]</tt></td>
</tr>
<tr>
  <td><tt>Mod.instance_methods</tt></td>
  <td>&#187;</td>
  <td><tt>["meth"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
  <methods type="class">
        <method name="constants" ref="constants">
      <callseq>
        Module.constants <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns an array of the names of all constants defined in the
      system. This list includes the names of all modules and classes.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        p Module.constants.sort[1..5]
]]></fullcode>
p<nbsp/>Module.constants.sort[1..5]
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
["ARGV",<nbsp/>"ArgumentError",<nbsp/>"Array",<nbsp/>"Bignum",<nbsp/>"Binding"]
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="nesting" ref="nesting">
      <callseq>
        Module.nesting <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the list of <tt>Modules</tt> nested at the point of call.
<p/>
<codefragment>
<fullcode><![CDATA[         module M1
           module M2
             $a = Module.nesting
           end
         end
         $a
         $a[0].name
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>module<nbsp/>M1</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>module<nbsp/>M2</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>$a<nbsp/>=<nbsp/>Module.nesting</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
  <td><tt>$a</tt></td>
  <td>&#187;</td>
  <td><tt>[M1::M2,<nbsp/>M1]</tt></td>
</tr>
<tr>
  <td><tt>$a[0].name</tt></td>
  <td>&#187;</td>
  <td><tt>"M1::M2"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="new" ref="new">
      <callseq>
        Module.new <returns><obj>aModule</obj></returns>
      </callseq>
      <desc>
<p/>
      Creates a new anonymous module.      
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
        <method name="&lt;, &lt;=, &gt;, &gt;=" ref="_lt_cm_lt_eq_cm_lt_cm_lt_eq">
      <callseq>
        <obj>mod</obj> <tt><em>relop</em></tt>
        <obj>aModule</obj>
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Hierarchy Query---One module is considered <em>greater than</em>
      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.
<p/>
<codefragment>
<fullcode><![CDATA[         module Mixin
         end

         module Parent
           include Mixin
         end

         module Unrelated
         end

         Parent > Mixin
         Parent < Mixin
         Parent <= Parent
         Parent < Unrelated
         Parent > Unrelated
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>module<nbsp/>Mixin</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
<td colspan="3"><tt>module<nbsp/>Parent</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>include<nbsp/>Mixin</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
<td colspan="3"><tt>module<nbsp/>Unrelated</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
  <td><tt>Parent<nbsp/>&gt;<nbsp/>Mixin</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
<tr>
  <td><tt>Parent<nbsp/>&lt;<nbsp/>Mixin</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
  <td><tt>Parent<nbsp/>&lt;=<nbsp/>Parent</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
  <td><tt>Parent<nbsp/>&lt;<nbsp/>Unrelated</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
<tr>
  <td><tt>Parent<nbsp/>&gt;<nbsp/>Unrelated</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="&lt;=&gt;" ref="_lt_eq_lt">
      <callseq>
        <obj>mod</obj> &lt;=&gt; <obj>aModule</obj>
        <returns>-1, 0, +1</returns>
      </callseq>
      <desc>
<p/>
      Comparison---Returns -1 if <obj>mod</obj> includes <obj>aModule</obj>, 0 if <obj>mod</obj> is
      the same as <obj>aModule</obj>, and +1 if <obj>mod</obj> is included by
      <obj>aModule</obj> or if <obj>mod</obj> has no relationship with
      <obj>aModule</obj>.
<p/>
      </desc>
    </method>
<p/>
        <method name="===" ref="_eq_eq_eq">
      <callseq>
        <obj>mod</obj> === <obj>anObject</obj>
        <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Case Equality---Returns <const>true</const> if <obj>anObject</obj> is an instance of <obj>mod</obj>
      or one of <obj>mod</obj>'s descendents. Of limited use for modules, but 
      can be used in <kw>case</kw> statements to classify objects by class.
<p/>
      </desc>
    </method>
<p/>
        <method name="ancestors" ref="ancestors">
      <callseq>
        <obj>mod</obj>.ancestors <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a list of modules included in <obj>mod</obj> (including <obj>mod</obj>
      itself).
<p/>
<codefragment>
<fullcode><![CDATA[        module Mod
          include Math
          include Comparable
        end

        Mod.ancestors
        Math.ancestors
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>module<nbsp/>Mod</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>include<nbsp/>Math</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>include<nbsp/>Comparable</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
  <td><tt>Mod.ancestors</tt></td>
  <td>&#187;</td>
  <td><tt>[Mod,<nbsp/>Comparable,<nbsp/>Math]</tt></td>
</tr>
<tr>
  <td><tt>Math.ancestors</tt></td>
  <td>&#187;</td>
  <td><tt>[Math]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="class_eval" ref="class_eval">
      <callseq>
                  <obj>mod</obj>.class_eval( <obj>aString</obj> ) <returns><obj>anObject</obj></returns><br/><obj>mod</obj>.class_eval <block>{|  | <blockbody>block</blockbody> }</block>
 <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Synonym for <tt>Module.module_eval</tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="class_variables" ref="class_variables">
      <callseq>
        <obj>mod</obj>.class_variables
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns an array of the names of class variables in
      <obj>mod</obj> and the ancestors of <obj>mod</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[        class One
          @@var1 = 1
        end
        class Two < One
          @@var2 = 2
        end
        One.class_variables
        Two.class_variables
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>class<nbsp/>One</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>@@var1<nbsp/>=<nbsp/>1</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>class<nbsp/>Two<nbsp/>&lt;<nbsp/>One</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>@@var2<nbsp/>=<nbsp/>2</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
  <td><tt>One.class_variables</tt></td>
  <td>&#187;</td>
  <td><tt>["@@var1"]</tt></td>
</tr>
<tr>
  <td><tt>Two.class_variables</tt></td>
  <td>&#187;</td>
  <td><tt>["@@var2",<nbsp/>"@@var1"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="clone" ref="clone">
      <callseq>
        <obj>mod</obj>.clone <returns><obj>aModule</obj></returns>
      </callseq>
      <desc>
<p/>
      Creates a new copy of a module.
<p/>
<codefragment>
<fullcode><![CDATA[         m = Math.clone
         m.constants
         m == Math
]]></fullcode><rubycode>
<tr>
  <td><tt>m<nbsp/>=<nbsp/>Math.clone</tt></td>
  <td>&#187;</td>
  <td><tt>Math</tt></td>
</tr>
<tr>
  <td><tt>m.constants</tt></td>
  <td>&#187;</td>
  <td><tt>["E",<nbsp/>"PI"]</tt></td>
</tr>
<tr>
  <td><tt>m<nbsp/>==<nbsp/>Math</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="const_defined?" ref="const_defined_qm">
      <callseq>
                <obj>mod</obj>.const_defined?( <obj>aSymbol</obj> ) <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns <const>true</const> if a constant with
      the given name is defined by <obj>mod</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[         Math.const_defined? "PI"
]]></fullcode><rubycode>
<tr>
  <td><tt>Math.const_defined?<nbsp/>"PI"</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="const_get" ref="const_get">
      <callseq>
                <obj>mod</obj>.const_get( <obj>aSymbol</obj> ) <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the value of the named constant in <obj>mod</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[         Math.const_get :PI
]]></fullcode><rubycode>
<tr>
  <td><tt>Math.const_get<nbsp/>:PI</tt></td>
  <td>&#187;</td>
  <td><tt>3.141592654</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="const_set" ref="const_set">
      <callseq>
                <obj>mod</obj>.const_set( <obj>aSymbol</obj>, <obj>anObject</obj> )
           <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Sets the named constant to the given object, returning that
      object. Creates a new constant if no constant with the given
      name previously existed.
<p/>
<codefragment>
<fullcode><![CDATA[         Math.const_set("HIGH_SCHOOL_PI", 22.0/7.0)
         Math::HIGH_SCHOOL_PI - Math::PI
]]></fullcode><rubycode>
<tr>
  <td><tt>Math.const_set("HIGH_SCHOOL_PI",<nbsp/>22.0/7.0)</tt></td>
  <td>&#187;</td>
  <td><tt>3.142857143</tt></td>
</tr>
<tr>
  <td><tt>Math::HIGH_SCHOOL_PI<nbsp/>-<nbsp/>Math::PI</tt></td>
  <td>&#187;</td>
  <td><tt>0.001264489267</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="constants" ref="constants">
      <callseq>
                <obj>mod</obj>.constants <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns an array of the names of the constants accessible
      in <obj>mod</obj>. This includes the names of constants in any
      included modules (example at start of section).
<p/>
      </desc>
    </method>
<p/>
        <method name="included_modules" ref="included_modules">
      <callseq>
        <obj>mod</obj>.included_modules
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the list of modules included in <obj>mod</obj>.
<p/>
<codefragment>
<fullcode><![CDATA[         module Mixin
         end

         module Outer
           include Mixin
         end

         Mixin.included_modules
         Outer.included_modules
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>module<nbsp/>Mixin</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
<td colspan="3"><tt>module<nbsp/>Outer</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>include<nbsp/>Mixin</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
  <td><tt>Mixin.included_modules</tt></td>
  <td>&#187;</td>
  <td><tt>[]</tt></td>
</tr>
<tr>
  <td><tt>Outer.included_modules</tt></td>
  <td>&#187;</td>
  <td><tt>[Mixin]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="instance_methods" ref="instance_methods">
      <callseq>
        <obj>mod</obj>.instance_methods(
        <obj>includeSuper</obj>=<const>false</const> ) <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      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 
      <const>false</const>, the instance methods in <obj>mod</obj> are returned, 
      otherwise the methods in <obj>mod</obj> and <obj>mod</obj>'s superclasses
      are returned.
<codefragment>
<alltt><fullcode><![CDATA[         module A
!-           def method1()
!-           end
#           def method1()  end
         end
         class B
!-           def method2()
!-           end
#           def method2()  end
         end
         class C < B
!-           def method3()
!-           end
#           def method3()  end
         end
]]></fullcode>
module<nbsp/>A
<nbsp/><nbsp/>def<nbsp/>method1()<nbsp/><nbsp/>end
end
class<nbsp/>B
<nbsp/><nbsp/>def<nbsp/>method2()<nbsp/><nbsp/>end
end
class<nbsp/>C<nbsp/>&lt;<nbsp/>B
<nbsp/><nbsp/>def<nbsp/>method3()<nbsp/><nbsp/>end
end
</alltt>
</codefragment>
<p/>
<codefragment>
<fullcode><![CDATA[!-         module A
!-           def method1()
!-           end
!-         end
!-         class B
!-           def method2()
!-           end
!-         end
!-         class C < B
!-           def method3()
!-           end
!-         end
         A.instance_methods
         B.instance_methods
         C.instance_methods
         C.instance_methods(true).length
]]></fullcode><rubycode>
<tr>
  <td><tt>A.instance_methods</tt></td>
  <td>&#187;</td>
  <td><tt>["method1"]</tt></td>
</tr>
<tr>
  <td><tt>B.instance_methods</tt></td>
  <td>&#187;</td>
  <td><tt>["method2"]</tt></td>
</tr>
<tr>
  <td><tt>C.instance_methods</tt></td>
  <td>&#187;</td>
  <td><tt>["method3"]</tt></td>
</tr>
<tr>
  <td><tt>C.instance_methods(true).length</tt></td>
  <td>&#187;</td>
  <td><tt>39</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="method_defined?" ref="method_defined_qm">
      <callseq>
                <obj>mod</obj>.method_defined?( <obj>aSymbol</obj> ) <returns><const>true</const> or <const>false</const></returns>
      </callseq>
      <desc>
<p/>
      Returns <const>true</const> if the named method is defined by <obj>mod</obj>
      (or its included modules and, if <obj>mod</obj> is a class, its
      ancestors).
<p/>
<codefragment>
<fullcode><![CDATA[         module A
!-           def method1()
!-           end
#           def method1()  end
         end
         class B
!-           def method2()
!-           end
#           def method2()  end
         end
         class C < B
           include A
!-           def method3()
!-           end
#           def method3()  end
         end

         A.method_defined? :method1
         C.method_defined? "method1"
         C.method_defined? "method2"
         C.method_defined? "method3"
         C.method_defined? "method4"
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>module<nbsp/>A</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>method1()<nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>class<nbsp/>B</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>method2()<nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>class<nbsp/>C<nbsp/>&lt;<nbsp/>B</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>include<nbsp/>A</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>method3()<nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt></tt></td>
</tr>
<tr>
  <td><tt>A.method_defined?<nbsp/>:method1</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
  <td><tt>C.method_defined?<nbsp/>"method1"</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
  <td><tt>C.method_defined?<nbsp/>"method2"</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
  <td><tt>C.method_defined?<nbsp/>"method3"</tt></td>
  <td>&#187;</td>
  <td><tt>true</tt></td>
</tr>
<tr>
  <td><tt>C.method_defined?<nbsp/>"method4"</tt></td>
  <td>&#187;</td>
  <td><tt>false</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="module_eval" ref="module_eval">
      <callseq>
                  <obj>mod</obj>.module_eval( <obj>aString</obj> ) <returns><obj>anObject</obj></returns><br/><obj>mod</obj>.module_eval <block>{|  | <blockbody>block</blockbody> }</block>
 <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Evaluates the string or block in the context of <obj>mod</obj>. This can
      be used to add methods to a class. <meth>module_eval</meth> returns 
      the result of evaluating its argument.
<p/>
<codefragment>
<fullcode><![CDATA[        class Thing
        end
        a = %q{def hello() "Hello there!" end}
        Thing.module_eval(a)
        Thing.new.hello()
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>class<nbsp/>Thing</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>a<nbsp/>=<nbsp/>%q{def<nbsp/>hello()<nbsp/>"Hello<nbsp/>there!"<nbsp/>end}</tt></td>
</tr>
<tr>
  <td><tt>Thing.module_eval(a)</tt></td>
  <td>&#187;</td>
  <td><tt>nil</tt></td>
</tr>
<tr>
  <td><tt>Thing.new.hello()</tt></td>
  <td>&#187;</td>
  <td><tt>"Hello<nbsp/>there!"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="name" ref="name">
      <callseq>
        <obj>mod</obj>.name <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the name of the module <obj>mod</obj>.
<p/>
      </desc>
    </method>
<p/>
        <method name="private_class_method" ref="private_class_method">
      <callseq>
                <obj>mod</obj>.private_class_method( <optn><obj>aSymbol</obj></optn> )
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Makes existing class methods private.            
      Often used to hide the 
      default constructor <tt>new</tt>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[          class SimpleSingleton  # Not thread safe
            private_class_method :new
            def SimpleSingleton.create(*args, &block)
              @me = new(*args, &block) if ! @me
              @me
            end
          end
]]></fullcode>
class<nbsp/>SimpleSingleton<nbsp/><nbsp/>#<nbsp/>Not<nbsp/>thread<nbsp/>safe
<nbsp/><nbsp/>private_class_method<nbsp/>:new
<nbsp/><nbsp/>def<nbsp/>SimpleSingleton.create(*args,<nbsp/>&amp;block)
<nbsp/><nbsp/><nbsp/><nbsp/>@me<nbsp/>=<nbsp/>new(*args,<nbsp/>&amp;block)<nbsp/>if<nbsp/>!<nbsp/>@me
<nbsp/><nbsp/><nbsp/><nbsp/>@me
<nbsp/><nbsp/>end
end
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="private_instance_methods" ref="private_instance_methods">
      <callseq>
        <br/><obj>mod</obj>.private_instance_methods(
        <obj>includeSuper</obj>=<const>false</const> )
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a list of the private instance methods defined in <obj>mod</obj>.
      If the optional parameter is not <const>false</const>, the methods 
      of any ancestors are included.
<p/>
<codefragment>
<fullcode><![CDATA[         module Mod
!-           def method1()
!-           end
#           def method1()  end
           private :method1
!-           def method2()
!-           end
#           def method2()  end
         end
         Mod.instance_methods
         Mod.private_instance_methods
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>module<nbsp/>Mod</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>method1()<nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>private<nbsp/>:method1</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>method2()<nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
  <td><tt>Mod.instance_methods</tt></td>
  <td>&#187;</td>
  <td><tt>["method2"]</tt></td>
</tr>
<tr>
  <td><tt>Mod.private_instance_methods</tt></td>
  <td>&#187;</td>
  <td><tt>["method1"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="protected_instance_methods" ref="protected_instance_methods">
      <callseq>
        <br/><obj>mod</obj>.protected_instance_methods(
        <obj>includeSuper</obj>=<const>false</const> )
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a list of the protected instance methods defined in <obj>mod</obj>.
      If the optional parameter is not <const>false</const>, the methods 
      of any ancestors are included.
<p/>
      </desc>
    </method>
<p/>
        <method name="public_class_method" ref="public_class_method">
      <callseq>
                <obj>mod</obj>.public_class_method( <optn><obj>aSymbol</obj></optn> )
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Makes a list of existing class methods public.            
<p/>
      </desc>
    </method>
<p/>
        <method name="public_instance_methods" ref="public_instance_methods">
      <callseq>
        <br/><obj>mod</obj>.public_instance_methods(
        <obj>includeSuper</obj>=<const>false</const> )
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns a list of the public instance methods defined in <obj>mod</obj>.
      If the optional parameter is not <tt>false</tt>, the methods 
      of any ancestors are included.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="private">
<p/>
    The following methods are used mainly during the definition of
    classes and modules.
<p/>
        <method name="alias_method" ref="alias_method">
      <callseq>
                alias_method( <obj>newID, oldID</obj> )
        <returns><obj>mod</obj></returns>
      </callseq>
      <desc>
<p/>
      Makes <obj>newID</obj> a new copy of the method
      <obj>oldID</obj>. This can be used to retain access to methods that
      are overridden.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        module Mod
          alias_method :origExit, :exit
          def exit(code=0)
            print "Exiting with code #{code}\n"
            origExit(code)
          end
        end
        include Mod
        exit(99)
]]></fullcode>
module<nbsp/>Mod
<nbsp/><nbsp/>alias_method<nbsp/>:origExit,<nbsp/>:exit
<nbsp/><nbsp/>def<nbsp/>exit(code=0)
<nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"Exiting<nbsp/>with<nbsp/>code<nbsp/>#{code}\n"
<nbsp/><nbsp/><nbsp/><nbsp/>origExit(code)
<nbsp/><nbsp/>end
end
include<nbsp/>Mod
exit(99)
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Exiting<nbsp/>with<nbsp/>code<nbsp/>99
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="append_features" ref="append_features">
      <callseq>
                append_features( <obj>aModule</obj> )
        <returns><obj>mod</obj></returns>
      </callseq>
      <desc>
<p/>
      When this module is included in
      another, Ruby calls <meth>append_features</meth> in this module,
      passing it the receiving module in <obj>aModule</obj>. Ruby's default 
      implementation is to add the constants, methods, and module
      variables of this module to <obj>aModule</obj> if this
      module has not already been added to <obj>aModule</obj> or one of its
      ancestors. See also
      <cim><file>module</file><front>Module</front><back>include</back><mref>include</mref></cim> on page 345.
<p/>
      </desc>
    </method>
<p/>
        <method name="attr" ref="attr">
      <callseq>
                attr( <obj>aSymbol</obj>, <obj>writable</obj>=<const>false</const> )
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
              Defines a named attribute for this module, where the name is
      <obj>aSymbol.</obj><tt>id2name</tt>, creating an instance variable
      (<var>@name</var>) and a corresponding access method to read it.
      If the optional <obj>writable</obj>
      argument is <const>true</const>, also creates a method called <tt>name=</tt> to 
      set the attribute.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        module Mod
          attr  :size, true
        end
]]></fullcode>
module<nbsp/>Mod
<nbsp/><nbsp/>attr<nbsp/><nbsp/>:size,<nbsp/>true
end
</alltt>
</codefragment>
      <em>is equivalent to:</em>
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        module Mod
          def size
            @size
          end
          def size=(val)
            @size = val
          end
        end
]]></fullcode>
module<nbsp/>Mod
<nbsp/><nbsp/>def<nbsp/>size
<nbsp/><nbsp/><nbsp/><nbsp/>@size
<nbsp/><nbsp/>end
<nbsp/><nbsp/>def<nbsp/>size=(val)
<nbsp/><nbsp/><nbsp/><nbsp/>@size<nbsp/>=<nbsp/>val
<nbsp/><nbsp/>end
end
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="attr_accessor" ref="attr_accessor">
      <callseq>
                attr_accessor( <optn><obj>aSymbol</obj></optn> )
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Equivalent to calling ``<tt>attr<nbsp/></tt><obj>aSymbol</obj><tt>,<nbsp/>true</tt>'' on each
      <obj>aSymbol</obj> in turn.
<p/>
<codefragment>
<fullcode><![CDATA[        module Mod
          attr_accessor(:one, :two)
        end
        Mod.instance_methods.sort
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>module<nbsp/>Mod</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>attr_accessor(:one,<nbsp/>:two)</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
  <td><tt>Mod.instance_methods.sort</tt></td>
  <td>&#187;</td>
  <td><tt>["one",<nbsp/>"one=",<nbsp/>"two",<nbsp/>"two="]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="attr_reader" ref="attr_reader">
      <callseq>
                attr_reader( <optn><obj>aSymbol</obj></optn> )
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Creates instance variables and corresponding methods that
      return the value of each instance variable.
      Equivalent to calling ``<tt>attr<nbsp/></tt><obj>:name</obj>'' on each name
      in turn.
<p/>
      </desc>
    </method>
<p/>
        <method name="attr_writer" ref="attr_writer">
      <callseq>
<p/>
        attr_writer( <optn><obj>aSymbol</obj></optn> )
        <returns><tt>nil</tt></returns>
      </callseq>
      <desc>
<p/>
      Creates an accessor method to allow assignment to the attribute
      <obj>aSymbol</obj><tt>.id2name</tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="extend_object" ref="extend_object">
      <callseq>
                extend_object( <obj>anObject</obj> )
        <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      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 <cim><file>object</file><front>Object</front><back>extend</back><mref>extend</mref></cim>.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        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
]]></fullcode>
module<nbsp/>Picky
<nbsp/><nbsp/>def<nbsp/>Picky.extend_object(o)
<nbsp/><nbsp/><nbsp/><nbsp/>if<nbsp/>String<nbsp/>===<nbsp/>o
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"Can't<nbsp/>add<nbsp/>Picky<nbsp/>to<nbsp/>a<nbsp/>String\n"
<nbsp/><nbsp/><nbsp/><nbsp/>else
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"Picky<nbsp/>added<nbsp/>to<nbsp/>",<nbsp/>o.type,<nbsp/>"\n"
<nbsp/><nbsp/><nbsp/><nbsp/><nbsp/><nbsp/>super
<nbsp/><nbsp/><nbsp/><nbsp/>end
<nbsp/><nbsp/>end
end
(s<nbsp/>=<nbsp/>Array.new).extend<nbsp/>Picky<nbsp/><nbsp/>#<nbsp/>Call<nbsp/>Object.extend
(s<nbsp/>=<nbsp/>"quick<nbsp/>brown<nbsp/>fox").extend<nbsp/>Picky
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Picky<nbsp/>added<nbsp/>to<nbsp/>Array
Can't<nbsp/>add<nbsp/>Picky<nbsp/>to<nbsp/>a<nbsp/>String
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="include" ref="include">
      <callseq>
                include( <optn><obj>aModule</obj></optn> )
        <returns><obj>mod</obj></returns>
      </callseq>
      <desc>
<p/>
      Invokes <tt>Module.append_features</tt>
      (documented on page 344)
      on each parameter in turn. 
<p/>
      </desc>
    </method>
<p/>
        <method name="method_added" ref="method_added">
      <callseq>
        method_added( <obj>aSymbol</obj> )
      </callseq>
      <desc>
<p/>
      Invoked as a callback whenever a method is added to the receiver.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        module Chatty
          def Chatty.method_added(id)
            print "Adding ", id.id2name, "\n"
          end
          def one()   end
        end
        module Chatty
          def two()   end
        end
]]></fullcode>
module<nbsp/>Chatty
<nbsp/><nbsp/>def<nbsp/>Chatty.method_added(id)
<nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"Adding<nbsp/>",<nbsp/>id.id2name,<nbsp/>"\n"
<nbsp/><nbsp/>end
<nbsp/><nbsp/>def<nbsp/>one()<nbsp/><nbsp/><nbsp/>end
end
module<nbsp/>Chatty
<nbsp/><nbsp/>def<nbsp/>two()<nbsp/><nbsp/><nbsp/>end
end
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
Adding<nbsp/>one
Adding<nbsp/>two
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="module_function" ref="module_function">
      <callseq>
                module_function( <optz><obj>aSymbol</obj></optz> )  <returns><obj>mod</obj></returns>
      </callseq>
      <desc>
<p/>
            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.
<p/>
<codefragment>
<fullcode><![CDATA[        module Mod
          def one
            "This is one"
          end
          module_function :one
        end
        class Cls
          include Mod
          def callOne
            one
          end
        end
        Mod.one
        c = Cls.new
        c.callOne
        module Mod
          def one
            "This is the new one"
          end
        end
        Mod.one
        c.callOne
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>module<nbsp/>Mod</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>one</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>"This<nbsp/>is<nbsp/>one"</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>module_function<nbsp/>:one</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>class<nbsp/>Cls</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>include<nbsp/>Mod</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>callOne</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>one</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
  <td><tt>Mod.one</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>one"</tt></td>
</tr>
<tr>
<td colspan="3"><tt>c<nbsp/>=<nbsp/>Cls.new</tt></td>
</tr>
<tr>
  <td><tt>c.callOne</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>one"</tt></td>
</tr>
<tr>
<td colspan="3"><tt>module<nbsp/>Mod</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>one</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/><nbsp/><nbsp/>"This<nbsp/>is<nbsp/>the<nbsp/>new<nbsp/>one"</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
  <td><tt>Mod.one</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>one"</tt></td>
</tr>
<tr>
  <td><tt>c.callOne</tt></td>
  <td>&#187;</td>
  <td><tt>"This<nbsp/>is<nbsp/>the<nbsp/>new<nbsp/>one"</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="private" ref="private">
      <callseq>
        private( <optz><obj>aSymbol</obj></optz> )
        <returns><obj>mod</obj></returns>
      </callseq>
      <desc>
<p/>
      With no arguments, sets the default visibility for subsequently
      defined methods to private.            
      With arguments, sets the named
      methods to have private visibility. See <em>Access Control</em>
      starting on page 233. 
<p/>
<codefragment>
<fullcode><![CDATA[        module Mod
!-          def a()
!-          end
#          def a()  end
!-          def b()
!-          end
#          def b()  end
          private
!-          def c()
!-          end
#          def c()  end
          private :a
        end
        Mod.private_instance_methods
]]></fullcode><rubycode>
<tr>
<td colspan="3"><tt>module<nbsp/>Mod</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>a()<nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>b()<nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>private</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>def<nbsp/>c()<nbsp/><nbsp/>end</tt></td>
</tr>
<tr>
<td colspan="3"><tt><nbsp/><nbsp/>private<nbsp/>:a</tt></td>
</tr>
<tr>
<td colspan="3"><tt>end</tt></td>
</tr>
<tr>
  <td><tt>Mod.private_instance_methods</tt></td>
  <td>&#187;</td>
  <td><tt>["a",<nbsp/>"c"]</tt></td>
</tr>
</rubycode>
<p/>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="protected" ref="protected">
      <callseq>
        protected( <optz><obj>aSymbol</obj></optz> )
        <returns><obj>mod</obj></returns>
      </callseq>
      <desc>
<p/>
      With no arguments, sets the default visibility for subsequently
      defined methods to protected.            
      With arguments, sets the named
      methods to have protected visibility. See <em>Access Control</em> starting
      on page 233.
<p/>
      </desc>
    </method>
<p/>
        <method name="public" ref="public">
      <callseq>
        public( <optz><obj>aSymbol</obj></optz> )
        <returns><obj>mod</obj></returns>
      </callseq>
      <desc>
<p/>
      With no arguments, sets the default visibility for subsequently
      defined methods to public.            
      With arguments, sets the named
      methods to have public visibility. See <em>Access Control</em> starting
      on page 233.
<p/>
      </desc>
    </method>
<p/>
        <method name="remove_const" ref="remove_const">
      <callseq>
        remove_const( <obj>aSymbol</obj> )
        <returns><obj>anObject</obj></returns>
      </callseq>
      <desc>
<p/>
      Removes the definition of the given constant, returning that
      constant's value. Predefined classes and singleton objects (such 
      as <obj>true</obj>) cannot be removed.
<p/>
      </desc>
    </method>
<p/>
        <method name="remove_method" ref="remove_method">
      <callseq>
        remove_method( <obj>aSymbol</obj> )
        <returns><obj>mod</obj></returns>
      </callseq>
      <desc>
         Removes the method identified by
      <obj>aSymbol</obj>
      from the current class.
      For an example, see <tt>Module.undef_method</tt>.
<p/>
      </desc>
    </method>
<p/>
        <method name="undef_method" ref="undef_method">
      <callseq>
        undef_method( <obj>aSymbol</obj> )
        <returns><obj>mod</obj></returns>
      </callseq>
      <desc>
<p/>
      Prevents the current class from responding to calls to the named
      method. Contrast this with
      <meth>remove_method</meth>, which
      deletes the method from the particular class; Ruby will still
      search superclasses and mixed-in modules for a possible
      receiver.
<p/>
<codefragment>
<alltt><fullcode><![CDATA[        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
]]></fullcode>
class<nbsp/>Parent
<nbsp/><nbsp/>def<nbsp/>hello
<nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"In<nbsp/>parent\n"
<nbsp/><nbsp/>end
end
class<nbsp/>Child<nbsp/>&lt;<nbsp/>Parent
<nbsp/><nbsp/>def<nbsp/>hello
<nbsp/><nbsp/><nbsp/><nbsp/>print<nbsp/>"In<nbsp/>child\n"
<nbsp/><nbsp/>end
end
<p/>
c<nbsp/>=<nbsp/>Child.new
c.hello
<p/>
class<nbsp/>Child
<nbsp/><nbsp/>remove_method<nbsp/>:hello<nbsp/><nbsp/>#<nbsp/>remove<nbsp/>from<nbsp/>child,<nbsp/>still<nbsp/>in<nbsp/>parent
end
c.hello
<p/>
class<nbsp/>Child
<nbsp/><nbsp/>undef_method<nbsp/>:hello<nbsp/><nbsp/><nbsp/>#<nbsp/>prevent<nbsp/>any<nbsp/>calls<nbsp/>to<nbsp/>'hello'
end
c.hello
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
In<nbsp/>child
In<nbsp/>parent
prog.rb:23:<nbsp/>undefined<nbsp/>method<nbsp/>`hello'<nbsp/>for<nbsp/>#&lt;Child:0x401b5928&gt;<nbsp/>(NameError)
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>
