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 <=> 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 :: provided the outer ;TI".modules (or classes) are already defined:;T@ o;;[I"%module Outer::Inner::GrandChild ;TI" end ;T;0o; ;[I"Outer::Inner 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 A::Z 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 :: to define A::B without ;TI"Unesting 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"%:: 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"VWhen 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 == 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 < 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"Psuper(). To send specific arguments to the superclass method ;TI"6provide them manually like super(2).;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 class << object 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 def self.my_method.;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