lazy_methods 1.0.2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Brian Durand
+
+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

@@ -0,0 +1,37 @@
+== LazyMethods
+
+So your Rails application is successful beyond your wildest dreams and now your meager servers are straining under the load. You figure you'll add some caching to your views and all will be well again. Unfortunately, your controller actions load up all sorts of instance variables with records from the database. The caching won't do you much good if your database is still getting slammed. You could move your query logic to the views behind the caching layer, but that just feels icky. Besides, that will break all your tests and you really don't feel like fixing them.
+
+== Enter LazyMethods.
+
+This plugin adds a virtual lazy version of every method on every class. Lazy methods have the same name as the original method name but prefixed with "lazy_". A lazy method will return a proxy object that looks and acts just like the result from calling the actual method. The trick is that the actual method will not be called until a method is invoked on the proxy object. This way you can continue to set up the business logic in your controller and have it only actually executed only as needed.
+
+If you add fragment caching to your views and the cache returns a value and bypasses your view code, the method will never be invoked. Thanks to the magic of Ruby the proxy object will even act like the class it is proxying in class to class and kind_of?
+
+A simple example:
+
+The normal way to do it (at least according to every tutorial):
+
+  def index
+	  @records = MyRecord.find(:all, :conditions => {:name => params[:name]})
+  end
+
+And in the view:
+
+	<% cache(params[:names]) -%>
+		<% @records.each do |record| -%>
+			<div><%=record.title%></div>
+		<% end -%>
+	<% end -%>
+
+Now even if you cache the fragments in your view that use @records, the database will still be hit to select and instantiate all the records. You could remove the code from the action and simple add it back into the view. However, this just feels wrong and is inherently harder to test. Instead just use a lazy method.
+
+	def index
+		@records = MyRecord.lazy_find(:all, :conditions => {:name => params[:name]})
+	end
+
+Now, as long as no methods are invoked on @records, the original find method will never be called. As soon as the first method is called, the original find method will be called. It will never be called more than once. You can even pass in a block to the lazy method.
+
+== Testing
+
+Since the proxy object looks and acts just like the real result object, all your view tests should still pass. Your controller tests should pass will little or no tweaking.

data/Rakefile

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'spec/rake/spectask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the lazy_methods plugin.'
+Spec::Rake::SpecTask.new(:test) do |t|
+  t.spec_files = 'spec/**/*_spec.rb'
+end
+
+desc 'Generate documentation for the lazy_methods plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.options << '--title' << 'LazyMethods' << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s| 
+  s.name = "lazy_methods"
+  s.version = "1.0.2"
+  s.author = "Brian Durand"
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Provide lazy method calls for all methods on every object to aid in caching."
+  s.files = FileList["lib/**/*", "MIT-LICENSE", 'Rakefile'].to_a
+  s.require_path = "lib"
+  s.test_files = FileList["{spec}/**/*.rb"].to_a
+  s.has_rdoc = true
+  s.rdoc_options << '--title' << 'LazyMethods' << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  s.extra_rdoc_files = ["README"]
+  s.homepage = "http://lazymethods.rubyforge.org"
+  s.rubyforge_project = "lazymethods"
+  s.email = 'brian@embellishedvisions.com'
+end
+ 
+Rake::GemPackageTask.new(spec) do |pkg| 
+  pkg.need_tar = true 
+end
+

data/lib/lazy_methods/lazy_methods.rb

@@ -0,0 +1,82 @@
+# Including this module will provide the lazy method handling for the class where any method can be
+# prefixed with lazy_ to defer execution. By default, the plugin includes it in Object so it is universally
+# available.
+module LazyMethods
+  
+  module InstanceMethods
+    def self.included (base)
+      base.send :alias_method, :method_missing_without_lazy, :method_missing
+      base.send :alias_method, :method_missing, :method_missing_with_lazy
+    end
+    
+    # Override missing method to add the lazy method handling
+    def method_missing_with_lazy (method, *args, &block)
+      if method.to_s[0, 5] == 'lazy_'
+        method = method.to_s
+        return Proxy.new(self, method[5, method.length].to_sym, args, &block)
+      else
+        # Keep track of the current missing method calls to keep out of an infinite loop
+        stack = Thread.current[:lazy_method_missing_methods] ||= []
+        sig = MethodSignature.new(self, method)
+        raise NoMethodError.new("undefined method `#{method}' for #{self}") if stack.include?(sig)
+        begin
+          stack.push(sig)
+          return method_missing_without_lazy(method, *args, &block)
+        ensure
+          stack.pop
+        end
+      end
+    end
+  end
+  
+  # This class is used to keep track of methods being called.
+  class MethodSignature
+    
+    attr_reader :object, :method
+    
+    def initialize (obj, method)
+      @object = obj
+      @method = method
+    end
+    
+    def eql? (sig)
+      sig.kind_of(MethodSignature) and sig.object == @object and sig.method == @method
+    end
+    
+  end
+  
+  # The proxy object does all the heavy lifting.
+  class Proxy
+    # These methods we don't want to override. All other existing methods will be redefined.
+    PROTECTED_METHODS = %w(initialize __proxy_result__ __proxy_loaded__ method_missing)
+    
+    def initialize (obj, method, args = nil, &block)
+      @object = obj
+      @method = method
+      @args = args || []
+      @block = block
+      
+      # Override already defined methods on Object to proxy them to the result object
+      methods.each do |m|
+        eval "def self.#{m} (*args, &block); __proxy_result__.send(:#{m}, *args, &block); end" unless PROTECTED_METHODS.include?(m)
+      end
+    end
+    
+    # Get the result of the original method call. The original method will only be called once.
+    def __proxy_result__
+      @proxy_result = @object.send(@method, *@args, &@block) unless defined?(@proxy_result)
+      @proxy_result
+    end
+    
+    # Helper method that indicates if the proxy has loaded the original method results yet.
+    def __proxy_loaded__
+      !!defined?(@proxy_result)
+    end
+    
+    # All missing methods are proxied to the original result object.
+    def method_missing (method, *args, &block)
+      __proxy_result__.send(method, *args, &block)
+    end
+  end
+  
+end

data/lib/lazy_methods.rb

@@ -0,0 +1,2 @@
+require 'lazy_methods/lazy_methods'
+Object.send(:include, LazyMethods::InstanceMethods) unless Object.include?(LazyMethods::InstanceMethods)

data/spec/lazy_method_spec.rb

@@ -0,0 +1,101 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'lazy_methods', 'lazy_methods'))
+Object.send(:include, LazyMethods::InstanceMethods) unless Object.include?(LazyMethods::InstanceMethods)
+require File.expand_path(File.dirname(__FILE__) + '/method_tester')
+
+context "LazyMethods InstanceMethods" do
+  
+  setup do
+    @object = MethodTester.new
+  end
+  
+  specify "should inject lazy method handling" do
+    proxy = @object.lazy_test("arg")
+    proxy.to_s.should == "ARG"
+    proxy.__proxy_loaded__.should == true
+  end
+  
+  specify "should return a proxy object that has not been invoked yet" do
+    proxy = @object.lazy_test("arg")
+    proxy.__proxy_loaded__.should == false
+  end
+  
+end
+
+context "LazyMethods Proxy" do
+  
+  setup do
+    @object = MethodTester.new
+  end
+  
+  specify "should be able to wrap a method without executing it" do
+    proxy = @object.lazy_test("arg")
+    @object.test_called.should == 0
+  end
+  
+  specify "should execute the wrapped method when it needs to" do
+    proxy = @object.lazy_test("arg")
+    proxy.to_s
+    @object.test_called.should == 1
+  end
+  
+  specify "should only execute the wrapped method once" do
+    proxy = @object.lazy_test("arg")
+    proxy.to_s
+    proxy.to_s
+    @object.test_called.should == 1
+  end
+  
+  specify "should allow nil as a valid proxied value" do
+    proxy = @object.lazy_test(nil)
+    proxy.should_not
+    @object.test_called.should == 1
+  end
+  
+  specify "should allow blocks in the lazy method" do
+    n = 1
+    proxy = @object.lazy_test("arg") do
+      n = 2
+    end
+    n.should == 1
+    proxy.to_s
+    n.should == 2
+  end
+  
+  specify "should be indistinguishable from the real object" do
+    proxy = @object.lazy_test("arg")
+    proxy.class.should == String
+    proxy.kind_of?(String).should == true
+  end
+  
+  specify "should proxy core methods on Object" do
+    proxy = "xxx".lazy_to_s
+    proxy.should == "xxx"
+  end
+  
+  specify "should proxy missing methods" do
+    proxy = @object.lazy_find_test
+    proxy.to_s.should == "FINDER"
+  end
+  
+  specify "should allow blocks in the lazy missing methods" do
+    n = 1
+    proxy = @object.lazy_find_test do
+      n = 2
+    end
+    n.should == 1
+    proxy.to_s
+    n.should == 2
+  end
+  
+  specify "should not interfere with the proxied object's method_missing" do
+    real = @object.find_test
+    real.to_s.should == "FINDER"
+  end
+  
+  specify "should not interfere with real methods that begin with lazy_" do
+    @object.lazy_real_method_called.should == false
+    @object.lazy_real_method
+    @object.lazy_real_method_called.should == true
+  end
+  
+end

data/spec/method_tester.rb

@@ -0,0 +1,31 @@
+# This class is used for testing the lazy_methods plugin functionality.
+
+class MethodTester
+  
+  attr_reader :test_called, :lazy_real_method_called
+  
+  def initialize
+    @test_called = 0
+    @lazy_real_method_called = false
+  end
+  
+  def test (arg)
+    @test_called += 1
+    yield if block_given?
+    arg.upcase if arg
+  end
+  
+  def lazy_real_method
+    @lazy_real_method_called = true
+  end
+  
+  def method_missing (method, *args, &block)
+    if method.to_s.starts_with?('find_')
+      yield if block_given?
+      "FINDER"
+    else
+      super
+    end
+  end
+  
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+name: lazy_methods
+version: !ruby/object:Gem::Version 
+  version: 1.0.2
+platform: ruby
+authors: 
+- Brian Durand
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-01-17 00:00:00 -06:00
+default_executable: 
+dependencies: []
+
+description: 
+email: brian@embellishedvisions.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/lazy_methods
+- lib/lazy_methods.rb
+- lib/lazy_methods/lazy_methods.rb
+- MIT-LICENSE
+- Rakefile
+- README
+has_rdoc: true
+homepage: http://lazymethods.rubyforge.org
+post_install_message: 
+rdoc_options: 
+- --title
+- LazyMethods
+- --line-numbers
+- --inline-source
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: lazymethods
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: Provide lazy method calls for all methods on every object to aid in caching.
+test_files: 
+- spec/lazy_method_spec.rb
+- spec/method_tester.rb