easyload 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+.yardoc
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,5 @@
+# -*- encoding: utf-8 -*-
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in Easyload.gemspec
+gemspec

data/README.md

@@ -0,0 +1,64 @@
+Easyload
+========
+An alternative to autoload that relies on your project's directory structure to determine its
+module hierarchy, recursively.
+
+This is an opinionated loading method that attempts to simplify your development process by
+enforcing that your directory and file names follow convention and are consistent with your
+project's module hierarchy.  Additionally, it allows for painless refactoring and reduces code
+repetition by removing the need of declaring your module hierarchy in every single source
+file.  The project's directory structure determines that; it's just extra work to keep the two
+in sync.
+
+Easyload frowns upon the require statement, and would much rather that your library know how
+to load itself.  Simply reference the constant that you want, and it's there.
+
+
+General Use
+-----------
+To easyload a project, it must define at least one top level module to be used as the easyload
+root.  From that root, and the search path that it defines, all child constants are easyloaded
+according to your directory structure.
+
+For example, with a directory structure of:
+    lib/ 
+      my_easyloaded_module.rb
+      my_easyloaded_module/
+        child_module.rb
+        child_module/
+          leafy.rb
+        node.rb
+
+`lib/my_easyloaded_module.rb`:
+    module MyEasyloadedModule
+      import Easyload
+    end
+
+`lib/my_easyloaded_module/child_module.rb`:
+    module ChildModule
+      ... 
+    end
+
+`lib/my_easyloaded_module/child_module/leafy.rb`:
+    class Leafy
+      ...
+    end
+
+`lib/my_easyloaded_module/node.rb`:
+    class Node
+      ...
+    end
+
+Would result in the following module/class hierarchy being easyloadable:
+    MyEasyloadedModule
+    MyEasyloadedModule::ChildModule
+    MyEasyloadedModule::ChildModule::Leafy
+    MyEasyloadedModule::Node
+
+
+Easyload Configuration
+----------------------
+When a class or module includes `Easyload`, the 
+`Easyload::SingletonExtensions` module is mixed into that class or module's singleton methods, 
+providing the easyload API.  See [`Easyload::SingletonExtensions`](http://rdoc.info/github/nevir/easyload/master/Easyload/SingletonExtensions)
+for a reference of what configuration can be performed on an easyloaded class or module.

data/Rakefile

@@ -0,0 +1,6 @@
+# -*- encoding: utf-8 -*-
+require 'bundler'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+RSpec::Core::RakeTask.new

data/easyload.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path('../lib', __FILE__)
+require 'easyload/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'easyload'
+  s.version     = Easyload::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Ian MacLeod']
+  s.email       = ['ian@nevir.net']
+  s.homepage    = ''
+  s.summary     = 'A recursive and opinionated alternative to autoload.'
+  s.description = 'An alternative to autoload that relies on your project\'s directory structure to determine its module hierarchy, recursively.'
+
+  s.rubyforge_project = 'easyload'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ['lib']
+  
+  s.add_development_dependency('rspec', ['~> 2.5.0'])
+end

data/lib/easyload.rb

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require 'easyload/singleton_extensions'
+
+module Easyload
+  autoload :VERSION, 'version'
+  
+  # Handle module/class inclusions in a clean manner, and try to guess our easyload root.
+  # 
+  # @private
+  def self.included(in_mod)
+    class << in_mod
+      include SingletonExtensions
+    end
+    
+    if in_mod.name
+      components = in_mod.name.split('::').map {|n| in_mod.easyload_path_component_for_sym(n)}
+      in_mod.easyload_from(components.join('/'))
+    end
+  end
+end

data/lib/easyload/singleton_extensions.rb

@@ -0,0 +1,72 @@
+# -*- encoding: utf-8 -*-
+module Easyload
+  # The singleton methods that are defined for a module that includes {Easyload}.
+  module SingletonExtensions
+    # The root path that easyload should use when loading a child constant for this module.
+    # 
+    # Defaults to the path component form of the class/module's name
+    attr_reader :easyload_root
+    
+    # Sets easyload_root.
+    def easyload_from(root_path)
+      @easyload_root = root_path.to_s
+    end
+    
+    # Converts a CamelCased symbol into a path component.
+    # 
+    # * A +Single+ symbol becomes +single+.
+    # * +MultiWordSymbols+ become +multi_word_symbols+.
+    # * +ACRONYMS+ are treated like words: +acronyms+.
+    # * +ABCFoo+ is considered to be a mix of acronyms and words: +abc_foo+.
+    def easyload_path_component_for_sym(sym)
+      path = sym.to_s.dup
+      path.gsub!(/([A-Z]+)([A-Z][a-z]+)/, '\1_\2_')
+      path.gsub!(/([A-Z][a-z]+)/, '\1_')
+      path.gsub!(/_+/, '_')
+      path.chomp!('_')
+      path.downcase!
+    end
+    
+    # The meat of easyloading happens here.
+    # 
+    # @private
+    def const_missing(sym)
+      if not self.instance_variable_defined? :@easyload_root
+        $stderr.puts "You must call easyload_from() before you can easyload #{self}::#{sym}"
+        return super(sym)
+      end
+      
+      path_component = self.easyload_path_component_for_sym(sym)
+      easyload_path = File.join(@easyload_root, "#{path_component}.rb")
+      
+      # Search for the file to include
+      $LOAD_PATH.each do |load_root|
+        full_load_path = File.join(load_root, easyload_path)
+        if File.exists? full_load_path
+          self.module_eval(File.read(full_load_path))
+          
+          # Did we get our target constant?
+          if self.const_defined? sym
+            target_const = self.const_get(sym)
+            class << target_const
+              include SingletonExtensions
+            end
+            
+            target_const.easyload_from(File.join(self.easyload_root, path_component))
+            
+            return self.const_get(sym)
+          
+          # Warn but still break the load process.  We don't want to support ambiguous load
+          # paths.
+          else
+            $stderr.puts "Attempted to easyload #{sym} from '#{full_load_path}', but it doesn't appear to exist in that source file."
+          end
+          
+          break
+        end
+      end
+      
+      return super(sym)
+    end
+  end
+end

data/lib/easyload/version.rb

@@ -0,0 +1,4 @@
+# -*- encoding: utf-8 -*-
+module Easyload
+  VERSION = '0.1.0'
+end

data/spec/basic_spec.rb

@@ -0,0 +1,56 @@
+# -*- encoding: utf-8 -*-
+require 'easyload'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+module Examples
+  include Easyload
+end
+
+module Deep
+  module Example
+    include Easyload
+  end
+end
+
+module SpecRoot
+  class << self
+    attr_accessor :load_count
+  end
+  self.load_count = 0
+end
+
+describe 'A basic easyload module' do
+  it 'should default to the class/module name for the easyload root' do
+    Examples.easyload_root.should == 'examples'
+  end
+  
+  it 'should be able to load constants one level deep' do
+    Examples::Node::ABOUT.should == 'A node?'
+  end
+  
+  it 'should raise standard NameErrors for unknown constants' do
+    expect {
+      Examples::Missing
+    }.to raise_error(NameError)
+  end
+  
+  it 'should not load files twice' do
+    SpecRoot.load_count.should == 0
+    
+    Examples::LoadCounter::ABOUT.should == 'load counter: 1'
+    SpecRoot.load_count.should == 1
+    
+    Examples::LoadCounter::ABOUT.should == 'load counter: 1'
+    SpecRoot.load_count.should == 1
+  end
+  
+  it 'should be able to load nested modules' do
+    Examples::Nested::Leaf::ABOUT.should == 'A leaf?'
+  end
+  
+  it 'should be able to automatically guess a nested module name' do
+    Deep::Example.easyload_root.should == 'deep/example'
+    thing = Deep::Example::Thing.new
+  end
+end

data/spec/deep/example.rb

@@ -0,0 +1,4 @@
+# -*- encoding: utf-8 -*-
+module Example
+  
+end

data/spec/deep/example/thing.rb

@@ -0,0 +1,4 @@
+# -*- encoding: utf-8 -*-
+class Thing
+  
+end

data/spec/examples/load_counter.rb

@@ -0,0 +1,7 @@
+# -*- encoding: utf-8 -*-
+
+::SpecRoot.load_count += 1
+
+module LoadCounter
+  ABOUT = "load counter: #{::SpecRoot.load_count}"
+end

data/spec/examples/nested.rb

@@ -0,0 +1,4 @@
+# -*- encoding: utf-8 -*-
+class Nested
+  
+end

data/spec/examples/nested/leaf.rb

@@ -0,0 +1,4 @@
+# -*- encoding: utf-8 -*-
+class Leaf
+  ABOUT = 'A leaf?'
+end

data/spec/examples/node.rb

@@ -0,0 +1,4 @@
+# -*- encoding: utf-8 -*-
+class Node
+  ABOUT = 'A node?'
+end

data/spec/naming_spec.rb

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+require 'easyload'
+
+module NamingExamples
+  Easyload
+end
+
+describe 'Easyload file names' do
+  it 'should use a single lowercase name for a single word constant' do
+    Examples.easyload_path_component_for_sym(:Single).should == 'single'
+    Examples.easyload_path_component_for_sym(:A).should == 'a'
+  end
+  
+  it 'should break CamelCase constants into lowercase words separated by underscores' do
+    Examples.easyload_path_component_for_sym(:TwoWords).should == 'two_words'
+    Examples.easyload_path_component_for_sym(:OneTwoThreeFour).should == 'one_two_three_four'
+  end
+  
+  it 'should treat strings of adjacent capital letters as acronyms' do
+    Examples.easyload_path_component_for_sym(:ABC).should == 'abc'
+    Examples.easyload_path_component_for_sym(:WTFWord).should == 'wtf_word'
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification 
+name: easyload
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Ian MacLeod
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-02-13 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 5
+        - 0
+        version: 2.5.0
+  type: :development
+  version_requirements: *id001
+description: An alternative to autoload that relies on your project's directory structure to determine its module hierarchy, recursively.
+email: 
+- ian@nevir.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- easyload.gemspec
+- lib/easyload.rb
+- lib/easyload/singleton_extensions.rb
+- lib/easyload/version.rb
+- spec/basic_spec.rb
+- spec/deep/example.rb
+- spec/deep/example/thing.rb
+- spec/examples/load_counter.rb
+- spec/examples/nested.rb
+- spec/examples/nested/leaf.rb
+- spec/examples/node.rb
+- spec/naming_spec.rb
+has_rdoc: true
+homepage: ""
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: easyload
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A recursive and opinionated alternative to autoload.
+test_files: 
+- spec/basic_spec.rb
+- spec/deep/example.rb
+- spec/deep/example/thing.rb
+- spec/examples/load_counter.rb
+- spec/examples/nested.rb
+- spec/examples/nested/leaf.rb
+- spec/examples/node.rb
+- spec/naming_spec.rb