Kernel.require behavior

Is it correct that Kernel.require returns (1) true if the file was
successfully required (and wasn’t already loaded), (2) false if it was
successfully required (but was already loaded), or (3) throws a
LoadError if it couldn’t be successfully required.

I claim that the rdoc is misleading and should be corrected as it says:

require(string) => true or false

 Ruby tries to load the library named _string_, returning +true+ if
 successful. [snip]

which you’d implicitly assume means it returns false if NOT successful,
and it doesn’t say anything at all about a LoadError.

I’ve validated this with a test script but want to make sure there
isn’t some well-known alternate specification or understanding. I’m
researching a potential bug in the RubyGems require mechanism and
making sure I’m rock-solid on this will help.

Test script as:

#!/site/ruby/bin/ruby -w

required = (require ‘pp’)
print “#{required}\n”

required = (require ‘pp’)
print “#{required}\n”

required = (require ‘baz’)
print “#{required}\n”

and output:

[12:07am] lemur:~ > ./test.rb
./test.rb:9:in `require’: no such file to load – baz (LoadError)
from ./test.rb:9


Looks like this is the case. You might want to direct this question at
ruby-talk instead of RoR talk.