lazy_load 0.0.3 → 0.1.0

data/CHANGELOG

@@ -1,7 +1,13 @@
 
 HEAD
 
-
+0.1.0
+  deprecate custom msgs and errors
+  let LoadErrors pass
+  deprecate #map
+  alias #dep to #const
+  LazyLoad::Mixin
+  wrapper support
 
 0.0.3
   alias #map to #dep

data/README.md

@@ -2,13 +2,17 @@
 LazyLoad
 ========
 
-**Unobtrusively autoload code with callbacks and helpful errors**
+**Autoload with custom callbacks**
 
 ---
 
-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.
+LazyLoad is a slightly more elaborate alternative to [autoload](http://ruby-doc.org/core/classes/Module.html#M000443). It helps deal with "soft" dependencies, where dependencies are "preferred", rather than strictly needed. It is very simple, but provides:
 
-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.
+* Custom callbacks
+* "Best available" dependency selection
+* A simple, optional wrapper mechanism
+
+Unlike [autoload](http://ruby-doc.org/core/classes/Module.html#M000443), LazyLoad is scoped. This means that when you register a callback for the `Foo` constant, referencing `LazyLoad::Foo` will trigger the callback. Simply referencing `Foo` will not trigger the callback. In other words, internals are not monkey patched. However, you can also use it as a mixin, thereby eliminating the verbosity.
 
 ### Samples
 
@@ -20,72 +24,91 @@ Unlike autoload, LazyLoad is scoped, and it does therefore not pollute or monkey
 
 ```ruby
 
-  LazyLoad.map(:Tilt, 'tilt',
-    'Tilt not found. Possible fix: gem install tilt')
+  # same as as autoload:
 
-  # or equivalent with a callback:
+  LazyLoad.const(:Tilt, 'tilt')
 
-  LazyLoad.map(:Tilt) do
-    begin
-      require 'tilt'
-      Tilt
-    rescue LoadError
-      raise(LazyLoad::DependencyError,
-        'Tilt not found. Possible fix: gem install tilt')
-    end
-  end
+  # or the equivalent with a callback:
 
-  Tilt
-  # => NameError: uninitialized constant Object::Tilt
+  LazyLoad.const(:Tilt) do
+    require 'tilt'
+    Tilt
+  end
 
-  LazyLoad::Tilt
-  # => Tilt
+  # lets you..
 
-  # or if Tilt is not available:
-  
-  LazyLoad::Tilt
-  # => LazyLoad::DependencyError: Tilt not found. Possible fix: gem install tilt'
+  LazyLoad::Tilt # => Tilt (or LoadError)
 
-  LazyLoad::Foo
-  # => NameError: uninitialized constant LazyLoad::Foo
+  LazyLoad::Oboe
+  # => NameError: uninitialized constant LazyLoad::Oboe
 
 ```
 
-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 a 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`.
+Note that the return value of the callback becomes the constant. Any object can be returneed.
 
 
 ### 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.
+You can use the `best` method to return the first constant for which the callback does not raise a `LoadError`, or else raise the `LoadError` of the first (most preferred) constant:
 
 ```ruby
+
     LazyLoad.best(:Kramdown, :RDiscount, :Redcarpet)
 
+    # or using named groups:
+
+    LazyLoad.group(:markdown, :Kramdown, :RDiscount, :Redcarpet)
+    LazyLoad.best(:markdown)
+
 ```
 
+### Mixin
+
+You can endow objects with the LazyLoad methods by extending the `LazyLoad::Mixin.` Each object will have its own scope of callbacks.
+
+```ruby
+
+  module WidgetFactoryFactory
+
+    extend LazyLoad::Mixin
+
+    const :Haml, 'haml'
 
-### Scopes
+    Haml # => Haml
 
-Use the `scope` method if you need more than one scope (typically for gem interoperability).
+  end
+
+```
+
+### Wrappers
+
+LazyLoad has super simple wrapper support, which lets you quickly define wrapper classes that are automatically wrapped around their corresponding constants. These wrappers get a default `initialize` method, which sets `@wrapped` to the object they wrap, and are set to forward method calls there using `method_missing`.
 
 ```ruby
-  module SomeProject
-    Lazy = LazyLoad.scope do
-      map(:StringIO, 'stringio')
+
+  LazyLoad.wrapper(:RDiscount) do
+
+    def new(*args)
+      InstanceWrapper.new(super(*args))
     end
-    
-    Lazy.map(:Tilt, 'tilt')
-  
-    Lazy::StringIO # => StringIO
-    Lazy::Tilt # => Tilt
+
+    class InstanceWrapper < LazyLoad::Wrapper
+
+      def render(*args); to_html(*args); end
+
+      def go_shopping
+        puts 'sure, why not'
+      end
+
+    end
+
   end
+
 ```
 
+
+&nbsp;
+
 Feedback and suggestions are welcome through Github.
 
 ---

data/lazy_load.gemspec

@@ -13,14 +13,12 @@ Gem::Specification.new do |s|
   s.version   = LazyLoad::VERSION
   s.platform  = Gem::Platform::RUBY
 
-  s.summary       = 'An unobtrusive way to autoload code with callbacks ' +
-                    'and helpful errors.'
+  s.summary       = 'Autoload with custom callbacks.'
 
-  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.description   = %{LazyLoad is a slightly more elaborate alternative
+                    to the autoload method. It provides custom callbacks,
+                    "best available" dependency selection, and an optional
+                    simple wrapper mechanism.}
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- test/*`.split("\n")

data/lib/lazy_load.rb

@@ -3,86 +3,94 @@
 
 module LazyLoad
 
-  VERSION = '0.0.3'
+  VERSION = '0.1.0'
 
-  class DependencyError < NameError;  end
-
-  module Methods
+  module Mixin
 
     def reset!
-      @messages = {}
       @actions  = {}
       @groups   = {}
+      @wrappers = {}
       self
     end
 
+    def self.extended(obj)
+      obj.reset!
+    end
+
     def scope(&blk)
-      mod = Module.new.extend(LazyLoad::Methods).reset!
+      mod = Module.new.extend(LazyLoad::Mixin).reset!
       mod.module_eval(&blk) if blk
       mod
     end
 
-    def map(name, action=nil, msg=nil, &blk)
-      @messages[name] = msg
+    def const(name, action=nil, &blk)
       @actions[name]  = blk || action || raise(
         ArgumentError, "missing require path or callback")
     end
+    alias :dep :const
 
     def group(name, *constants)
       @groups[name] = constants
     end
 
-    alias :dep :map
-
     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
+        when String
+          require @actions[name]
+          Kernel.const_get(name)
         else raise "Invalid action for dependency #{action.inspect}"
       end
+      k = @wrappers[name].new(k) if @wrappers[name]
       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)
-      expand_groups(names).each do |name|
+      names.map do |name|
+        @groups[name] || name
+      end.flatten.each do |name|
         begin
           return const_get(name)
-        rescue NameError; end
+        rescue NameError, LoadError; end
       end
       const_get(names.first)
     end
     alias :first_available :best
     alias :[] :best
 
-    def expand_groups(names)
-      names.map do |name|
-        @groups[name] || name
-      end.flatten
+    def wrap(name, &blk)
+      kls = Class.new(Wrapper)
+      kls.class_eval(&blk)
+      @wrappers[name] = kls
+    end
+
+    class Wrapper
+      def initialize(wrapped)
+        @wrapped = wrapped
+      end
+      attr_reader :wrapped
+
+      def method_missing(*args)
+        @wrapped.send(*args)
+      end
+
+      def respond_to?(name)
+        super || @wrapped.respond_to?(name)
+      end
     end
 
   end
 
-  extend Methods
-  reset!
+  extend Mixin
 
 end
 

data/test/lazy_load_test.rb

@@ -6,15 +6,28 @@ 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'
+
+    mappings = Proc.new do
+      const(:StringIO, 'stringio')
+      const(:Bogus, 'thishastobebogusnow')
+      const(:Message) { 'love' }
+      const(:Boat) { 'sank' }
+      const(:Unavailable) { raise LoadError, 'not available' }
+      group(:test_grp, :Bogus, :Unavailable, :Message)
+      wrap(:Boat) { def actually; 'floats'; end }
     end
-    LazyLoad.group(:test_grp, :Bogus, :Unavailable, :Message)
-    yield
+
+    LazyLoad.module_eval(&mappings)
+    yield(LazyLoad)
     LazyLoad.reset!
+
+    yield LazyLoad.scope(&mappings)
+
+    mod = Module.new
+    mod.extend(LazyLoad::Mixin)
+    mod.module_eval(&mappings)
+    yield mod
+
   end
 
 
@@ -27,29 +40,29 @@ class LazyLoadTest < TestCase
   end
 
   test 'requires existing' do
-    with_mappings do
-      assert LazyLoad::StringIO == StringIO
+    with_mappings do |ll|
+      assert ll::StringIO == StringIO
     end
   end
 
   test 'require fails with message when unavailable' do
-    with_mappings do
-      assert_raises(LazyLoad::DependencyError) do
-        LazyLoad::Bogus
+    with_mappings do |ll|
+      assert_raises(LoadError) do
+        ll::Bogus
       end
     end
   end
 
   test 'callback' do
-    with_mappings do
-      assert LazyLoad::Message == "love"
+    with_mappings do |ll|
+      assert ll::Message == "love"
     end
   end
 
   test 'callback with dependency error' do
-    with_mappings do
-      assert_raises(LazyLoad::DependencyError) do
-        LazyLoad::Unavailable
+    with_mappings do |ll|
+      assert_raises(LoadError) do
+        ll::Unavailable
       end
     end
   end
@@ -58,27 +71,30 @@ class LazyLoadTest < TestCase
   # first_available
 
   test 'returns first when first available is first' do
-    with_mappings do
+    with_mappings do |ll|
       assert_equal(
         'love',
-        LazyLoad.best(:Message, :StringIO, :Unavailable)
+        ll.best(:Message, :StringIO, :Unavailable)
         )
     end
   end
 
   test 'returns third when first available is third' do
-    with_mappings do
+    with_mappings do |ll|
       assert_equal(
         'StringIO',
-        LazyLoad.best(:Bogus, :Unavailable, :StringIO, :Message).name
+        ll.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)
+    with_mappings do |ll|
+      assert_raises LoadError do
+        ll.best(:Bogus, :Air, :Unavailable, :Bogus)
+      end
+      assert_raises NameError do
+        ll.best(:Air, :Bogus, :Unavailable, :Bogus)
       end
     end
   end
@@ -87,20 +103,25 @@ class LazyLoadTest < TestCase
   # new_scope
 
   test 'scope independent of source' do
-    with_mappings do
-      scope = LazyLoad.scope
-      scope.map(:StringIO, 'not_anymore')
+    with_mappings do |ll|
+      scope = ll.scope
+      scope.const(:StringIO, 'not_anymore')
 
-      assert_equal('StringIO', LazyLoad::StringIO.name)
-      assert_raises(LazyLoad::DependencyError) do
-        scope::StringIO
-      end
+      assert_equal('StringIO', ll::StringIO.name)
+      assert_raises(LoadError) { scope::StringIO }
     end
   end
 
   test 'groups' do
-    with_mappings do
-      assert_equal 'love', LazyLoad[:test_grp]
+    with_mappings do |ll|
+      assert_equal 'love', ll[:test_grp]
+    end
+  end
+
+  test 'wrapper' do
+    with_mappings do |ll|
+      assert_equal 'sank',   ll::Boat.wrapped
+      assert_equal 'floats', ll::Boat.actually
     end
   end
   

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 3
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors: 
 - Jostein Berre Eliassen
@@ -18,7 +18,11 @@ date: 2011-06-23 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.
+description: |-
+  LazyLoad is a slightly more elaborate alternative
+                      to the autoload method. It provides custom callbacks,
+                      "best available" dependency selection, and an optional
+                      simple wrapper mechanism.
 email: josteinpost@gmail.com
 executables: []
 
@@ -67,7 +71,7 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: An unobtrusive way to autoload code with callbacks and helpful errors.
+summary: Autoload with custom callbacks.
 test_files: 
 - test/helper.rb
 - test/lazy_load_test.rb