Autoloaded

If you like the Module#autoload feature of the
Ruby Core library, you may have wished for Autoloaded. It eliminates the
drudgery of handcrafting an autoload statement for each Ruby source code file
in your project. It also avoids the limitations of rigid convention-driven
facilities such as those provided by the ActiveSupport
RubyGem.

Autoloaded assumes, but does not enforce, CamelCase-to-snake_case
correspondence between the names of constants and source files. You can combine
conventions, even putting multiple autoloaded constants in a single source file.

The Autoloaded.module or Autoloaded.class method

The Autoloaded.module and Autoloaded.class method calls below invoke
Module#autoload for each source file in the
calling module’s corresponding directory. Note that these methods must receive a
block, even if it’s an empty block.

The file paths used are abbreviated, if possible, using a directory of the Ruby
load path ($:). They are also rendered without their .rb extension.

The code above is succinct, but it’s not exactly correct. The constants
MyAwesomeGem::DB, MyAwesomeGem::DB::MySQL, and others are not set up to
autoload properly because they are misspelled (case-sensitively speaking).

The only specification is like except but it has the opposite effect, namely,
that only specified constants and/or source files will be autoloaded.

You can specify only as:

A symbol or array of symbols representing constants to autoload

A string or array of strings representing source filenames to autoload

A hash of symbols and/or strings representing constants and the source
filename(s) from which to autoload them

A combination of the above

A symbol provided to except or only signifies the name of a constant, and a
string signifies the name of a source file.

You can specify except and only multiple times, and their effects are
cumulative.

The from specification

It’s recommended that you call Autoloaded.module or Autoloaded.class from
within the source file where your module or class is defined. This practice
allows Autoloaded to assume that the source files to be autoloaded are in a
directory of the same name (and in the same location) as the module’s defining
source file.

There are circumstances, however, in which you cannot rely on the computed
directory for autoloading. Perhaps the directory has a different name from the
module’s defining source file. Or perhaps you are autoloading a library that you
didn’t author. In these situations you can specify from with the path from
which source files should be autoloaded.

# somewhere_else.rb
moduleMyAwesomeGemAutoloaded.moduledo|autoloading|# The following code is not actually very useful since the installed location
# of a RubyGem varies with the operating system and user preferences. How to
# compute the path properly is outside the scope of this readme and is left
# as an exercise for the reader.
autoloading.from'/absolute/path/to/my_awesome_gem'endend

A path provided to from cannot be relative; it must start with the filesystem
root.

If you specify from multiple times in an Autoloaded block, only the last one
takes effect.

The Autoloaded.warn method

There are two circumstances under which Autoloaded by default will write
warnings to stderr:

Overriding an established autoload

Establishing an autoload for a defined constant

You can silence these warnings by passing false to Autoloaded.warn. (Passing
true turns warnings on if they are off.)

Use the block form if you want to ensure warnings get toggled on or off for a
series of statements.

# lib/my_awesome_gem/db.rb
moduleMyAwesomeGemclassDBautoload:SQLServer,'my_awesome_gem/db/MicroSoft'classOracle;endAutoloaded.warnfalsedoAutoloaded.class{}# This duplicates the 'autoload' statement and class
# definition above, but no Autoloaded warnings will
# be displayed.
end# Autoloaded warnings are turned on again automatically.
endend

How to debug autoloading

The Autoloaded.module or Autoloaded.class method returns an ordered list of
arguments it has passed to autoload.

Source filenames are relative to the from specification

You may have noticed that source filenames in the above examples are not
absolute. They are relative to the Autoloaded block’s from specification
(which I recommend that you allow to be computed for you —
see above).

Recursive autoloading not supported

Autoloaded does not perform deep autoloading of nested namespaces and
directories. This is by design.

Development

After cloning the repository, bin/setup to install dependencies. Then rake to
run the tests. You can also bin/console to get an interactive prompt that will
allow you to experiment.

To install this gem onto your local machine, bundle exec rake install. To
release a new version, update the version number in lib/autoloaded/version.rb,
and then bundle exec rake release, which will create a Git tag for the version,
push Git commits and tags, and push the .gem file to
RubyGems.org.