liveBook · Manning

Require

As explained in The Well-Grounded Rubyist, Fourth Edition

Ruby's Kernel method that loads a feature once and records it so subsequent calls with the same feature do not reload it.

Suppose `URI.parse` raises `NameError` in irb. Run `require "uri"`, then try again: the URI library is now available. `require` loads a feature at runtime, making the classes and methods it provides available to your program. section 1.3.3

A feature is more abstract than a filename. You normally omit the extension, as in `require "./loadee"`. That lets the same call style load Ruby files and compiled extensions. `require` also accepts a fully qualified path and searches the load path for features named without one. section 1.3.3 section 1.3.2

Unlike `load`, `require` does not reload a file when called again with the same argument: Ruby keeps track of what it has already required. Use `load` when you deliberately want to execute a file again, such as while editing it in an irb session; use `require` for everyday library loading. section 1.3.3 section 1.3.2

>> uri = URI.parse("https://example.com/foo?bar=baz") 1
(irb):1:in '<main>': uninitialized constant URI (NameError)
from <internal:kernel>:168:in 'Kernel#loop' 
from /Users/jleo3/.gem/ruby/4.0.1/gems/irb-1.16.0/exe/irb:9:
➥in '<top (required)>' 
from /Users/jleo3/.gem/ruby/4.0.1/bin/irb:25:in 'Kernel#load' 
from /Users/jleo3/.gem/ruby/4.0.1/bin/irb:25:in '' 
from /Users/jleo3/.rubies/ruby-4.0.1/lib/ruby/4.0.0/rubygems.rb:303:
➥ in 'Gem.activate_and_load_bin_path'
from /Users/jleo3/.rubies/ruby-4.0.1/bin/irb:25:in '<main>'
>> require "uri"                  2
=> true 
>> uri = URI.parse("https://example.com/foo?bar=baz") 
=> #<URI::HTTPS https://example.com/foo?bar=baz> 

The irb transcript shows `URI.parse` failing before `require "uri"` and succeeding afterward. section 1.3.3

The same method loads installed gems. For example, after installing `colorize`, a program can call `require "colorize"` before using its String color methods. Installation and loading are separate steps; someone running the program also needs the gem installed. section 1.4.4

How The Well-Grounded Rubyist, Fourth Edition covers it

How deep it goes
Explains feature names, omitted extensions, path lookup, and repeated calls through examples; stops short of a detailed account of Ruby's loading internals.
Examples
Uses an irb failure before `require "uri"`, a two-file loading example, and a program that requires `colorize`.
What it assumes
Assumes basic Ruby files and method calls while introducing multi-file programs, feature names, and load-path lookup through examples.
What you can do after
Apply it via Ruby's `require` to load a library once, choosing `load` instead when repeated execution is wanted.
How it connects
Contrasts `load` and connects `require` to the load path, standard library, compiled extensions, and RubyGems.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of The Well-Grounded Rubyist, Fourth Edition. The section links point to the parts of the book it draws on.