autoloaded 1.2.0 → 1.3.0

data/autoloaded.gemspec

@@ -3,27 +3,32 @@
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
-require 'autoloaded/version'
+require 'autoloaded'
 
 Gem::Specification.new do |spec|
   spec.name          = 'autoloaded'
   spec.version       = Autoloaded::VERSION
   spec.authors       = ['Nils Jonsson']
   spec.email         = ['autoloaded@nilsjonsson.com']
-  spec.summary       = <<-end_summary.gsub(/^\s+/, '').gsub("\n", ' ')
-                         Dynamically and flexibly loads source files in a
-                         directory when a corresponding constant is dereferenced.
+  spec.summary       = <<-end_summary.chomp.gsub(/^\s+/, '').gsub("\n", ' ')
+                         Eliminates the drudgery of handcrafting a Ruby Core
+                         library `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.
                        end_summary
-  spec.description   = spec.summary +
-                       ' '          +
-                       <<-end_description.gsub(/^\s+/, '').gsub(/\n(?=\S)/, ' ').chomp
-                         Offers several advantages over other autoloading
-                         facilities such as those provided by the Ruby Core
-                         library and the ActiveSupport gem: (a) it does not
-                         require a separate `autoload` statement for each
-                         constant, and (b) it does not enforce CamelCase to
-                         snake_case correspondence between the names of constants
-                         and source files.
+  spec.description   = <<-end_description.chomp.gsub(/^\s+/, '').gsub("\n", ' ')
+                         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.
                        end_description
   spec.homepage      = 'http://njonsson.github.io/autoloaded'
   spec.license       = 'MIT'

data/lib/autoloaded.rb

@@ -1,100 +1,25 @@
-# coding: utf-8
-#
-# When used to extend a module, the _Autoloaded_ module dynamically loads
-# constants into that module from source files contained in its filesystem path.
-#
-# @note 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`.
-#
-# Suppose you have the following source files:
-#
-# * lib/
-#   * my_awesome_gem/
-#     * db/
-#       * mysql.rb
-#       * postgresql.rb
-#       * sql_server.rb
-#     * db.rb
-#   * my_awesome_gem.rb
-#
-# The following statements establish autoloading — one statement per namespace:
-#
-#   # lib/my_awesome_gem.rb
-#   module MyAwesomeGem
-#
-#     extend Autoloaded
-#
-#   end
-#
-#   # lib/my_awesome_gem/db.rb
-#   module MyAwesomeGem
-#
-#     module DB
-#
-#       extend Autoloaded
-#
-#     end
-#
-#   end
-#
-# Note that your preferred casing of constants is accommodated automatically.
-#
-#   # 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]
-#
-# _Autoloaded_ does not perform deep autoloading of nested namespaces and
-# directories. This is by design.
-#
-# 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.
-#
-#   # lib/my_awesome_gem.rb
-#   module MyAwesomeGem; end
-#
-#   # lib/my_awesome_gem/db.rb
-#   module MyAwesomeGem
-#
-#     # WRONG!
-#     extend Autoloaded
-#
-#     module DB
-#
-#       extend Autoloaded
-#
-#     end
-#
-#   end
-#
-#   # some_other_file.rb
-#   require 'my_awesome_gem'
-#   MyAwesomeGem::DB  # NameError is raised!
+# Eliminates the drudgery of handcrafting a Ruby Core library +autoload+
+# statement for each Ruby source code file in your project.
 #
+# @since 0.0.1
 module Autoloaded
 
-  autoload :Constant, 'autoloaded/constant'
-  autoload :Refine,   'autoloaded/refine'
-  autoload :VERSION,  'autoloaded/version'
+  autoload :Autoloader,          'autoloaded/autoloader'
+  autoload :Constant,            'autoloaded/constant'
+  autoload :Deprecation,         'autoloaded/deprecation'
+  autoload :Inflection,          'autoloaded/inflection'
+  autoload :LoadPathedDirectory, 'autoloaded/load_pathed_directory'
+  autoload :Refine,              'autoloaded/refine'
+  autoload :Specification,       'autoloaded/specification'
+  autoload :Specifications,      'autoloaded/specifications'
+  autoload :VERSION,             'autoloaded/version'
+  autoload :Warning,             'autoloaded/warning'
 
   def self.extended(other_module)
     caller_file_path = caller_locations.first.absolute_path
+    Deprecation.deprecate deprecated_usage: "extend #{name}",
+                          sanctioned_usage: "#{name}.module { }",
+                          source_filename:  caller_file_path
     dir_path = "#{::File.dirname caller_file_path}/#{::File.basename caller_file_path, '.rb'}"
     other_module.module_eval <<-end_module_eval, __FILE__, __LINE__
       def self.autoload?(symbol)
@@ -127,4 +52,92 @@ module Autoloaded
     end_module_eval
   end
 
+  # @!method self.module
+  #   Autoloads constants that match files in the source directory.
+  #
+  #   @yield [Autoloader] accepts options for regulating autoloading
+  #
+  #   @return [Array of Array] the arguments passed to each +autoload+ statement
+  #                            made
+  #
+  #   @raise [LocalJumpError] no block is given
+  #
+  #   @since 1.3
+  #
+  #   @example Autoloading a namespace
+  #     # lib/my_awesome_gem/db.rb
+  #
+  #     module MyAwesomeGem
+  #
+  #       Autoloaded.module { }
+  #
+  #     end
+  #
+  #   @example Autoloading with optional specifications
+  #     # 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']]
+  def self.module(&block)
+    raise(::LocalJumpError, 'no block given (yield)') unless block
+
+    yield(autoloader = Autoloader.new(block.binding))
+    autoloader.autoload!
+  end
+
+  # Enables or disables warning messages depending on the specified _enabling_
+  # argument.
+  #
+  # @param [Object] enabling disables warnings if +nil+ or +false+
+  #
+  # @yield if a block is given, the value of _#warn?_ is reset after the block is
+  #        called
+  #
+  # @return if a block is given, the result of calling the block
+  # @return [Autoloaded] if a block is not given, _Autoloaded_ (_Module_)
+  #
+  # @since 1.3
+  #
+  # @see .warn?
+  def self.warn(enabling, &block)
+    result = Warning.enable(enabling, &block)
+
+    block ? result : self
+  end
+
+  # Indicates whether warning messages are enabled or disabled.
+  #
+  # @return [true] if warning messages are enabled
+  # @return [false] if warning messages are disabled
+  #
+  # @since 1.3
+  #
+  # @see .warn
+  def self.warn?
+    Warning.enabled?
+  end
+
+  class << self
+
+    alias_method :class, :module
+
+  end
+
 end

data/lib/autoloaded/autoloader.rb

@@ -0,0 +1,260 @@
+module Autoloaded
+
+  # Autoloads files in a source directory.
+  #
+  # @since 1.3
+  class Autoloader
+
+    # The source code context in which autoloading is to occur.
+    #
+    # @return [Binding] the source code context in which autoloading is to occur.
+    #
+    # @see #autoload!
+    #
+    # @api private
+    attr_reader :host_binding
+
+    # Constructs a new _Autoloader_ with the specified _host_binding_.
+    #
+    # @param [Binding] host_binding a value for _#host_binding_
+    #
+    # @raise [ArgumentError] _host_binding_ is +nil+
+    #
+    # @api private
+    def initialize(host_binding)
+      raise(::ArgumentError, "can't be nil") if host_binding.nil?
+
+      @host_binding = host_binding
+      @specifications = Specifications.new
+    end
+
+    # Issues +autoload+ statements for source files found in _#from_. The
+    # constants are renamed by _#with_ and _#only_. The source files are filtered
+    # by _#except_ and _#only_.
+    #
+    # @return [Array of Array] the arguments passed to each +autoload+ statement
+    #                          made
+    #
+    # @see http://ruby-doc.org/core/Module.html#method-i-autoload Module#autoload
+    # @see http://ruby-doc.org/core/Kernel.html#method-i-autoload Kernel#autoload
+    # @see #from
+    # @see #except
+    # @see #only
+    # @see #with
+    #
+    # @api private
+    def autoload!
+      result = []
+      from_load_pathed_directory.each_source_filename do |source_filename|
+        source_basename = ::File.basename(source_filename)
+        next if specifications.except.any? { |spec| spec.match source_basename }
+
+        unless specifications.only.empty? ||
+               specifications.only.any? { |spec| spec.match source_basename }
+          next
+        end
+
+        first_match = (specifications.with + specifications.only).inject(nil) do |match, spec|
+          match || spec.match(source_basename)
+        end
+        constant_names = Array(first_match ||
+                               Inflection.to_constant_name(source_basename))
+        existing_source_filenames = constant_names.collect do |const|
+          existing_autoload? const
+        end
+        if existing_source_filenames.all? { |file| file == source_filename }
+          next
+        end
+
+        existing_source_filenames.zip(constant_names).each do |file, const|
+          if file
+            Warning.changing_autoload constant_name:        constant_full_name(const),
+                                      old_source_filename:  file,
+                                      new_source_filename:  source_filename,
+                                      host_source_location: host_source_location
+          end
+        end
+
+        if existing_source_filenames.compact.empty?
+          constant_names.each do |const|
+            next unless existing_constant?(const)
+
+            Warning.existing_constant constant_name:        constant_full_name(const),
+                                      source_filename:      source_filename,
+                                      host_source_location: host_source_location
+          end
+        end
+
+        constant_names.each do |const|
+          establish_autoload const, source_filename
+          result << [const, source_filename]
+        end
+      end
+      result
+    end
+
+    # @!method except(*arguments)
+    #   Specifies constants and/or source files not to be autoloaded. _Symbol_
+    #   arguments signify the names of constants and _String_ arguments signify
+    #   the names of source files. You can specify _#except_ multiple times, and
+    #   its effects are cumulative.
+    #
+    #   Source file names specified are relative to _#from_.
+    #
+    #   Valid arguments include:
+    #
+    #   * _Symbol_ values
+    #   * _String_ values
+    #   * _Array_ values comprising _Symbol_ and/or _String_ values
+    #   * _Hash_ values comprising _Symbol_, _String_, and/or _Array_ values
+    #     described above
+    #   * Any combination of the options described above
+    #
+    #   @return [Autoloader] the _Autoloader_
+    #
+    #   @raise [RuntimeError] _#only_ already has a specification
+    #
+    #   @see #autoload!
+    #   @see #from
+    #   @see #only
+    #
+    # @!method only(*arguments)
+    #   Specifies constants and/or source files to be autoloaded exclusively.
+    #   _Symbol_ arguments signify the names of constants and _String_ arguments
+    #   signify the names of source files. You can specify _#only_ multiple
+    #   times, and its effects are cumulative.
+    #
+    #   Source file names specified are relative to _#from_.
+    #
+    #   Valid arguments include:
+    #
+    #   * _Symbol_ values
+    #   * _String_ values
+    #   * _Array_ values comprising _Symbol_ and/or _String_ values
+    #   * _Hash_ values comprising _Symbol_, _String_, and/or _Array_ values
+    #     described above, which will autoload specified constants from their
+    #     associated source files
+    #   * Any combination of the options described above
+    #
+    #   @return [Autoloader] the _Autoloader_
+    #
+    #   @raise [RuntimeError] _#except_ already has a specification
+    #
+    #   @see #autoload!
+    #   @see #from
+    #   @see #except
+    #
+    # @!method with(*arguments)
+    #   Specifies constants and/or source files to be autoloaded whose names may
+    #   have unpredictable spellings, stylization, or organization. _Symbol_
+    #   arguments signify the names of constants and _String_ arguments signify
+    #   the names of source files. You can specify _#with_ multiple times, and
+    #   its effects are cumulative.
+    #
+    #   Source file names specified are relative to _#from_.
+    #
+    #   Valid arguments include:
+    #
+    #   * _Symbol_ values
+    #   * _Array_ values comprising _Symbol_ values
+    #   * _Hash_ values comprising _Symbol_, _String_, and/or _Array_ values
+    #     described above, which will autoload specified constants from their
+    #     associated source files
+    #   * Any combination of the options described above
+    #
+    #   @return [Autoloader] the _Autoloader_
+    #
+    #   @see #autoload!
+    #   @see #from
+    %i(except only with).each do |attr|
+      define_method attr do |*arguments|
+        attr_specs = specifications.send(attr)
+        if arguments.empty?
+          return attr_specs.collect(&:value)
+        end
+
+        attr_specs << Specification.new(*arguments)
+        begin
+          specifications.validate! attr
+        rescue
+          attr_specs.pop
+          raise
+        end
+
+        self
+      end
+    end
+
+    # The directory from which source files are autoloaded.
+    #
+    # Defaults to the directory corresponding to the +__FILE__+ of
+    # _#host_binding_. For example, if <code>eval('__FILE__',
+    # host_binding)</code> evaluates to +'/absolute/path/to/my_awesome_gem.rb'+,
+    # then the default value of _#from_ is +'/absolute/path/to/my_awesome_gem'+.
+    #
+    # @param [String] value a source directory path; optional
+    #
+    # @return [String] if _value_ is +nil+, the source directory
+    # @return [Autoloader] if _value_ is not +nil+, the _Autoloader_
+    #
+    # @raise [ArgumentError] _value_ is a relative path
+    #
+    # @see #autoload!
+    # @see #host_binding
+    def from(value=nil)
+      return((@from && @from.path) || default_from) if value.nil?
+
+      # Validate value.
+      @from = LoadPathedDirectory.new(value)
+
+      self
+    end
+
+  private
+
+    attr_reader :specifications
+
+    def constant_full_name(constant_name)
+      "#{host_eval 'name rescue nil'}::#{constant_name}"
+    end
+
+    def default_from
+      filename = host_source_filename
+      dirname  = ::File.dirname(filename)
+      basename = ::File.basename(filename, ::File.extname(filename))
+      ::File.join dirname, basename
+    end
+
+    def establish_autoload(constant_name, source_filename)
+      host_eval "autoload #{constant_name.to_sym.inspect}, #{source_filename.inspect}"
+    end
+
+    def existing_autoload?(constant_name)
+      host_eval "autoload? #{constant_name.to_sym.inspect}"
+    end
+
+    def existing_constant?(constant_name)
+      host_eval "constants.include? #{constant_name.to_sym.inspect}"
+    end
+
+    def from_load_pathed_directory
+      @from || LoadPathedDirectory.new(default_from)
+    end
+
+    def host_eval(statement)
+      # TODO: Why does adding the third and fourth arguments break Kernel#eval ?
+      # ::Kernel.eval statement, host_binding, __FILE__, __LINE__
+      ::Kernel.eval statement, host_binding
+    end
+
+    def host_source_filename
+      host_eval '::File.expand_path __FILE__'
+    end
+
+    def host_source_location
+      host_eval('[__FILE__, __LINE__]').collect(&:to_s).join ':'
+    end
+
+  end
+
+end