autoloaded 1.2.0 → 1.3.0

data/lib/autoloaded/version.rb

@@ -1,6 +1,8 @@
 module Autoloaded
 
   # The current version of the _Autoloaded_ project.
-  VERSION = '1.2.0'
+  #
+  # @since 0.0.1
+  VERSION = '1.3.0'
 
 end

data/lib/autoloaded/warning.rb

@@ -0,0 +1,125 @@
+module Autoloaded; end
+
+# Prints warning messages to _stderr_.
+#
+# @since 1.3
+#
+# @api private
+module Autoloaded::Warning
+
+  class << self
+
+    # Sets the warning stream.
+    #
+    # @param [IO] value a new value for #io
+    attr_writer :io
+
+    # The warning stream. Defaults to +$stderr+.
+    #
+    # @return [IO] the warning stream
+    def io
+      @io || $stderr
+    end
+
+    # Prints a warning message to _#io_ concerning an existing autoloaded
+    # constant for which the autoloaded source file is being changed.
+    #
+    # @param [Symbol] constant_name        the name of the constant
+    # @param [String] old_source_filename  the name of the existing autoloaded
+    #                                      source file
+    # @param [String] new_source_filename  the name of the new autoloaded source
+    #                                      file
+    # @param [String] host_source_location the file and line number of the source
+    #                                      establishing autoloading
+    #
+    # @return [Module] _Warning_
+    def changing_autoload(constant_name:        raise(::ArgumentError,
+                                                      'missing keyword: constant_name'),
+                          old_source_filename:  raise(::ArgumentError,
+                                                      'missing keyword: old_source_filename'),
+                          new_source_filename:  raise(::ArgumentError,
+                                                      'missing keyword: new_source_filename'),
+                          host_source_location: raise(::ArgumentError,
+                                                      'missing keyword: host_source_location'))
+      message = "Existing autoload of \e[4m#{constant_name}\e[0m from "       +
+                "#{old_source_filename.inspect} is being overridden to "      +
+                "autoload from #{new_source_filename.inspect} -- avoid this " +
+                "warning by using an \e[4monly\e[0m or an \e[4mexcept\e[0m "  +
+                "specification in the block at #{host_source_location}"
+      warn message
+    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 _#enabled?_ is reset after the
+    #        block is called
+    #
+    # @return if a block is given, the result of calling the block
+    # @return [Module] if a block is not given, _Warning_
+    #
+    # @see .enabled?
+    def enable(enabling)
+      previous_value = @disabled
+      @disabled = not!(enabling)
+      if block_given?
+        begin
+          return yield
+        ensure
+          @disabled = previous_value
+        end
+      end
+
+      self
+    end
+
+    # Indicates whether warning messages are enabled or disabled.
+    #
+    # @return [true] if warning messages are enabled
+    # @return [false] if warning messages are enabled
+    #
+    # @see .enable
+    def enabled?
+      not! @disabled
+    end
+
+    # Prints a warning message to _#io_ concerning a defined constant for which
+    # autoloading is being established.
+    #
+    # @param [Symbol] constant_name        the name of the constant
+    # @param [String] source_filename      the name of the autoloaded source file
+    # @param [String] host_source_location the file and line number of the source
+    #                                      establishing autoloading
+    #
+    # @return [Module] _Warning_
+    def existing_constant(constant_name:        raise(::ArgumentError,
+                                                      'missing keyword: constant_name'),
+                          source_filename:      raise(::ArgumentError,
+                                                      'missing keyword: source_filename'),
+                          host_source_location: raise(::ArgumentError,
+                                                      'missing keyword: host_source_location'))
+      message = "Existing definition of \e[4m#{constant_name}\e[0m obviates " +
+                "autoloading from #{source_filename.inspect} -- avoid this "  +
+                "warning by using an \e[4monly\e[0m or an \e[4mexcept\e[0m "  +
+                "specification in the block at #{host_source_location}"
+      warn message
+    end
+
+  private
+
+    def not!(value)
+      value.nil? || (value == false)
+    end
+
+    def warn(message)
+      warning = "\e[33m*** \e[7m WARNING \e[0m #{message}"
+      io.puts(warning) if enabled?
+
+      self
+    end
+
+  end
+
+end

data/spec/autoloaded/autoloader_spec.rb

@@ -0,0 +1,469 @@
+RSpec.describe Autoloaded::Autoloader do
+  subject(:autoloader) { autoloader_class.new host_binding }
+
+  before :each do
+    allow(specifications_class).to receive(:new).and_return(specifications)
+    allow(inflector_class).to receive(:to_constant_name).
+                              and_return(:FromInflection1,
+                                         :FromInflection2,
+                                         :FromInflection3,
+                                         :FromInflection4)
+  end
+
+  let(:autoloader_class) { described_class }
+
+  let(:host_binding) { self.class.class_eval 'binding', __FILE__, __LINE__ }
+
+  let(:directory_class) { Autoloaded::LoadPathedDirectory }
+
+  let(:specifications) { specifications_class.new }
+
+  let(:specifications_class) { Autoloaded::Specifications }
+
+  let(:specification_class) { Autoloaded::Specification }
+
+  let(:inflector_class) { Autoloaded::Inflection }
+
+  describe '.new' do
+    describe 'with nil argument' do
+      specify {
+        expect { autoloader_class.new nil }.to raise_error(ArgumentError,
+                                                           "can't be nil")
+      }
+    end
+  end
+
+  describe '#from' do
+    subject(:from) { autoloader.from }
+
+    describe 'has expected default value' do
+      specify { is_expected.to eq(__FILE__.gsub(/\.rb$/, '')) }
+    end
+
+    describe 'rejects relative path argument' do
+      specify {
+        expect {
+          autoloader.from 'a/relative/path'
+        }.to raise_error(ArgumentError, "can't be relative")
+      }
+    end
+
+    describe 'operates as attribute reader and writer' do
+      specify {
+        autoloader.from '/an/absolute/path'
+        is_expected.to eq('/an/absolute/path')
+      }
+    end
+  end
+
+  describe '#except' do
+    specify("delegates to #{Autoloaded::Specifications.name}#except") {
+      expect(specifications.except).to be_empty
+      autoloader.except 'foo'
+      expect(specifications.except).to contain_exactly(specification_class.new('foo'))
+    }
+
+    describe 'where #only is specified' do
+      before :each do
+        autoloader.only :Foo
+      end
+
+      specify {
+        expect { autoloader.except :Bar }.to raise_error(RuntimeError,
+                                                         "can't specify `except' when `only' is already specified")
+      }
+    end
+  end
+
+  describe '#only' do
+    specify("delegates to #{Autoloaded::Specifications.name}#only") {
+      expect(specifications.only).to be_empty
+      autoloader.only 'foo'
+      expect(specifications.only).to contain_exactly(specification_class.new('foo'))
+    }
+
+    describe 'where #except is specified' do
+      before :each do
+        autoloader.except :Foo
+      end
+
+      specify {
+        expect { autoloader.only :Bar }.to raise_error(RuntimeError,
+                                                       "can't specify `only' when `except' is already specified")
+      }
+    end
+  end
+
+  describe '#with' do
+    specify("delegates to #{Autoloaded::Specifications.name}#with") {
+      expect(specifications.with).to be_empty
+      autoloader.with 'foo'
+      expect(specifications.with).to contain_exactly(specification_class.new('foo'))
+    }
+  end
+
+  describe '#autoload!' do
+    before :each do
+      allow_any_instance_of(directory_class).to receive(:closest_ruby_load_path).
+                                                and_return('/foo')
+      allow(directory_class).to receive(:new).and_return(directory)
+      allow(directory).to receive(:each_source_filename)
+    end
+
+    let(:directory) { directory_class.new '/foo' }
+
+    describe 'where #from is' do
+      describe 'not specified' do
+        describe "initializes #{Autoloaded::LoadPathedDirectory.name} with computed value" do
+          specify {
+            expect(directory_class).to receive(:new).
+                                       with(__FILE__.gsub(/\.rb$/, '')).
+                                       and_return(directory)
+            autoloader.autoload!
+          }
+        end
+      end
+
+      describe 'specified' do
+        before :each do
+          autoloader.from directory.path
+          allow(specifications).to receive(:except).
+                                   and_return(except_specifications)
+          allow(specifications).to receive(:only).
+                                   and_return(only_specifications)
+          allow(specifications).to receive(:with).
+                                   and_return(with_specifications)
+        end
+
+        let(:except_specifications) { [] }
+
+        let(:except_specification) { specification_class.new }
+
+        let(:only_specifications) { [] }
+
+        let(:only_specification) { specification_class.new }
+
+        let(:with_specifications) { [] }
+
+        let(:with_specification) { specification_class.new }
+
+        describe 'where no source files are found' do
+          specify {
+            expect(Kernel).not_to receive(:eval)
+            autoloader.autoload!
+          }
+
+          specify { expect(autoloader.autoload!).to be_empty }
+        end
+
+        describe 'where a source file is found' do
+          before :each do
+            allow(directory).to receive(:each_source_filename).
+                                and_yield('from_each_source_filename')
+          end
+
+          describe 'and no specifications are provided' do
+            specify {
+              expect(Kernel).to receive(:eval).
+                                with('autoload? :FromInflection1',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('constants.include? :FromInflection1',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload :FromInflection1, "from_each_source_filename"',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              autoloader.autoload!
+            }
+
+            specify {
+              expect(autoloader.autoload!).to eq([[:FromInflection1,
+                                                   'from_each_source_filename']])
+            }
+          end
+
+          describe "and a `with' specification is provided" do
+            before :each do
+              allow(with_specification).to receive(:match).and_return(:FromWith)
+            end
+
+            let(:with_specifications) { [with_specification] }
+
+            specify {
+              expect(Kernel).to receive(:eval).
+                                with('autoload? :FromWith',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('constants.include? :FromWith',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload :FromWith, "from_each_source_filename"',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric))
+                                     host_binding).
+                                ordered
+              autoloader.autoload!
+            }
+
+            specify {
+              expect(autoloader.autoload!).to eq([[:FromWith,
+                                                   'from_each_source_filename']])
+            }
+          end
+
+          describe "and an `only' specification is provided" do
+            before :each do
+              allow(only_specification).to receive(:match).and_return(:FromOnly)
+            end
+
+            let(:only_specifications) { [only_specification] }
+
+            specify {
+              expect(Kernel).to receive(:eval).
+                                with('autoload? :FromOnly',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('constants.include? :FromOnly',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload :FromOnly, "from_each_source_filename"',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              autoloader.autoload!
+            }
+
+            specify { expect(autoloader.autoload!).to eq([[:FromOnly,
+                                                           'from_each_source_filename']]) }
+          end
+
+          describe "and both `with' and `only' specifications are provided" do
+            before :each do
+              allow(with_specification).to receive(:match).and_return(:FromWith)
+              allow(only_specification).to receive(:match).and_return(:FromOnly)
+            end
+
+            let(:with_specifications) { [with_specification] }
+
+            let(:only_specifications) { [only_specification] }
+
+            specify {
+              expect(Kernel).to receive(:eval).
+                                with('autoload? :FromWith',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('constants.include? :FromWith',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload :FromWith, "from_each_source_filename"',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              autoloader.autoload!
+            }
+
+            specify { expect(autoloader.autoload!).to eq([[:FromWith,
+                                                           'from_each_source_filename']]) }
+          end
+        end
+
+        describe 'where multiple source files are found' do
+          before :each do
+            allow(directory).to receive(:each_source_filename).
+                                and_yield('from_each_source_filename1').
+                                and_yield('from_each_source_filename2').
+                                and_yield('from_each_source_filename3')
+          end
+
+          describe 'and no specifications are provided' do
+            specify {
+              expect(Kernel).to receive(:eval).
+                                with('autoload? :FromInflection1',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('constants.include? :FromInflection1',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload :FromInflection1, "from_each_source_filename1"',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload? :FromInflection2',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('constants.include? :FromInflection2',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload :FromInflection2, "from_each_source_filename2"',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload? :FromInflection3',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('constants.include? :FromInflection3',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload :FromInflection3, "from_each_source_filename3"',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              autoloader.autoload!
+            }
+
+            specify {
+              expect(autoloader.autoload!).to eq([[:FromInflection1,
+                                                   'from_each_source_filename1'],
+                                                  [:FromInflection2,
+                                                   'from_each_source_filename2'],
+                                                  [:FromInflection3,
+                                                   'from_each_source_filename3']])
+            }
+          end
+
+          describe "and a matching `except' specification is provided" do
+            before :each do
+              allow(except_specification).to receive(:match).
+                                             with('from_each_source_filename1').
+                                             and_return(nil)
+              allow(except_specification).to receive(:match).
+                                             with('from_each_source_filename2').
+                                             and_return(:FromExcept)
+              allow(except_specification).to receive(:match).
+                                             with('from_each_source_filename3').
+                                             and_return(nil)
+            end
+
+            let(:except_specifications) { [except_specification] }
+
+            specify {
+              expect(Kernel).to receive(:eval).
+                                with('autoload? :FromInflection1',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('constants.include? :FromInflection1',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload :FromInflection1, "from_each_source_filename1"',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload? :FromInflection2',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('constants.include? :FromInflection2',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              expect(Kernel).to receive(:eval).
+                                with('autoload :FromInflection2, "from_each_source_filename3"',
+                                #      host_binding,
+                                #      kind_of(String),
+                                #      kind_of(Numeric)).
+                                     host_binding).
+                                ordered
+              autoloader.autoload!
+            }
+
+            specify {
+              expect(autoloader.autoload!).to eq([[:FromInflection1,
+                                                   'from_each_source_filename1'],
+                                                  [:FromInflection2,
+                                                   'from_each_source_filename3']])
+            }
+          end
+        end
+      end
+    end
+  end
+end