The "Require" Method in Ruby

In order to create reusable components, ones that can be easily used in other programs, a programming language must have some way of smoothly importing that code at run-time. In Ruby, the require method is used to load another file and execute all its statements. This serves to import all class and method definitions in the file. In addition to simply executing all of the statements in the file, the require method also keeps track of which files have been previously required and, thus, will not require a file twice.

Using the 'require' Method

The require method takes the name of the file to require, as a string, as a single argument. This can either be a path to the file, such as ./lib/some_library.rb or a shortened name, such as some_library. If the argument is a path and complete filename, the require method will look there for the file. However, if the argument is a shortened name, the require method will search through a number of pre-defined directories on your system for that file. Using the shortened name is the most common way of using the require method.

The following example demonstrates how to use the require statement. The file test_library.rb is in the first code block. This file prints a message and defines a new class. The second code block is the file test_program.rb. This file loads the test_library.rb file using the require method and creates a new TestClass object.

puts "test_library included"
class TestClass
def initialize
puts "TestClass object created"
end
end

#!/usr/bin/env ruby
require 'test_library.rb'
t = TestClass.new

Avoid Name Clashes

When writing reusable components, it's best not to declare many variables in the global scope outside any classes or methods or by using the $ prefix. This is to prevent something called "namespace pollution." If you declare too many names, another program or library might declare the same name and cause a name clash. When two completely unrelated libraries start changing each other's variables accidentally, things will break-- seemingly at random. This is a very difficult bug to track down and it's best just to avoid it.

To avoid name clashes, you can enclose everything in your library inside of a module statement. This will require people to refer to your classes and method by a fully qualified name such as MyLibrary::my_method, but it's worth it since name clashes generally won't occur. For people who want to have all of your class and method names in the global scope, they can do that using the include statement.

The following example repeats the previous example but encloses everything in a MyLibrary module. Two versions of my_program.rb are given; one that uses the include statement and one that does not.

puts "test_library included"
module MyLibrary
class TestClass
def initialize
puts "TestClass object created"
end
end
end

#!/usr/bin/env ruby
require 'test_library2.rb'
t = MyLibrary::TestClass.new

#!/usr/bin/env ruby
require 'test_library2.rb'
include MyLibrary
t = TestClass.new

Avoid Absolute Paths

Because reusable components often get moved around, it's also best not to use absolute paths in your require calls. An absolute path is a path like /home/user/code/library.rb. You'll notice that the file must be in that exact location in order to work. If the script is ever moved or your home directory ever changes, that require statement will stop working.

Instead of absolute paths, it's often common to create a ./lib directory in your Ruby program's directory. The ./lib directory is added to the $LOAD_PATH variable which stores the directories in which the require method searches for Ruby files. After that, if the file my_library.rb is stored in the lib directory, it can be loaded into your program with a simple require 'my_library' statement.

The following example is the same as the previous test_program.rb examples. However, it assumes the test_library.rb file is stored in the ./lib directory and loads it using the method described above.

#!/usr/bin/env ruby
$LOAD_PATH << './lib'
require 'test_library.rb'
t = TestClass.new