U:RDoc::TopLevel[	iI"$syntax/modules_and_classes.rdoc:EFcRDoc::Parser::Simpleo:RDoc::Markup::Document:@parts[
€S:RDoc::Markup::Heading:
leveli:	textI"Modules;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[I"NModules serve two purposes in Ruby, namespacing and mix-in functionality.;T@
o;
;[	I"OA namespace can be used to organize code by package or functionality that ;TI"Sseparates common names from interference by other packages.  For example, the ;TI"LIRB namespace provides functionality for irb that prevents a collision ;TI"#for the common name "Context".;T@
o;
;[	I"SMix-in functionality allows sharing common methods across multiple classes or ;TI"Pmodules.  Ruby comes with the Enumerable mix-in module which provides many ;TI"Uenumeration methods based on the +each+ method and Comparable allows comparison ;TI"@of objects based on the <code><=></code> comparison method.;T@
o;
;[I"UNote that there are many similarities between modules and classes.  Besides the ;TI"Rability to mix-in a module, the description of modules below also applies to ;TI"
classes.;T@
S;	;
i;I"Module Definition;T@
o;
;[I"4A module is created using the +module+ keyword:;T@
o:RDoc::Markup::Verbatim;[I"module MyModule
;TI"
  # ...
;TI"	end
;T:@format0o;
;[I"KA module may be reopened any number of times to add, change or remove ;TI"functionality:;T@
o;;[I"module MyModule
;TI"  def my_method
;TI"  end
;TI"	end
;TI"
;TI"module MyModule
;TI"   alias my_alias my_method
;TI"	end
;TI"
;TI"module MyModule
;TI"   remove_method :my_method
;TI"	end
;T;0o;
;[I"RReopening classes is a very powerful feature of Ruby, but it is best to only ;TI"Rreopen classes you own.  Reopening classes you do not own may lead to naming ;TI"-conflicts or difficult to diagnose bugs.;T@
S;	;
i;I"Nesting;T@
o;
;[I"Modules may be nested:;T@
o;;[	I"module Outer
;TI"  module Inner
;TI"  end
;TI"	end
;T;0o;
;[I"LMany packages create a single outermost module (or class) to provide a ;TI"'namespace for their functionality.;T@
o;
;[I"PYou may also define inner modules using <code>::</code> provided the outer ;TI".modules (or classes) are already defined:;T@
o;;[I"%module Outer::Inner::GrandChild
;TI"	end
;T;0o;
;[I"<Note that this will raise a +NameError+ if +Outer+ and ;TI"7<code>Outer::Inner</code> are not already defined.;T@
o;
;[	I"LThis style has the benefit of allowing the author to reduce the amount ;TI"Pof indentation.  Instead of 3 levels of indentation only one is necessary. ;TI"QHowever, the scope of constant lookup is different for creating a namespace ;TI":using this syntax instead of the more verbose syntax.;T@
S;	;
i;I"
Scope;T@
S;	;
i;I"+self+;T@
o;
;[I"U+self+ refers to the object that defines the current scope.  +self+ will change ;TI"Dwhen entering a different method or when defining a new module.;T@
S;	;
i;I"Constants;T@
o;
;[	I"OAccessible constants are different depending on the module nesting (which ;TI"Fsyntax was used to define the module).  In the following example ;TI"Mthe constant <code>A::Z</code> is accessible from B as A is part of the ;TI"
nesting:;T@
o;;[
I"module A
;TI"
  Z = 1
;TI"
;TI"  module B
;TI"(    p Module.nesting #=> [A::B, A]
;TI"    p Z #=> 1
;TI"  end
;TI"	end
;T;0o;
;[I"MHowever, if you use <code>::</code> to define <code>A::B</code> without ;TI"Tnesting it inside +A+ a NameError exception will be raised because the nesting ;TI"does not include +A+:;T@
o;;[
I"module A
;TI"
  Z = 1
;TI"	end
;TI"
;TI"module A::B
;TI"#  p Module.nesting #=> [A::B]
;TI"   p Z #=> raises NameError
;TI"	end
;T;0o;
;[I"HIf a constant is defined at the top-level you may preceded it with ;TI"%<code>::</code> to reference it:;T@
o;;[I"Z = 0
;TI"
;TI"module A
;TI"
  Z = 1
;TI"
;TI"  module B
;TI"    p ::Z #=> 0
;TI"  end
;TI"	end
;T;0S;	;
i;I"Methods;T@
o;
;[I"KFor method definition documentation see the {syntax documentation for ;TI",methods}[rdoc-ref:syntax/methods.rdoc].;T@
o;
;[	I"OClass methods may be called directly.  (This is slightly confusing, but a ;TI"Nmethod on a module is often called a "class method" instead of a "module ;TI"Tmethod".  See also Module#module_function which can convert an instance method ;TI"into a class method.);T@
o;
;[I"UWhen a class method references a constant it uses the same rules as referencing ;TI"4it outside the method as the scope is the same.;T@
o;
;[I"RInstance methods defined in a module are only callable when included.  These ;TI"Rmethods have access to the constants defined when they were included through ;TI"the ancestors list:;T@
o;;[I"module A
;TI"
  Z = 1
;TI"
;TI"
  def z
;TI"    Z
;TI"  end
;TI"	end
;TI"
;TI"include A
;TI"
;TI"Ap self.class.ancestors #=> [Object, A, Kernel, BasicObject]
;TI"p z #=> 1
;T;0S;	;
i;I"Visibility;T@
o;
;[I"TRuby has three types of visibility.  The default is +public+.  A public method ;TI")may be called from any other object.;T@
o;
;[I"PThe second visibility is +protected+.  When calling a protected method the ;TI"Usender must be a subclass of the receiver or the receiver must be a subclass of ;TI";the sender.  Otherwise a NoMethodError will be raised.;T@
o;
;[I"PProtected visibility is most frequently used to define <code>==</code> and ;TI"Sother comparison methods where the author does not wish to expose an object's ;TI"Qstate to any caller and would like to restrict it only to inherited classes.;T@
o;
;[I"Here is an example:;T@
o;;[I"
class A
;TI"  def n(other)
;TI"    other.m
;TI"  end
;TI"	end
;TI"
;TI"class B < A
;TI"
  def m
;TI"    1
;TI"  end
;TI"
;TI"  protected :m
;TI"
;TI"	end
;TI"
;TI"class C < B
;TI"	end
;TI"
;TI"a = A.new
;TI"b = B.new
;TI"c = C.new
;TI"
;TI")c.n b #=> 1 -- C is a subclass of B
;TI"/b.n b #=> 1 -- m called on defining class
;TI";a.n b # raises NoMethodError A is not a subclass of B
;T;0o;
;[I"SThe third visibility is +private+.  A private method may not be called with a ;TI"Qreceiver, not even +self+.  If a private method is called with a receiver a ;TI""NoMethodError will be raised.;T@
S;	;
i;I"+alias+ and +undef+;T@
o;
;[I"JYou may also alias or undefine methods, but these operations are not ;TI"Frestricted to modules or classes.  See the {miscellaneous syntax ;TI"Dsection}[rdoc-ref:syntax/miscellaneous.rdoc] for documentation.;T@
S;	;
i;I"Classes;T@
o;
;[I"UEvery class is also a module, but unlike modules a class may not be mixed-in to ;TI"Tanother module (or class).  Like a module, a class can be used as a namespace. ;TI"EA class also inherits methods and constants from its superclass.;T@
S;	;
i;I"Defining a class;T@
o;
;[I"/Use the +class+ keyword to create a class:;T@
o;;[I"class MyClass
;TI"
  # ...
;TI"	end
;T;0o;
;[I"UIf you do not supply a superclass your new class will inherit from Object.  You ;TI"Qmay inherit from a different class using <code><</code> followed by a class ;TI"
name:;T@
o;;[I" class MySubclass < MyClass
;TI"
  # ...
;TI"	end
;T;0o;
;[	I"QThere is a special class BasicObject which is designed as a blank class and ;TI"Sincludes a minimum of built-in methods.  You can use BasicObject to create an ;TI"Oindependent inheritance structure.  See the BasicObject documentation for ;TI"further details.;T@
S;	;
i;I"Inheritance;T@
o;
;[I"AAny method defined on a class is callable from its subclass:;T@
o;;[I"
class A
;TI"
  Z = 1
;TI"
;TI"
  def z
;TI"    Z
;TI"  end
;TI"	end
;TI"
;TI"class B < A
;TI"	end
;TI"
;TI"p B.new.z #=> 1
;T;0o;
;[I"$The same is true for constants:;T@
o;;[I"
class A
;TI"
  Z = 1
;TI"	end
;TI"
;TI"class B < A
;TI"
  def z
;TI"    Z
;TI"  end
;TI"	end
;TI"
;TI"p B.new.z #=> 1
;T;0o;
;[I"QYou can override the functionality of a superclass method by redefining the ;TI"method:;T@
o;;[I"
class A
;TI"
  def m
;TI"    1
;TI"  end
;TI"	end
;TI"
;TI"class B < A
;TI"
  def m
;TI"    2
;TI"  end
;TI"	end
;TI"
;TI"p B.new.m #=> 2
;T;0o;
;[I"RIf you wish to invoke the superclass functionality from a method use +super+:;T@
o;;[I"
class A
;TI"
  def m
;TI"    1
;TI"  end
;TI"	end
;TI"
;TI"class B < A
;TI"
  def m
;TI"    2 + super
;TI"  end
;TI"	end
;TI"
;TI"p B.new.m #=> 3
;T;0o;
;[	I"MWhen used without any arguments +super+ uses the arguments given to the ;TI"Isubclass method.  To send no arguments to the superclass method use ;TI"P<code>super()</code>.  To send specific arguments to the superclass method ;TI"6provide them manually like <code>super(2)</code>.;T@
o;
;[I"L+super+ may be called as many times as you like in the subclass method.;T@
S;	;
i;I"Singleton Classes;T@
o;
;[I"UThe singleton class (also known as the metaclass or eigenclass) of an object is ;TI"La class that holds methods for only that instance.  You can access the ;TI"Osingleton class of an object using <code>class << object</code> like this:;T@
o;;[I"
class C
;TI"	end
;TI"
;TI"class << C
;TI"*  # self is the singleton class here
;TI"	end
;T;0o;
;[I"GMost frequently you'll see the singleton class accessed like this:;T@
o;;[
I"
class C
;TI"  class << self
;TI"    # ...
;TI"  end
;TI"	end
;T;0o;
;[I"UThis allows definition of methods and attributes on a class (or module) without ;TI"6needing to write <code>def self.my_method</code>.;T@
o;
;[I"TSince you can open the singleton class of any object this means that this code ;TI"block:;T@
o;;[
I"o = Object.new
;TI"
;TI"def o.my_method
;TI"
  1 + 1
;TI"	end
;T;0o;
;[I"&is equivalent to this code block:;T@
o;;[I"o = Object.new
;TI"
;TI"class << o
;TI"  def my_method
;TI"    1 + 1
;TI"  end
;TI"	end
;T;0o;
;[I";Both objects will have a +my_method+ that returns +2+.;T:
@file@:0@omit_headings_from_table_of_contents_below0