lazy_load 0.0.2

data/.gitignore

@@ -0,0 +1,7 @@
+
+.rvmrc
+.yardoc
+doc
+*.swp
+*.gem
+*.rbc

data/CHANGELOG

@@ -0,0 +1,3 @@
+
+0.0.2
+  Initial version

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Jostein Berre Eliassen
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,93 @@
+
+LazyLoad
+========
+
+**Unobtrusively autoload code with callbacks and helpful errors**
+
+---
+
+LazyLoad is a more elaborate alternative to the [autoload](http://ruby-doc.org/core/classes/Module.html#M000443) method. For instance, it allows setting up callbacks to be invoked when a certain constant is referenced. It is used in scenarios where you need to "soft require" something -- typically to find the "best available" implementation, or fail gracefully when dependencies are not met.
+
+Unlike autoload, LazyLoad is scoped, and it does therefore not pollute or monkey patch. What this means is: When you register a callback for the `Foo` constant, referencing `LazyLoad::Foo` will trigger the callback. Simply referencing `Foo` will not trigger the callback.
+
+### Samples
+
+```bash
+  
+  gem install lazy_load`
+
+```
+
+```ruby
+
+  LazyLoad.map(:Tilt, 'tilt',
+    'Tilt not found. Possible fix: gem install tilt')
+
+  # or equivalent with a callback:
+
+  LazyLoad.map(:Tilt) do
+    begin
+      require 'tilt'
+      Tilt
+    rescue LoadError
+      raise(LazyLoad::DependencyError,
+        'Tilt not found. Possible fix: gem install tilt')
+    end
+  end
+
+  Tilt
+  # => NameError: uninitialized constant Object::Tilt
+
+  LazyLoad::Tilt
+  # => Tilt
+
+  # or if Tilt is not available:
+  
+  LazyLoad::Tilt
+  # => LazyLoad::DependencyError: Tilt not found. Possible fix: gem install tilt'
+
+  LazyLoad::Foo
+  # => NameError: uninitialized constant LazyLoad::Foo
+
+```
+
+Notice how, when a block is used, it must return the constant. The help message is optional. LazyLoad has no mappings by default.
+
+
+### Errors
+
+Referencing constant beneath `LazyLoad` for which there is no mapping, resuslts in the usual `NameError`. Referencing an unavailable constant typically gives a `LazyLoad::DependencyError`, which conveniently is also a subclass of `NameError`.
+
+
+### Best available
+
+You can use the `best` method to return the first constant from a list of names, or else raise a `LazyLoad::DependencyError` for the first (most preferred) one.
+
+```ruby
+    LazyLoad.best(:Kramdown, :RDiscount, :Redcarpet)
+
+```
+
+
+### Scopes
+
+Use the `scope` method if you need more than one scope (typically for gem interoperability).
+
+```ruby
+  module SomeProject
+    Lazy = LazyLoad.scope do
+      map(:StringIO, 'stringio')
+    end
+    
+    Lazy.map(:Tilt, 'tilt')
+  
+    Lazy::StringIO # => StringIO
+    Lazy::Tilt # => Tilt
+  end
+```
+
+Feedback and suggestions are welcome through Github.
+
+---
+
+© 2011 Jostein Berre Eliassen. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,17 @@
+
+task :test do
+  $LOAD_PATH.unshift './lib'
+  require 'lazy_load'
+  require 'minitest/autorun'
+  begin; require 'turn'; rescue LoadError; end
+  Dir.glob("test/**/*_test.rb").each { |test| require "./#{test}" }
+end
+
+task :shell do
+  system 'pry -I lib -r lazy_load --trace'
+end
+
+task :default => :test
+
+
+

data/lazy_load.gemspec

@@ -0,0 +1,28 @@
+$:.push File.expand_path('../lib', __FILE__)
+require 'lazy_load'
+
+Gem::Specification.new do |s|
+
+  s.name      = 'lazy_load'
+
+  s.author    = 'Jostein Berre Eliassen'
+  s.email     = 'josteinpost@gmail.com'
+  s.homepage  = "http://github.com/jbe/lazy_load"
+  s.license   = "MIT"
+
+  s.version   = LazyLoad::VERSION
+  s.platform  = Gem::Platform::RUBY
+
+  s.summary       = 'An unobtrusive way to autoload code with callbacks ' +
+                    'and helpful errors.'
+
+  s.description   = 'LazyLoad is a more elaborate alternative to the ' +
+                    'autoload method. For instance, it allows setting ' +
+                    'up callbacks to be invoked when a certain constant ' +
+                    'is referenced. It does not monkey patch or ' +
+                    'pollute the global namespace.'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- test/*`.split("\n")
+  s.require_path  = 'lib'
+end

data/lib/lazy_load.rb

@@ -0,0 +1,74 @@
+
+
+
+module LazyLoad
+
+  VERSION = '0.0.2'
+
+  class DependencyError < NameError;  end
+
+  module Methods
+
+    def reset!
+      @messages = {}
+      @actions  = {}
+      self
+    end
+
+    def scope(&blk)
+      mod = Module.new.extend(LazyLoad::Methods).reset!
+      mod.module_eval(&blk) if blk
+      mod
+    end
+
+    def map(name, action=nil, msg=nil, &blk)
+      @messages[name] = msg
+      @actions[name]  = blk || action || raise(
+        ArgumentError, "missing require path or callback")
+    end
+
+    def unmap(name)
+      @messages.delete(name)
+      @actions.delete(name)
+    end
+
+    def const_missing(name)
+      k = case action = @actions[name]
+        when String then helpful_require(name)
+        when Proc   then action.call
+        when nil    then super
+        else raise "Invalid action for dependency #{action.inspect}"
+      end
+      const_set(name, k)
+    end
+
+    def helpful_require(name)
+      begin
+        require @actions[name]
+        Kernel.const_get(name)
+      rescue LoadError
+        raise(DependencyError, @messages[name] ||
+          "failed to require #{@actions[name].inspect}.")
+      end
+    end
+
+    # Return the first available dependency from the
+    # list of constant names.
+    #
+    def best(*names)
+      names.each do |name|
+        begin
+          return const_get(name)
+        rescue NameError; end
+      end
+      const_get(names.first)
+    end
+    alias :first_available :best
+
+  end
+
+  extend Methods
+  reset!
+
+end
+

data/test/helper.rb

@@ -0,0 +1,15 @@
+
+class TestCase < MiniTest::Unit::TestCase
+
+  def self.test(name, &block)
+    test_name = "test_#{name.gsub(/\s+/, '_')}".to_sym
+    defined = instance_method(test_name) rescue false
+    #raise "#{test_name} already defined in #{self}" if defined
+
+    block ||= proc { skip }
+    define_method(test_name, &block)
+  end
+
+end
+
+

data/test/lazy_load_test.rb

@@ -0,0 +1,103 @@
+require File.join(File.dirname(__FILE__), 'helper')
+
+class LazyLoadTest < TestCase
+
+
+  # helpers:
+
+  def with_mappings(*args)
+    LazyLoad.map(:StringIO, 'stringio', 'stringio not in stdlib?')
+    LazyLoad.map(:Bogus, 'thishastobebogusnow', 'bogus lib not found')
+    LazyLoad.map(:Message) { 'love' }
+    LazyLoad.map(:Unavailable) do
+      raise LazyLoad::DependencyError, 'not available'
+    end
+    yield
+    LazyLoad.reset!
+  end
+
+
+  # basic
+
+  test 'raises name error' do
+    assert_raises(NameError) do
+      LazyLoad::Nonexistant
+    end
+  end
+
+  test 'requires existing' do
+    with_mappings do
+      assert LazyLoad::StringIO == StringIO
+    end
+  end
+
+  test 'require fails with message when unavailable' do
+    with_mappings do
+      assert_raises(LazyLoad::DependencyError) do
+        LazyLoad::Bogus
+      end
+    end
+  end
+
+  test 'callback' do
+    with_mappings do
+      assert LazyLoad::Message == "love"
+    end
+  end
+
+  test 'callback with dependency error' do
+    with_mappings do
+      assert_raises(LazyLoad::DependencyError) do
+        LazyLoad::Unavailable
+      end
+    end
+  end
+
+
+  # first_available
+
+  test 'returns first when first available is first' do
+    with_mappings do
+      assert_equal(
+        'love',
+        LazyLoad.best(:Message, :StringIO, :Unavailable)
+        )
+    end
+  end
+
+  test 'returns third when first available is third' do
+    with_mappings do
+      assert_equal(
+        'StringIO',
+        LazyLoad.best(:Bogus, :Unavailable, :StringIO, :Message).name
+        )
+    end
+  end
+  
+  test 'fails with first message when none available' do
+    with_mappings do
+      assert_raises LazyLoad::DependencyError do
+        LazyLoad.best(:Bogus, :Unavailable, :Bogus)
+      end
+    end
+  end
+
+
+  # new_scope
+
+  test 'scope independent of source' do
+    with_mappings do
+      scope = LazyLoad.scope
+      scope.map(:StringIO, 'not_anymore')
+
+      assert_equal('StringIO', LazyLoad::StringIO.name)
+      assert_raises(LazyLoad::DependencyError) do
+        scope::StringIO
+      end
+    end
+  end
+  
+end
+
+
+

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: lazy_load
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 2
+  version: 0.0.2
+platform: ruby
+authors: 
+- Jostein Berre Eliassen
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-06 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: LazyLoad is a more elaborate alternative to the autoload method. For instance, it allows setting up callbacks to be invoked when a certain constant is referenced. It does not monkey patch or pollute the global namespace.
+email: josteinpost@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- CHANGELOG
+- LICENSE
+- README.md
+- Rakefile
+- lazy_load.gemspec
+- lib/lazy_load.rb
+- test/helper.rb
+- test/lazy_load_test.rb
+has_rdoc: true
+homepage: http://github.com/jbe/lazy_load
+licenses: 
+- MIT
+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: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: An unobtrusive way to autoload code with callbacks and helpful errors.
+test_files: 
+- test/helper.rb
+- test/lazy_load_test.rb