Including Modules from Files

So far, I’ve mixed in modules that have been defined within a single source file. Often it is more useful to define modules in separate files and mix them in as needed. The first thing you have to do in order to use code from another file is to load that file using the require method, like this:

require_module.rb

require( "./testmod.rb" )

Optionally, you may omit the file extension:

require( "./testmod" )  # this works too

If no path is given, the required file must be in the current directory, on the search path, or in a folder listed in the predefined array variable $:. You can add a directory to this array variable using the usual array-append method, <<, in this way:

$: << "C:/mydir"

Note

The global variable, $: (a dollar sign and a colon), contains an array of strings representing the directories that Ruby searches when looking for a loaded or required file.

There is one documented difference in the way require works in Ruby 1.8 and Ruby 1.9. In Ruby 1.8, the filename is not converted to an absolute path, so require "a"; require "./a" will load a.rb twice. In Ruby 1.9, the filename is converted to an absolute path, so require "a"; require "./a" will not load a.rb twice.

In addition, I’ve found that require may, in at least some versions of Ruby 1.9, fail to load a file from the current directory if you use an unqualified filename as in require("testmod"). In such cases, a LoadError is thrown. This occurs when the array of searchable directories stored in the global variable, $:, does not contain the current directory. You can verify whether this is the case by running this code:

search_dirs.rb

puts( $: )

The search paths will be displayed one per line. There should be a line that displays a single dot (.) representing the current directory. If that dot is missing, then files in the current directory are not on the search path and cannot be loaded using an unqualified filename.

To ensure that the file is loaded, I have preceded the filename with a dot to specify the current directory, and this now succeeds: require( "./testmod" ). Alternatively, you could use the require_relative method, though this is new to Ruby 1.9 and cannot be used in earlier versions:

require_relative( "testmod.rb" )    # Ruby 1.9 only

Alternatively, if $: doesn’t contain the current directory, you could add it. Once this is done, require will work with the unqualified names of files in the current directory:

$: << "."              # add current directory to array of search paths
require( "testmod.rb" )

The require method returns a true value if the specified file is successfully loaded; otherwise, it returns false. If the file does not exist, it returns a LoadError. If in doubt, you can simply display the result.

puts(require( "testmod.rb" )) #=> true, false or LoadError

Any code that would normally be executed when a file is run will be executed when that file is required. So, if the file, testmod.rb, contains this code:

testmod.rb

def sing
    puts( "Tra-la-la-la-la....")
end

puts( "module loaded")
sing

when the require_module.rb program is run and it requires testmod.rb, this will be displayed:

module loaded
Tra-la-la-la-la....

When a module is declared in the required file, it can be mixed in:

require_module2.rb
require( "testmod.rb")
include MyModule       #mix in MyModule declared in testmod.rb

Ruby also lets you load a file using the load method. In most respects, require and load can be regarded as interchangeable. But there are a few subtle differences. In particular, load can take an optional second argument, which, if this is true, loads and executes the code as an unnamed or anonymous module:

load( "testmod.rb", true)

When the second argument is true, the file loaded does not introduce the new namespace into the main program, and you will not have access to the module(s) in the loaded file. In that case, the Module methods, constants, and instance methods will not be available to your code:

load_module.rb

load( "testmod.rb", true)

puts( MyModule.greet )   #=>Error:uninitialized constant Object::MyModule
puts(MyModule::GOODMOOD) #=>Error:uninitialized constant Object::MyModule
include MyModule         #=>Error:uninitialized constant Object::MyModule
puts( greet )            #=>Error:undefined local variable or method 'greet'

When the second argument to load is false or when there is no second argument, however, you will have access to modules in the loaded file:

load_module_false.rb

load( "testmod.rb", false)

puts( MyModule.greet )   #=> I'm grumpy. How are you?
puts(MyModule::GOODMOOD) #=> happy
include MyModule         #=> [success]
puts( greet )            #=> I'm happy. How are you?

Note that you must enter the full filename with load (testmod minus the .rb extension will not suffice). Another difference between load and require is that require loads a file once only (even if your code requires that file many times), whereas load causes the specified file to be reloaded each time load is called. Let’s suppose you have a file, test.rb, containing this code:

test.rb

MyConst = 1
if @a == nil then
    @a = 1
else
    @a += MyConst
end

puts @a

You now require this file three times:

require_again.rb

require "./test"
require "./test"
require "./test"

This will be the output:

1

But if you load the file three times . . .

load_again.rb

load "test.rb"
load "test.rb"
load "test.rb"

then this will be the output:

1
./test.rb:1: warning: already initialized constant MyConst
2
./test.rb:1: warning: already initialized constant MyConst
3

Digging Deeper

How exactly is a module related to a class? Here we answer that question, examine some important Ruby modules and find out how to use modules to extend objects.

Modules and Classes

In this chapter, I’ve discussed the behavior of a module. Let’s now find out what a module really is. It turns out that, as with most other things in Ruby, a module is an object. Each named module is, in fact, an instance of the Module class:

module_inst.rb

module MyMod
end

puts( MyMod.class )            #=> Module

You cannot create descendants of named modules, so this is not allowed:

module MyMod
end

module MyOtherMod < MyMod      # You can't do this!
end

However, as with other classes, it is permissible to create a descendant of the Module class:

class X < Module               # But you can do this
end

Indeed, the Class class is itself a descendant of the Module class. It inherits the behavior of Module and adds some important new behavior, notably the ability to create objects. You can verify that Module is the superclass of Class by running the modules_classes.rb program, which shows this hierarchy:

modules_classes.rb

Class
Module            #=> is the superclass of Class
Object            #=> is the superclass of Module
BasicObject       #=> (in Ruby 1.9) is the superclass of Module

Predefined Modules

The following modules are built into the Ruby interpreter: Comparable, Enumerable, FileTest, GC, Kernel, Math, ObjectSpace, Precision, Process, and Signal.

Comparable is a mixin module that permits the including class to implement comparison operators. The including class must define the <=> operator, which compares the receiver against another object, returning −1, 0, or +1 depending on whether the receiver is less than, equal to, or greater than the other object.

  • Comparable uses <=> to implement the conventional comparison operators (<, <=, ==, >=, and >) and the method between?.

  • Enumerable is a mixin module for enumeration. The including class must provide the method each.

  • FileTest is a module containing file test functions; its methods can also be accessed from the File class.

  • The GC module provides an interface to Ruby’s mark and sweep garbage collection mechanism. Some of the underlying methods are also available via the ObjectSpace module.

  • Kernel is a module included by the Object class; it defines Ruby’s “built-in” methods.

  • Math is a module containing module functions for basic trigonometric and transcendental functions. It has both “instance methods” and module methods of the same definitions and names.

  • ObjectSpace is a module that contains routines that interact with the garbage collection facility and allow you to traverse all living objects with an iterator.

  • Precision is a mixin for concrete numeric classes with precision. Here, “precision” means the fineness of approximation of a real number, so this module should not be included into anything that is not a subset of Real (so it should not be included in classes such as Complex or Matrix).

  • Process is the module for manipulating processes. All its methods are module methods.

  • Signal is the module for handling signals sent to running processes. The list of available signal names and their interpretation is system dependent.

The following is a brief overview of three of the most commonly used Ruby modules.

Kernel

The most important of the predefined modules is Kernel, which provides many of the “standard” Ruby methods such as gets, puts, print, and require. In common with much of the Ruby class library, Kernel is written in the C language. Although Kernel is, in fact, “built into” the Ruby interpreter, conceptually it can be regarded as a mixed-in module that, just like a normal Ruby mixin, makes its methods directly available to any class that requires it. Since it is mixed into the Object class from which all other Ruby classes descend, the methods of Kernel are universally accessible.

Math

The Math module’s methods are provided as both “module” and “instance” methods and can therefore be accessed either by mixing Math into a class or by accessing the module methods “from the outside” by using the module name, a dot, and the method name; you can access constants using a double colon:

math.rb

puts( Math.sqrt(144) )  #=> 12.0
puts( Math::PI )        #=> 3.141592653589793

Comparable

The Comparable module provides the neat ability to define your own comparison “operators” as in <, <=, ==, >=, and > (strictly speaking, these are methods, but they can be used like the comparison operators in other languages). This is done by mixing the module into your class and defining the <=> method. You can then specify the criteria for comparing some value from the current object with some other value. You might, for example, compare two integers, the length of two strings, or some more eccentric value such as the position of a string in an array. I’ve opted for this eccentric type of comparison in my example program, compare.rb. This uses the index of a string in an array of mythical beings in order to compare the name of one being with that of another. A low index such as hobbit at index 0 is considered to be “less than” a high index such as dragon at index 6:

compare.rb

class Being
       include Comparable

       BEINGS = ['hobbit','dwarf','elf','orc','giant','oliphant','dragon']

       attr_accessor :name

       def <=> (anOtherName)
               BEINGS.index(@name)<=>BEINGS.index(anOtherName.name)
       end

       def initialize( aName )
               @name = aName
       end

end

elf =  Being.new('elf')
orc = Being.new('orc')
giant = Being.new('giant')

puts( elf < orc )     #=> true
puts( elf > giant )   #=> false

Scope Resolution

As with classes, you can use the double-colon scope resolution operator to access constants (including classes and other modules) declared inside modules. For example, let’s suppose you have nested modules and classes, like this:

module OuterMod
    moduleInnerMod
        class Class1
        end
    end
end

You could use the :: operator to access Class1, like this:

OuterMod::InnerMod::Class1

Note

See Chapter 2 for an introduction to scope resolution of constants within classes.

Each module and class has its own scope, which means that a single constant name might be used in different scopes. This being so, you could use the :: operator to specify a constant within a precise scope:

Scope1::Scope2::Scope3        #...etc

If you use this operator at the very start of the constant name, this has the effect of breaking out of the current scope and accessing the “top-level” scope:

::ACONST                      # refers to ACONST at top-level scope

The following program provides some examples of the scope operator:

scope_resolution.rb

ACONST = "hello"                         # This is a top-level constant

module OuterMod
   module InnerMod
      ACONST=10                          # OuterMod::InnerMod::ACONST
      class Class1
         class Class2
            module XYZ
               class ABC
                  ACONST=100             # Deeply nested ACONST
                  def xyz
                     puts( ::ACONST )    # <= This refers to top-level ACONST
                  end
               end
            end
         end
      end
   end
end

puts(OuterMod::InnerMod::ACONST)                             #=> 10
puts(OuterMod::InnerMod::Class1::Class2::XYZ::ABC::ACONST)   #=> 100
ob = OuterMod::InnerMod::Class1::Class2::XYZ::ABC.new
ob.xyz                                                       #=> hello

Module Functions

If you want a function to be available both as an instance and as a module method, you can use the module_function method with a symbol matching the name of an instance method, like this:

module_func.rb

module MyModule
    def sayHi
        return "hi!"
    end

    def sayGoodbye
        return "Goodbye"
  end

    module_function :sayHi
end

The sayHi method may now be mixed into a class and used as an instance method:

class MyClass
    include MyModule
        def speak
            puts(sayHi)
            puts(sayGoodbye)
        end
end

It may be used as a module method, using dot notation:

ob = MyClass.new
ob.speak                   #=> hi!
Goodbye
puts(MyModule.sayHi)       #=> hi!

Since the sayGoodbye method here is not a module function, it cannot be used in this way:

puts(MyModule.sayGoodbye)  #=> Error: undefined method

Ruby uses module_function in some of its standard modules such as Math (in the Ruby library file, complex.rb) to create “matching pairs” of module and instance methods.

Extending Objects

You can add the methods of a module to a specific object (rather than to an entire class) using the extend method, like this:

extend.rb

module A
    def method_a
        puts( 'hello from a' )
    end
end

class MyClass
    def mymethod
        puts( 'hello from mymethod of class MyClass' )
    end
end

ob = MyClass.new
ob.mymethod       #=> hello from mymethod of class MyClass
ob.extend(A)

Now that the object ob is extended with the module A, it can access that module’s instance method, method_a:

ob.method_a      #=> hello from a

You can, in fact, extend an object with several modules all at once. Here, the modules B and C extend the object, ob:

module B
    def method_b
        puts( 'hello from b' )
    end
end

module C
    def mymethod
        puts( 'hello from mymethod of module C' )
    end
end

ob.extend(B, C)
ob.method_b       #=> hello from b
ob.mymethod       #=> hello from mymethod of module C

When an object is extended with a module containing a method with the same name as a method in the object’s class, the method from the module replaces the method from the class. So, when ob is extended with C and you call ob.mymethod, the string “hello from mymethod of module C” will be displayed rather than the “hello from mymethod of class MyClass” that was displayed before ob was extended with module C.

Freezing Objects

You can explicitly prevent an object from being extended it by “freezing” it using the freeze method:

ob.freeze

Any attempt to extend this object further would result in a runtime error:

module D
    def method_d
        puts( 'hello from d' )
    end
end
ob.extend( D ) #=> Error: can't modify frozen object (RuntimeError)

To avoid such an error, you can use the frozen? method to test whether an object has been frozen:

if !(ob.frozen?)
    ob.extend( D )
    ob.method_d
else
    puts( "Can't extend a frozen object" )
end
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.145.52.188