autoloaded 1.2.0 → 1.3.0

data/lib/autoloaded/compatibility/refine_and_using.rb

@@ -1,6 +1,7 @@
 # Fall back to monkeypatching if refinements are not supported.
 
 unless ::Module.private_instance_methods.include?(:refine)
+  # @api private
   class ::Module
 
   private
@@ -14,4 +15,5 @@ end
 
 unless private_methods.include?(:using)
   def using(*arguments); end
+  private :using
 end

data/lib/autoloaded/constant.rb

@@ -1,11 +1,14 @@
-require 'autoloaded/refine/string/to_source_filename'
 require 'set'
 
 using ::Autoloaded::Refine::String::ToSourceFilename
 
 module Autoloaded; end
 
-# @private
+# Represents a Ruby constant.
+#
+# @since 0.0.1
+#
+# @api private
 class Autoloaded::Constant
 
   attr_reader :name

data/lib/autoloaded/deprecation.rb

@@ -0,0 +1,50 @@
+module Autoloaded; end
+
+# Prints deprecation messages to _stderr_.
+#
+# @since 1.3
+#
+# @api private
+module Autoloaded::Deprecation
+
+  class << self
+
+    # Sets the deprecation stream.
+    #
+    # @param [IO] value a new value for #io
+    attr_writer :io
+
+    # The deprecation stream. Defaults to +$stderr+.
+    #
+    # @return [IO] the deprecation stream
+    def io
+      @io || $stderr
+    end
+
+    # Prints a deprecation message to _#io_ regarding the specified
+    # _deprecated_usage_.
+    #
+    # @param [String] deprecated_usage API usage that is soon to be discontinued
+    # @param [String] sanctioned_usage API usage that will succeed
+    #                                  _deprecated_usage_
+    # @param [String] source_filename  the file path of the source invoking the
+    #                                  deprecated API
+    #
+    # @return [Module] _Deprecation_
+    def deprecate(deprecated_usage: raise(::ArgumentError,
+                                          'missing keyword: deprecated_usage'),
+                  sanctioned_usage: raise(::ArgumentError,
+                                          'missing keyword: sanctioned_usage'),
+                  source_filename:  raise(::ArgumentError,
+                                          'missing keyword: source_filename'))
+      deprecation = "\e[33m*** \e[7m DEPRECATED \e[0m "     +
+                    "\e[4m#{deprecated_usage}\e[0m -- use " +
+                    "\e[4m#{sanctioned_usage}\e[0m instead in #{source_filename}"
+      io.puts deprecation
+
+      self
+    end
+
+  end
+
+end

data/lib/autoloaded/inflection.rb

@@ -0,0 +1,71 @@
+module Autoloaded; end
+
+# Translates source filenames into constants.
+  #
+  # @since 1.3
+#
+# @api private
+module Autoloaded::Inflection
+
+  # Translates a _String_ representing a source filename into a _Symbol_
+  # representing a constant.
+  #
+  # @param [String] source_filename the name of a source code file
+  #
+  # @return [Symbol] the name of a constant corresponding to _source_filename_
+  #
+  # @raise [ArgumentError] _source_filename_ is +nil+ or empty
+  #
+  # @note Directories are ignored rather than translated into namespaces.
+  def self.to_constant_name(source_filename)
+    source_filename = source_filename.to_s
+    raise(::ArgumentError, "can't be blank") if source_filename.empty?
+
+    translate(source_filename, *%i(file_basename
+                                   camelize_if_lowercase
+                                   nonalphanumeric_to_underscore
+                                   delete_leading_nonalphabetic
+                                   capitalize_first)).to_sym
+  end
+
+private
+
+  def self.camelize(string)
+    string.gsub(/(.)(?:_|-)+(.)/) do |match|
+      "#{match[0..0].downcase}#{match[-1..-1].upcase}"
+    end
+  end
+
+  def self.camelize_if_lowercase(string)
+    return string unless lowercase?(string)
+
+    camelize string
+  end
+
+  def self.capitalize_first(string)
+    "#{string[0..0].upcase}#{string[1..-1]}"
+  end
+
+  def self.delete_leading_nonalphabetic(string)
+    string.gsub(/^[^a-z]+/i, '')
+  end
+
+  def self.file_basename(string)
+    ::File.basename string, ::File.extname(string)
+  end
+
+  def self.lowercase?(string)
+    string == string.downcase
+  end
+
+  def self.nonalphanumeric_to_underscore(string)
+    string.gsub(/[^a-z0-9]+/i, '_')
+  end
+
+  def self.translate(string, *translations)
+    translations.inject string do |result, translation|
+      send translation, result
+    end
+  end
+
+end

data/lib/autoloaded/load_pathed_directory.rb

@@ -0,0 +1,112 @@
+require 'pathname'
+
+module Autoloaded; end
+
+# Enumerates the source files in a directory, relativizing their paths using the
+# Ruby load path.
+#
+# @since 1.3
+#
+# @api private
+class Autoloaded::LoadPathedDirectory
+
+  # The file extension of source files.
+  SOURCE_FILE_EXTENSION = '.rb'
+
+private
+
+  def self.join(path1, path2)
+    paths = [path1, path2].reject do |path|
+      path.to_s.empty?
+    end
+    (paths.length < 2) ? paths.first : ::File.join(*paths)
+  end
+
+  def self.ruby_load_paths
+    $:
+  end
+
+  def self.source_basename(source_filename)
+    ::File.basename source_filename, SOURCE_FILE_EXTENSION
+  end
+
+public
+
+  # The full path of a source directory.
+  #
+  # @return [String] a directory path
+  attr_reader :path
+
+  # Constructs a new _LoadPathedDirectory_ with the specified _path_.
+  #
+  # @param [String] path the value of _#path_
+  #
+  # @raise [ArgumentError] _path_ is +nil+ or a relative path
+  def initialize(path)
+    raise ::ArgumentError, "can't be nil" if path.nil?
+
+    @path = path.dup.freeze
+    if ::Pathname.new(@path).relative?
+      raise ::ArgumentError, "can't be relative"
+    end
+  end
+
+  # Enumerates the source files in _#path_, relativizing their paths if possible
+  # using the longest applicable entry in the Ruby load path (that is,
+  # <tt>$:</tt>). File names are rendered without _SOURCE_FILE_EXTENSION_.
+  # Yielded paths are guaranteed usable in +require+ statements unless elements
+  # of the Ruby load path are removed or changed.
+  #
+  # @yield [String] each source file in _#path_, formatted for use in +require+
+  #                 statements
+  #
+  # @return [LoadPathedDirectory] the _LoadPathedDirectory_
+  #
+  # @see #path
+  # @see http://ruby-doc.org/core/Kernel.html#method-i-require Kernel#require
+  def each_source_filename
+    if (ruby_load_path = closest_ruby_load_path)
+      ::Dir.chdir ruby_load_path do
+        glob = self.class.join(path_from(ruby_load_path),
+                               "*#{SOURCE_FILE_EXTENSION}")
+        ::Dir.glob glob do |file|
+          yield without_source_file_extension(file)
+        end
+      end
+    else
+      glob = self.class.join(path, "*#{SOURCE_FILE_EXTENSION}")
+      ::Dir.glob glob do |file|
+        yield without_source_file_extension(file)
+      end
+    end
+
+    self
+  end
+
+private
+
+  def closest_ruby_load_path
+    closest = self.class.ruby_load_paths.inject(score: 0) do |close, load_path|
+      score = path.length - path_from(load_path).length
+      (close[:score] < score) ? {score: score, load_path: load_path} : close
+    end
+    closest[:load_path]
+  end
+
+  def path_from(other_path)
+    # Don't use Pathname#relative_path_from because we want to avoid introducing
+    # double dots. The intent is to render the path as relative, if and only if
+    # it is a subdirectory of 'other_path'.
+    pattern = /^#{::Regexp.escape other_path.chomp(::File::SEPARATOR)}#{::Regexp.escape ::File::SEPARATOR}?/
+    path.gsub pattern, ''
+  end
+
+  def without_source_file_extension(path)
+    if (dirname = ::File.dirname(path)) == '.'
+      dirname = nil
+    end
+    basename = ::File.basename(path, SOURCE_FILE_EXTENSION)
+    self.class.join dirname, basename
+  end
+
+end

data/lib/autoloaded/refine.rb

@@ -1,6 +1,12 @@
 module Autoloaded
 
-  # @private
+  # Contains Ruby Core Library type refinements.
+  #
+  # @see http://ruby-doc.org/core Ruby Core Library
+  #
+  # @since 0.0.1
+  #
+  # @api private
   module Refine
 
     autoload :String, 'autoloaded/refine/string'

data/lib/autoloaded/refine/string.rb

@@ -2,6 +2,13 @@ module Autoloaded
 
   module Refine
 
+    # Contains _String_ refinements.
+    #
+    # @see http://ruby-doc.org/core/String.html String
+    #
+    # @since 0.0.1
+    #
+    # @api private
     module String
 
       autoload :ToSourceFilename, 'autoloaded/refine/string/to_source_filename'

data/lib/autoloaded/refine/string/to_source_filename.rb

@@ -10,8 +10,20 @@ module Autoloaded
 
 end
 
+# Refines _String_ to translate a constant name into a source filename.
+#
+# @since 0.0.1
+#
+# @api private
 module Autoloaded::Refine::String::ToSourceFilename
 
+  # @!method to_source_filename
+  #   Translates the name of a constant into the name of a source file.
+  #
+  #   @return [String] the name of a source file corresponding to the name of a
+  #                    constant
+  #
+  #   @note Namespaces are ignored rather than translated into directories.
   refine ::String do
     def replace_nonalphanumeric_sequence_with_separator
       gsub(/[^a-z0-9]+/i, separator.to_s)

data/lib/autoloaded/specification.rb

@@ -0,0 +1,97 @@
+module Autoloaded
+
+  # Describes regulations for autoloading.
+  #
+  # @since 1.3
+  #
+  # @api private
+  class Specification
+
+    # The elements of the specification.
+    #
+    # @return [Array]
+    attr_reader :elements
+
+    # Constructs a new _Specification_ with the specified _elements_.
+    #
+    # @param elements the value of _#elements_
+    #
+    # 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
+    #
+    # @see #elements
+    def initialize(*elements)
+      @elements = elements
+    end
+
+    # Compares the _Specification_ with the specified _other_object_.
+    #
+    # @param other_object another object
+    #
+    # @return [true] if _other_object_ is equal to the _Specification_
+    # @return [false] if _other_object_ is not equal to the _Specification_
+    def ==(other_object)
+      return false unless other_object.kind_of?(self.class)
+
+      other_object.elements == elements
+    end
+
+    # Provides a matching constant from _#elements_ for the specified
+    # _source_filename_.
+    #
+    # @param [String] source_filename the name of a source file
+    #
+    # @return [Symbol] a matching constant
+    # @return [Array of Symbol] matching constants
+    # @return [nil] if there is no matching constant
+    #
+    # @see #elements
+    def match(source_filename)
+      matched = elements.detect do |element|
+        if element.kind_of?(::Hash)
+          element.each do |key, value|
+            return value if source_filename_match?(source_filename, key)
+
+            return key if source_filename_match?(source_filename, value)
+          end
+          false
+        else
+          source_filename_match? source_filename, element
+        end
+      end
+
+      matched.kind_of?(::String) ? Inflection.to_constant_name(matched) : matched
+    end
+
+  private
+
+    def source_filename_match?(file, array_or_file_or_constant)
+      case array_or_file_or_constant
+        when ::Array
+          array_or_file_or_constant.detect do |o|
+            source_filename_match? file, o
+          end
+        when ::Symbol
+          source_filename_match_constant_name? file, array_or_file_or_constant
+        else
+          source_filename_match_filename? file, array_or_file_or_constant
+      end
+    end
+
+    def source_filename_match_constant_name?(file, constant)
+      Inflection.to_constant_name(file).to_s.casecmp(constant.to_s).zero?
+    end
+
+    def source_filename_match_filename?(file1, file2)
+      file1.to_s.casecmp(file2.to_s).zero?
+    end
+
+  end
+
+end

data/lib/autoloaded/specifications.rb

@@ -0,0 +1,66 @@
+module Autoloaded; end
+
+# Holds regulations for autoloading.
+#
+# @since 1.3
+#
+# @api private
+class Autoloaded::Specifications
+
+  # @!method except
+  #   Specifications for excluding source files from being autoloaded.
+  #
+  #   @return [Array of Specification] a list of specifications
+  #
+  #   @api private
+  #
+  # @!method only
+  #   Specifications for narrowing the set of source files being autoloaded as
+  #   well as optionally renaming and/or reorganizing their corresponding
+  #   constants.
+  #
+  #   @return [Array of Specification] a list of specifications
+  #
+  #   @api private
+  #
+  # @!method with
+  #   Specifications for renaming and/or reorganizing the constants corresponding
+  #   to source files being autoloaded.
+  #
+  #   @return [Array of Specification] a list of specifications
+  #
+  #   @api private
+  %i(except only with).each do |attribute_name|
+    define_method attribute_name do
+      variable_name = "@#{attribute_name}"
+      (instance_variable_get(variable_name) || []).tap do |value|
+        instance_variable_set variable_name, value
+      end
+    end
+  end
+
+  # Evaluates the specifications for conflicts, in reference to the specified
+  # _attribute_.
+  #
+  # @param [Symbol] attribute the attribute (+:except+, +:only+, or +:with+)
+  #                           being modified
+  #
+  # @return [Specifications] the _Specifications_
+  #
+  # @raise [RuntimeError] _attribute_ is +:except+ and _#only_ is not empty
+  # @raise [RuntimeError] _attribute_ is +:only+ and _#except_ is not empty
+  #
+  # @see #except
+  # @see #only
+  def validate!(attribute)
+    other_attribute = {except: :only, only: :except}[attribute]
+    if other_attribute
+      unless send(attribute).empty? || send(other_attribute).empty?
+        raise "can't specify `#{attribute}' when `#{other_attribute}' is " +
+              'already specified'
+      end
+    end
+
+    self
+  end
+end