autoloaded 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c8931d8ff044c161e9a4ac8a2b5ff68dcb567f4b
-  data.tar.gz: 85a1ad725f3204618a2e08937819a1249cc88b8c
+  metadata.gz: d675263480f333ea77af9172b0350774ce55a4e3
+  data.tar.gz: 167f64690ba5c4d7c1620859c363dad0b561cd38
 SHA512:
-  metadata.gz: 648c600b35a0068b001ba3ada55454c98a29bc55bec37c458d024d05137fc6a08b2625c320b09508b63e598d47b29d682d466ec875f6a56153f3f522f6fd60b1
-  data.tar.gz: d927ce04c49c708d784763b7d563e2189e6f9b195c2261ca3ba6bdcd01d0f295bd0599bd71652eaff5671be51c8c46cd089a2c2f62e5635d664213b7b103f07f
+  metadata.gz: adade785b5342753a9561d3c0a6e1efcda22cf9ce8ef20ab13313b98532cf9db8ff9bb7ac43dd776cbbb0b29813c4b69cd711eae5278e93b14a0ac38567f71b6
+  data.tar.gz: aff0f5212fd8a289acaddc73e69275e7c1da5225be45f956f0094d3ac37e3e9393533a9802c08e2ab0eeec110e5c79e2fe599521e09c5b0782e430ec73190f7b

data/.travis.yml

@@ -2,7 +2,7 @@ language: ruby
 bundler_args: --without debug doc tooling
 rvm:
   - 2.0
-  - 2.1.0
+  - 2.1
   - ruby-head
   - jruby-head
 script: "bundle exec rake test"

data/History.md

@@ -1,5 +1,9 @@
 # Version history for the _Autoloaded_ project
 
+## <a name="v1.3.0"></a>v1.3.0, Fri 12/26/2013
+
+* Add support for relative class references with a new API
+
 ## <a name="v1.2.0"></a>v1.2.0, Fri 11/28/2013
 
 * Add support for [JRuby][JRuby] (Ruby v2.x-compatible versions)

data/README.md

@@ -5,19 +5,21 @@
 [![Travis CI build status]      ][Travis-CI-build-status]
 [![Code Climate quality report] ][Code-Climate-report]
 [![Code Climate coverage report]][Code-Climate-report]
+
 [![Gemnasium build status]      ][Gemnasium-build-status]
 [![Inch CI build status]        ][Inch-CI-build-status]
 [![RubyGems release]            ][RubyGems-release]
 
-_Autoloaded_ dynamically and flexibly loads source files in a directory when a
-corresponding constant is dereferenced. It offers several advantages over other
-autoloading facilities such as those provided by the
-[Ruby Core library][Ruby-Core-Module-autoload] and the
-[ActiveSupport][ActiveSupport-Autoload] gem:
+If you like the [_Module#autoload_][Ruby-Core-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][ActiveSupport-Autoload]
+RubyGem.
 
-* It does not require a separate `autoload` statement for each constant
-* It does not enforce `CamelCase` to `snake_case` correspondence between the
-  names of constants and source files
+_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.
 
 ## Installation
 
@@ -25,8 +27,20 @@ Install [the RubyGem][RubyGems-release].
 
     $ gem install autoloaded
 
-Or you may want to make Autoloaded a dependency of your project by using
-[Bundler][Bundler]
+Use _Autoloaded_ in your RubyGem project by making it a runtime dependency.
+
+```ruby
+# my_awesome_gem.gemspec
+
+Gem::Specification.new do |spec|
+  # ...
+  spec.add_dependency 'autoloaded', '~> 1'
+  # ...
+end
+```
+
+Or you may want to make _Autoloaded_ a dependency of your project by using
+[Bundler][Bundler].
 
 ```ruby
 # Gemfile
@@ -38,99 +52,435 @@ gem 'autoloaded', '~> 1'
 
 ## Usage
 
-Suppose you have the following source files:
+Suppose you have the following source files.
+
+    lib/
+    ├─ my_awesome_gem/
+    │  ├─ db/
+    │  │  ├─ MicroSoft.rb
+    │  │  ├─ SELF-DESTRUCT!.rb
+    │  │  ├─ mysql.rb
+    │  │  ├─ oracle.rb
+    │  │  └─ postgre_sql.rb
+    │  ├─ db.rb
+    │  └─ version.rb
+    └─ my_awesome_gem.rb
+
+### The _Autoloaded.module_ or _Autoloaded.class_ method
 
-* lib/
-  * my_awesome_gem/
-    * db/
-      * mysql.rb
-      * postgresql.rb
-      * sql_server.rb
-    * db.rb
-  * my_awesome_gem.rb
+The _Autoloaded.module_ and _Autoloaded.class_ method calls below invoke
+[_Module#autoload_][Ruby-Core-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 following statements establish autoloading — one statement per namespace:
+The file paths used are abbreviated, if possible, using a directory of the Ruby
+load path (`$:`). They are also rendered without their _.rb_ extension.
 
 ```ruby
 # lib/my_awesome_gem.rb
 module MyAwesomeGem
 
-  extend Autoloaded
+  Autoloaded.module { }
+
+  # The above is the equivalent of:
+  #
+  # autoload :Db,      'my_awesome_gem/db'
+  # autoload :Version, 'my_awesome_gem/version'
 
 end
 
 # lib/my_awesome_gem/db.rb
 module MyAwesomeGem
 
-  module DB
+  class DB
+
+    # The 'class' and 'module' methods are aliases -- use either one.
+    Autoloaded.class { }
 
-    extend Autoloaded
+    # The above is the equivalent of:
+    #
+    # autoload :MicroSoft,      'my_awesome_gem/db/MicroSoft'
+    # autoload :SELF_DESTRUCT_, 'my_awesome_gem/db/SELF-DESTRUCT!'
+    # autoload :Mysql,          'my_awesome_gem/db/mysql'
+    # autoload :Oracle,         'my_awesome_gem/db/oracle'
+    # autoload :PostgreSql,     'my_awesome_gem/db/postgre_sql'
 
   end
 
 end
 ```
 
-Note that your preferred casing of constants is accommodated automatically.
+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).
 
 ```ruby
-# Unlike Kernel#autoload and Module#autoload, Autoloaded is not clairvoyant about
-# what constants will be autoloaded.
-MyAwesomeGem::DB.constants  # => []
-
-# But like Kernel#autoload and Module#autoload, Autoloaded does tell you which
-# source files will be autoloaded. (The difference is that it may return an array
-# of potential matches instead of just one filename.)
-MyAwesomeGem::DB.autoload? :MySQL        # => 'db/mysql'
-MyAwesomeGem::DB.autoload? :PostgreSQL   # => 'db/postgresql'
-MyAwesomeGem::DB.autoload? :SQLServer    # => 'db/sql_server'
-MyAwesomeGem::DB.autoload? :Nonexistent  # => nil
-
-MyAwesomeGem::DB::MySQL
-MyAwesomeGem::DB.constants    # => [:MySQL]
-MyAwesomeGem::DB::PostgreSQL
-MyAwesomeGem::DB.constants    # => [:MySQL, :PostgreSQL]
-MyAwesomeGem::DB::SQLServer
-MyAwesomeGem::DB.constants    # => [:MySQL, :PostgreSQL, :SQLServer]
+MyAwesomeGem.autoload?          :DB  # => nil
+MyAwesomeGem.const_defined?     :DB  # => false
+MyAwesomeGem.constants.include? :DB  # => false
+
+MyAwesomeGem::DB  # Raises NameError because lib/my_awesome_gem/db.rb does not
+                  # get autoloaded!
+
+MyAwesomeGem.autoload?          :Db  # => 'my_awesome_gem/db' (a lie!)
+MyAwesomeGem.const_defined?     :Db  # => true (a lie!)
+MyAwesomeGem.constants.include? :Db  # => true (a lie!)
+
+MyAwesomeGem::Db  # Raises NameError because lib/my_awesome_gem/db.rb defines
+                  # MyAwesomeGem::DB, not MyAwesomeGem::Db!
+
+#################################################################################
+
+require 'my_awesome_gem/db'
+
+MyAwesomeGem::DB.autoload?          :MySQL  # => nil
+MyAwesomeGem::DB.const_defined?     :MySQL  # => false
+MyAwesomeGem::DB.constants.include? :MySQL  # => false
+
+MyAwesomeGem::DB::MySQL  # Raises NameError because
+                         # lib/my_awesome_gem/db/mysql.rb does not get
+                         # autoloaded!
+
+MyAwesomeGem::DB.autoload?          :Mysql  # => 'my_awesome_gem/db/mysql' (a lie!)
+MyAwesomeGem::DB.const_defined?     :Mysql  # => true (a lie!)
+MyAwesomeGem::DB.constants.include? :Mysql  # => true (a lie!)
+
+MyAwesomeGem::DB::Mysql  # Raises NameError because
+                         # lib/my_awesome_gem/db/mysql.rb defines
+                         # MyAwesomeGem::DB::MySQL, not MyAwesomeGem::DB::Mysql!
 ```
 
-_Autoloaded_ does not perform deep autoloading of nested namespaces and
-directories. This is by design.
+### The `with` specification
+
+_Autoloaded_ needs hints from you concerning unpredictable spellings,
+stylization, and organization of constant names and/or source file names. You can
+specify `with` as:
 
-### Important note
+* A symbol or array of symbols representing constants to autoload
+* A hash of symbols and strings representing constants and the source filename(s)
+  from which to autoload them
+* A combination of the above
 
-You must extend a namespace with _Autoloaded_ **from within the file in which the
-namespace is defined**. This is because _Autoloaded_ utilizes the source file
-path of the namespace to establish which directory will be autoloaded. That path
-is discoverable only via the stack trace of `extend Autoloaded`.
+A symbol provided to `with` signifies the name of a constant, and a string
+signifies the name of a source file.
 
-In the following example, autoloading of the _MyAwesomeGem_ namespace will not
-occur because the name of the source file in which the `extend` statement is
-invoked does not match the name of the namespace.
+Specifying `with` does not filter the source files; it maps the source files to
+different constants, or tweaks the names of constants.
+
+You can specify `with` multiple times, and its effects are cumulative.
 
 ```ruby
 # lib/my_awesome_gem.rb
-module MyAwesomeGem; end
+module MyAwesomeGem
+
+  Autoloaded.module do |autoloaded|
+    autoloaded.with :DB, :VERSION
+    # Or:
+    # autoloaded.with :DB
+    # autoloaded.with :VERSION
+    # Or:
+    # autoloaded.with DB: 'db', VERSION: 'version'
+    # Or:
+    # autoloaded.with DB:      'db'
+    # autoloaded.with VERSION: 'version'
+    # Or:
+    # autoloaded.with 'db' => :DB, 'version' => :VERSION
+    # Or:
+    # autoloaded.with 'db'      => :DB
+    # autoloaded.with 'version' => :VERSION
+  end
+
+  # The above is the equivalent of:
+  #
+  # autoload :DB,      'my_awesome_gem/db'
+  # autoload :VERSION, 'my_awesome_gem/version'
+
+end
+
+# lib/my_awesome_gem/db.rb
+module MyAwesomeGem
+
+  class DB
+
+    Autoloaded.class do |autoloaded|
+      autoloaded.with :MySQL, :PostgreSQL, [:Access, :SQLServer] => 'MicroSoft'
+      # Or:
+      # autoloaded.with :MySQL,
+      #                 :PostgreSQL,
+      #                 Access:    'MicroSoft',
+      #                 SQLServer: 'MicroSoft'
+      # Or:
+      # autoloaded.with :MySQL, :PostgreSQL, 'MicroSoft' => [:Access, :SQLServer]
+      # Or:
+      # autoloaded.with :MySQL,
+      #                 :PostgreSQL,
+      #                 'MicroSoft' => :Access,
+      #                 'MicroSoft' => :SQLServer
+      # Or ...
+    end
+
+    # The above is the equivalent of:
+    #
+    # autoload :Access,         'my_awesome_gem/db/MicroSoft'
+    # autoload :SQLServer,      'my_awesome_gem/db/MicroSoft'
+    # autoload :SELF_DESTRUCT_, 'my_awesome_gem/db/SELF-DESTRUCT!'
+    # autoload :MySQL,          'my_awesome_gem/db/mysql'
+    # autoload :Oracle,         'my_awesome_gem/db/oracle'
+    # autoload :PostgreSQL,     'my_awesome_gem/db/postgre_sql'
+
+  end
+
+end
+```
+
+Now you’re autoloading all the constants you want to be autoloading.
+
+```ruby
+MyAwesomeGem.autoload?          :DB  # => 'my_awesome_gem/db'
+MyAwesomeGem.const_defined?     :DB  # => true
+MyAwesomeGem.constants.include? :DB  # => true
+
+MyAwesomeGem::DB  # => MyAwesomeGem::DB
+
+MyAwesomeGem.autoload?          :Db  # => nil
+MyAwesomeGem.const_defined?     :Db  # => false
+MyAwesomeGem.constants.include? :Db  # => false
+
+MyAwesomeGem::Db  # Raises NameError as expected.
+
+#################################################################################
+
+MyAwesomeGem::DB.autoload?          :MySQL  # => 'my_awesome_gem/db/mysql'
+MyAwesomeGem::DB.const_defined?     :MySQL  # => true
+MyAwesomeGem::DB.constants.include? :MySQL  # => true
+
+MyAwesomeGem::DB::MySQL  # => MyAwesomeGem::DB::MySQL
+
+MyAwesomeGem::DB.autoload?          :Mysql  # => nil
+MyAwesomeGem::DB.const_defined?     :Mysql  # => false
+MyAwesomeGem::DB.constants.include? :Mysql  # => false
+
+MyAwesomeGem::DB::Mysql  # Raises NameError as expected.
+```
+
+### The `except` and `only` specifications
+
+What about source files you **don’t** want to be autoloaded?
+
+```ruby
+MyAwesomeGem::DB::SELF_DESTRUCT_  # Loading this file does something bad, so
+                                  # let's not.
+```
+
+If you really want to avoid loading *lib/my_awesome_gem/db/SELF-DESTRUCT!.rb*, so
+much so that you don’t want an `autoload` statement made for it, specify
+`except`.
+
+```ruby
+# lib/my_awesome_gem/db.rb
+
+module MyAwesomeGem
+
+  class DB
+
+    Autoloaded.class do |autoloaded|
+      autoloaded.with :MySQL, :PostgreSQL, [:Access, :SQLServer] => 'MicroSoft'
+
+      autoloaded.except 'SELF-DESTRUCT!'
+      # Or:
+      # autoloaded.except :SELF_DESTRUCT_
+      # Or ...
+    end
+
+    # The above is the equivalent of:
+    #
+    # autoload :Access,     'my_awesome_gem/db/MicroSoft'
+    # autoload :SQLServer,  'my_awesome_gem/db/MicroSoft'
+    # autoload :MySQL,      'my_awesome_gem/db/mysql'
+    # autoload :Oracle,     'my_awesome_gem/db/oracle'
+    # autoload :PostgreSQL, 'my_awesome_gem/db/postgre_sql'
+
+  end
+
+end
+```
 
+```ruby
+MyAwesomeGem::DB.autoload?          :SELF_DESTRUCT_  # => nil
+MyAwesomeGem::DB.const_defined?     :SELF_DESTRUCT_  # => false
+MyAwesomeGem::DB.constants.include? :SELF_DESTRUCT_  # => false
+
+MyAwesomeGem::DB::SELF_DESTRUCT_  # Raises NameError as expected.
+```
+
+You can specify `except` as:
+
+* A symbol or array of symbols representing constants to avoid autoloading
+* A string or array of strings representing source filenames to avoid autoloading
+* A hash of symbols and/or strings representing constants and/or source filenames
+  to avoid autoloading
+* A combination of the above
+
+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.
+
+```ruby
+# somewhere_else.rb
+
+module MyAwesomeGem
+
+  Autoloaded.module do |autoloaded|
+    # 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.
+    autoloaded.from '/absolute/path/to/my_awesome_gem'
+  end
+
+end
+```
+
+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.)
+
+```ruby
 # lib/my_awesome_gem/db.rb
+
 module MyAwesomeGem
 
-  # WRONG!
-  extend Autoloaded
+  class DB
+
+    Autoloaded.warn false  # Turn off Autoloaded warnings.
 
-  module DB
+    autoload :SQLServer, 'my_awesome_gem/db/MicroSoft'
 
-    extend Autoloaded
+    class Oracle; end
+
+    Autoloaded.class { }  # This duplicates the 'autoload' statement and class
+                          # definition above, but no Autoloaded warnings will be
+                          # displayed.
+
+    Autoloaded.warn true  # Turn on Autoloaded warnings again.
 
   end
 
 end
+```
+
+Use the block form if you want to ensure warnings get toggled on or off for a
+series of statements.
 
-# some_other_file.rb
-require 'my_awesome_gem'
-MyAwesomeGem::DB  # NameError is raised!
+```ruby
+# lib/my_awesome_gem/db.rb
+
+module MyAwesomeGem
+
+  class DB
+
+    autoload :SQLServer, 'my_awesome_gem/db/MicroSoft'
+
+    class Oracle; end
+
+    Autoloaded.warn false do
+      Autoloaded.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.
+
+  end
+
+end
 ```
 
+### How to debug autoloading
+
+The _Autoloaded.module_ or _Autoloaded.class_ method returns an ordered list of
+arguments it has passed to `autoload`.
+
+```ruby
+# lib/my_awesome_gem/db.rb
+
+module MyAwesomeGem
+
+  class DB
+
+    results = Autoloaded.class do |autoloaded|
+      autoloaded.with   :MySQL, :PostgreSQL, [:Access, :SQLServer] => 'MicroSoft'
+      autoloaded.except 'SELF-DESTRUCT!'
+    end
+    STDOUT.puts results.inspect  # See output below.
+
+  end
+
+end
+
+# [[:Access,     'my_awesome_gem/db/MicroSoft'  ],
+#  [:SQLServer,  'my_awesome_gem/db/MicroSoft'  ],
+#  [:MySQL,      'my_awesome_gem/db/mysql'      ],
+#  [:Oracle,     'my_awesome_gem/db/oracle'     ],
+#  [:PostgreSQL, 'my_awesome_gem/db/postgre_sql']]
+```
+
+You can also hook [_Module#autoload_][Ruby-Core-Module-autoload] and
+[_Kernel#autoload_][Ruby-Core-Kernel-autoload] via monkeypatching or other means
+in order to see what’s happening.
+
+### 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](#the-from-specification)).
+
+### Recursive autoloading not supported
+
+_Autoloaded_ does not perform deep autoloading of nested namespaces and
+directories. This is by design.
+
 ## Contributing
 
 1. [Fork][fork-Autoloaded] the official repository.
@@ -160,6 +510,7 @@ Released under the [MIT License][MIT-License].
 [Ruby-Core-Module-autoload]:   http://ruby-doc.org/core/Module.html#method-i-autoload         "‘Module#autoload’ method in the Ruby Core Library"
 [ActiveSupport-Autoload]:      http://api.rubyonrails.org/classes/ActiveSupport/Autoload.html "‘ActiveSupport::Autoload’ module in the Rails API"
 [Bundler]:                     http://bundler.io
+[Ruby-Core-Kernel-autoload]:   http://ruby-doc.org/core/Kernel.html#method-i-autoload         "‘Kernel#autoload’ method in the Ruby Core Library"
 [fork-Autoloaded]:             https://github.com/njonsson/autoloaded/fork                    "Fork the official repository of Autoloaded"
 [compare-Autoloaded-branches]: https://github.com/njonsson/autoloaded/compare                 "Compare branches of Autoloaded repositories"
 [MIT-License]:                 http://github.com/njonsson/autoloaded/blob/master/License.md   "MIT License claim for Autoloaded"