expiration-date 1.0.1 → 1.1.0

data/History.txt

@@ -1,6 +1,11 @@
+== 1.1.0 / 2008-08-25
+
+* 1 minor enhancement
+  * added expiring class attributes
+
 == 1.0.1 / 2008-08-23
 
-- 1 bug fix
+* 1 bug fix
   * ensuring the block executes in the context of the
     instance and not the class
 

data/Manifest.txt

@@ -1,6 +1,7 @@
+.gitignore
 History.txt
 Manifest.txt
-README.txt
+README.rdoc
 Rakefile
 lib/expiration-date.rb
 spec/expiration-date_spec.rb

data/{README.txt → README.rdoc}

@@ -5,36 +5,17 @@
 
 == DESCRIPTION:
 
-Wandering the grocery aisle the other day I saw a package of bacon with a neon
-green sticker screaming for all to hear "THIS BACON ONLY COSTS ONE DOLLAR!!!".
-Screaming bacon always intrigues me, so I grabbed the nearest store manager. He
-works at the coffee shop next door, but when I told him about the screaming
-bacon he had to come and see for himself.
-
-"Oh, it's a manager's special" he told me. "When products get too old the
-manager will reduce the price so they sell more quickly. This allows new
-products to be put on the shelves, and the store can make some money instead of
-throwing out the expired products".
-
-I stared at him blankly. He wandered back to the coffee shop and had a latte.
-
-I continued to stand there thinking about expiring products and how Ruby could
-benefit from neon green stickers and stale bacon. Eventually the grocery
-store manager came by and asked me if everything was okay. I grabbed him by the
-collar, pointed at the bacon and yelled "DO YOU KNOW WHAT THIS MEANS!?!?". I
-ran from the store, grabbed my laptop, and whipped up this little gem.
+Really simple caching by attaching an expiration date to attributes.
 
-EXPIRATION DATE (now with more neon green).
+The ExpirationDate module adss two methods to a class -- expiring_attr and
+expiring_class_attr. These two methods are used to declare attributes in the
+instance and in the class, respectively, that will expire after some period of
+seconds have elapsed. The attribute is re-initialized from the given block
+after it has expired. This is a very simple form of caching.
 
-Now ruby can expire it's bacon, too, just like the grocery store, and make room
-for more bacon from the delivery truck.
 
 == SYNOPSIS:
 
-The ExpirationDate module adds the "expiring_attr" method to a class. This
-method is used to define an attribute that will expire after some period of
-seconds have elapsed.
-
 A simple example demonstrating how the block gets called after the expiration
 time is passed.
 
@@ -45,14 +26,9 @@ time is passed.
 
   a = A.new
   a.foo                  #=> 'foo'
-  a.foo.object_id        #=> 123456
-  a.foo.object_id        #=> 123456
-
-  sleep 61
-  a.foo.object_id        #=> 654321
-
   a.foo = 'bar'
   a.foo                  #=> 'bar'
+
   sleep 61
   a.foo                  #=> 'foo'
 
@@ -62,13 +38,15 @@ database every five minutes. This assumes you have the 'activesupport' and
 
   class MyModel < ::ActiveRecord::Base
     include ExpirationDate
-    expiring_attr( :costly_data, 5.minutes ) {
+    expiring_class_attr( :costly_data, 5.minutes ) {
       models = MyModel.find( :all, :conditions => ['costly query conditions'] )
       result = models.map {|m| # costly operations here}
       result
     }
   end
 
+  MyModel.costly_data    #=> result
+
 Attributes can be expired manually, and the time it takes them to expire can be
 modified as well.
 
@@ -83,11 +61,11 @@ modified as well.
   sleep 60
   demo.bar               #=> 60 seconds ago
 
-  demo.expire_now(:bar)
+  demo.expire_bar_now
   demo.bar               #=> now
 
-  demo.alter_expiration_label(:bar, 10)
-  demo.expire_now(:bar)
+  demo.alter_bar_age( 10 )
+  demo.expire_bar_now
   demo.bar               #=> now
   sleep 11
   demo.bar               #=> now
@@ -100,6 +78,32 @@ This is a pure ruby library. There are no requirements for using this code.
 
   sudo gem install expiration-date
 
+== FUN STORY:
+
+Wandering the grocery aisle the other day I saw a package of bacon with a neon
+green sticker screaming for all to hear "THIS BACON ONLY COSTS ONE DOLLAR!!!".
+Screaming bacon always intrigues me, so I grabbed the nearest store manager. He
+works at the coffee shop next door, but when I told him about the screaming
+bacon he had to come and see for himself.
+
+"Oh, it's a manager's special" he told me. "When products get too old the
+manager will reduce the price so they sell more quickly. This allows new
+products to be put on the shelves, and the store can make some money instead of
+throwing out the expired products".
+
+I stared at him blankly. He wandered back to the coffee shop and had a latte.
+
+I continued to stand there thinking about expiring products and how Ruby could
+benefit from neon green stickers and stale bacon. Eventually the grocery
+store manager came by and asked me if everything was okay. I grabbed him by the
+collar, pointed at the bacon and yelled "DO YOU KNOW WHAT THIS MEANS!?!?". I
+ran from the store, grabbed my laptop, and whipped up this little gem.
+
+EXPIRATION DATE (now with more neon green).
+
+Now ruby can expire it's bacon, too, just like the grocery store, and make room
+for more bacon from the delivery truck.
+
 == LICENSE:
 
 The MIT License

data/Rakefile

@@ -14,7 +14,9 @@ PROJ.url = 'http://codeforpeople.rubyforge.org/expiration-date'
 PROJ.rubyforge.name = 'codeforpeople'
 PROJ.rdoc.remote_dir = 'expiration-date'
 PROJ.version = ExpirationDate::VERSION
-PROJ.release_name = 'Buggy Bacon'
+PROJ.release_name = 'Screaming Bacon'
+PROJ.readme_file = 'README.rdoc'
+PROJ.rdoc.include << 'README.rdoc'
 
 PROJ.spec.opts << '--color'
 

data/lib/expiration-date.rb

@@ -4,7 +4,7 @@ require 'thread'
 module ExpirationDate
 
   # :stopdoc:
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
   ExpirationLabel = Struct.new(:mutex, :age, :expires_on)
   # :startdoc:
 
@@ -28,7 +28,9 @@ module ExpirationDate
     # Declares a new instance attribute that will expire after _age_ seconds
     # and be replaced by the results of running the _block_. The block is
     # lazily evaluated when the attribute is accessed after the expiration
-    # time.
+    # time. The block is evaluated in the context of the instance (as
+    # opposed to being evaluated in the context of the class where the block
+    # is declared).
     #
     # Obviously this scheme will only work if the attribute is only accessed
     # using the setter and getter methods defined by this function.
@@ -39,9 +41,11 @@ module ExpirationDate
     #   end
     #
     #   a = A.new
-    #   a.foo.object_id    #=> 123456
+    #   a.foo              #=> 'foo'
+    #   a.foo = 'bar'
+    #   a.foo              #=> 'bar'
     #   sleep 61
-    #   a.foo.object_id    #=> 654321
+    #   a.foo              #=> 'foo'
     #
     def expiring_attr( name, age, &block )
       raise ArgumentError, "a block must be given" if block.nil?
@@ -53,7 +57,7 @@ module ExpirationDate
       self.class_eval <<-CODE, __FILE__, __LINE__
         def #{name}
           now = Time.now
-          label = expiration_labels[#{name.inspect}]
+          label = _expiration_labels[#{name.inspect}]
           if label.expires_on.nil? || now >= label.expires_on
             label.mutex.synchronize {
               break unless label.expires_on.nil? || now >= label.expires_on
@@ -68,7 +72,7 @@ module ExpirationDate
 
         def #{name}=( val )
           now = Time.now
-          label = expiration_labels[#{name.inspect}]
+          label = _expiration_labels[#{name.inspect}]
           label.mutex.synchronize {
             @#{name} = val
             label.age ||= #{age}
@@ -76,6 +80,83 @@ module ExpirationDate
           }
           @#{name}
         end
+
+        def expire_#{name}_now
+          label = _expiration_labels[#{name.inspect}]
+          label.mutex.synchronize {label.expires_on = Time.now - 1}
+          @#{name}
+        end
+
+        def alter_#{name}_age( age )
+          label = _expiration_labels[#{name.inspect}]
+          label.mutex.synchronize {label.age = Float(age)}
+        end
+      CODE
+    end
+
+    # Declares a new class attribute that will expire after _age_ seconds
+    # and be replaced by the results of running the _block_. The block is
+    # lazily evaluated when the attribute is accessed after the expiration
+    # time. The block is evaluated in the context of the class.
+    #
+    # Obviously this scheme will only work if the attribute is only accessed
+    # using the setter and getter methods defined by this function.
+    #
+    #   class A
+    #     include ExpirationDate
+    #     expiring_class_attr( :foo, 60 ) { 'foo' }
+    #   end
+    #
+    #   A.foo              #=> 'foo'
+    #   A.foo = 'bar'
+    #   A.foo              #=> 'bar'
+    #   sleep 61
+    #   A.foo              #=> 'foo'
+    #
+    def expiring_class_attr( name, age, &block )
+      raise ArgumentError, "a block must be given" if block.nil?
+
+      name = name.to_sym
+      age = Float(age)
+      _class_managers_specials[name] = block
+
+      self.class_eval <<-CODE, __FILE__, __LINE__
+        def self.#{name}
+          now = Time.now
+          label = _class_expiration_labels[#{name.inspect}]
+          if label.expires_on.nil? || now >= label.expires_on
+            label.mutex.synchronize {
+              break unless label.expires_on.nil? || now >= label.expires_on
+              block = ::#{self.name}._class_managers_specials[#{name.inspect}]
+              @#{name} = instance_eval(&block)
+              label.age ||= #{age}
+              label.expires_on = now + label.age
+            }
+          end
+          @#{name}
+        end
+
+        def self.#{name}=( val )
+          now = Time.now
+          label = _class_expiration_labels[#{name.inspect}]
+          label.mutex.synchronize {
+            @#{name} = val
+            label.age ||= #{age}
+            label.expires_on = now + label.age
+          }
+          @#{name}
+        end
+
+        def self.expire_#{name}_now
+          label = _class_expiration_labels[#{name.inspect}]
+          label.mutex.synchronize {label.expires_on = Time.now - 1}
+          @#{name}
+        end
+
+        def self.alter_#{name}_age( age )
+          label = _class_expiration_labels[#{name.inspect}]
+          label.mutex.synchronize {label.age = Float(age)}
+        end
       CODE
     end
 
@@ -86,55 +167,23 @@ module ExpirationDate
     def _managers_specials
       @_managers_specials ||= Hash.new
     end
-    # :startdoc:
-  end
 
-  # Immediately expire an attribute so that it will be refreshed the next
-  # time it is requested.
-  #
-  #    expire_now( :foo )
-  #
-  def expire_now( name )
-    name = name.to_sym
-    if expiration_labels.key?(name)
-      now = Time.now
-      label = expiration_labels[name]
-      label.mutex.synchronize {
-        label.expires_on = now - 1
-      }
+    def _class_managers_specials
+      @_class_managers_specials ||= Hash.new
     end
-  end
 
-  # Alter the _age_ of the named attribute. This new age will be used the
-  # next time the attribute expries to determine the new expiration date --
-  # i.e. the new age does not immediately take effect. You will need to
-  # manually expire the attribute if you want the new age to take effect
-  # immediately.
-  #
-  # Modify the 'foo' attribute so that it expires every 60 seconds.
-  #
-  #    alter_expiration_label( :foo, 60 )
-  #
-  # Modify the 'bar' attribute so that it expires every two minutes. Make
-  # this new age take effect immediately.
-  #
-  #    alter_expiration_label( :bar, 120 )
-  #    expire_now( :bar )
-  #
-  def alter_expiration_label( name, age )
-    name = name.to_sym
-    if expiration_labels.key?(name)
-      label = expiration_labels[name]
-      label.mutex.synchronize {
-        label.age = Float(age)
-      }
+    def _class_expiration_labels
+      @_class_expiration_labels ||= Hash.new do |h,k|
+        h[k] = ExpirationLabel.new(Mutex.new)
+      end
     end
+    # :startdoc:
   end
 
   # Accessor that returns the hash of ExpirationLabel objects.
   #
-  def expiration_labels
-    @expiration_labels ||= Hash.new do |h,k|
+  def _expiration_labels
+    @_expiration_labels ||= Hash.new do |h,k|
       h[k] = ExpirationLabel.new(Mutex.new)
     end
   end

data/spec/expiration-date_spec.rb

@@ -7,8 +7,11 @@ class TestA
   expiring_attr(:foo,  0.5) { 'foo' }
   expiring_attr('bar', 10 ) { 'bar' }
   expiring_attr(:me,   60 ) { self  }
-end
 
+  expiring_class_attr(:foo,  0.5) { 'class foo' }
+  expiring_class_attr('bar', 10 ) { 'class bar' }
+  expiring_class_attr(:me,   60 ) { self  }
+end
 
 describe ExpirationDate do
   it 'returns the same attribute before the expiration time' do
@@ -35,7 +38,7 @@ describe ExpirationDate do
     bar.should be_equal(a.bar)
     bar.should == 'bar'
 
-    a.expire_now(:bar)
+    a.expire_bar_now
     bar.should_not be_equal(a.bar)
     a.bar.should == 'bar'
   end
@@ -53,20 +56,20 @@ describe ExpirationDate do
     a.foo.should == 'foo'
   end
 
-  it 'can alter an expiration label' do
+  it "can alter an attribute's age" do
     a = TestA.new
     bar = a.bar
     bar.should be_equal(a.bar)
     bar.should == 'bar'
 
     # this alteration takes place only after the attribute expires
-    a.alter_expiration_label('bar', 0.5)
+    a.alter_bar_age 0.5
 
     sleep 0.75
     bar.should be_equal(a.bar)
 
     # so now the age should only be 0.5 seconds
-    a.expire_now(:bar)
+    a.expire_bar_now
     bar.should_not be_equal(a.bar)
     a.bar.should == 'bar'
 
@@ -74,23 +77,75 @@ describe ExpirationDate do
     bar.should_not be_equal(a.bar)
   end
 
-  it 'ignores requests on unknown expriation labels' do
-    a = TestA.new
-
-    h = a.expiration_labels
-    h.keys.length == 2
-
-    a.expire_now(:foobar)
-    h.keys.length == 2
-
-    a.alter_expiration_label(:foobar, 42)
-    h.keys.length == 2
-  end
-
   it 'executes the block in the context of the instance' do
     a = TestA.new
     a.me.should be_equal(a)
   end
+
+  describe 'when used at the class level' do
+    it 'returns the same attribute before the expiration time' do
+      foo = TestA.foo
+      foo.should be_equal(TestA.foo)
+      foo.should == 'class foo'
+    end
+
+    it 'returns a new attribute after the expiration time' do
+      foo = TestA.foo
+      foo.should be_equal(TestA.foo)
+      foo.should == 'class foo'
+
+      sleep 0.75
+      foo.should_not be_equal(TestA.foo)
+      TestA.foo.should == 'class foo'
+    end
+
+    it 'can immediately expire an attribute' do
+      bar = TestA.bar
+      bar.should be_equal(TestA.bar)
+      bar.should == 'class bar'
+
+      TestA.expire_bar_now
+      bar.should_not be_equal(TestA.bar)
+      TestA.bar.should == 'class bar'
+    end
+
+    it 'can assign an attribute' do
+      TestA.foo.should == 'class foo'
+
+      foobar = 'foobar'
+      TestA.foo = foobar
+      TestA.foo.should be_equal(foobar)
+
+      sleep 0.75
+      TestA.foo.should_not be_equal(foobar)
+      TestA.foo.should == 'class foo'
+    end
+
+    it "can alter an attribute's age" do
+      bar = TestA.bar
+      bar.should be_equal(TestA.bar)
+      bar.should == 'class bar'
+
+      # this alteration takes place only after the attribute expires
+      TestA.alter_bar_age 0.5
+
+      sleep 0.75
+      bar.should be_equal(TestA.bar)
+
+      # so now the age should only be 0.5 seconds
+      TestA.expire_bar_now
+      bar.should_not be_equal(TestA.bar)
+      TestA.bar.should == 'class bar'
+
+      sleep 0.75
+      bar.should_not be_equal(TestA.bar)
+    end
+
+    it 'executes the block in the context of the class' do
+      TestA.me.should be_equal(TestA)
+    end
+
+  end
 end
 
 # EOF

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: expiration-date
 version: !ruby/object:Gem::Version 
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors: 
 - Tim Pease
@@ -9,11 +9,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-08-23 00:00:00 -06:00
+date: 2008-08-25 00:00:00 -06:00
 default_executable: 
 dependencies: []
 
-description: Wandering the grocery aisle the other day I saw a package of bacon with a neon green sticker screaming for all to hear "THIS BACON ONLY COSTS ONE DOLLAR!!!". Screaming bacon always intrigues me, so I grabbed the nearest store manager. He works at the coffee shop next door, but when I told him about the screaming bacon he had to come and see for himself.  "Oh, it's a manager's special" he told me. "When products get too old the manager will reduce the price so they sell more quickly. This allows new products to be put on the shelves, and the store can make some money instead of throwing out the expired products".  I stared at him blankly. He wandered back to the coffee shop and had a latte.  I continued to stand there thinking about expiring products and how Ruby could benefit from neon green stickers and stale bacon. Eventually the grocery store manager came by and asked me if everything was okay. I grabbed him by the collar, pointed at the bacon and yelled "DO YOU KNOW WHAT THIS MEANS!?!?". I ran from the store, grabbed my laptop, and whipped up this little gem.  EXPIRATION DATE (now with more neon green).  Now ruby can expire it's bacon, too, just like the grocery store, and make room for more bacon from the delivery truck.
+description: Really simple caching by attaching an expiration date to attributes.  The ExpirationDate module adss two methods to a class -- expiring_attr and expiring_class_attr. These two methods are used to declare attributes in the instance and in the class, respectively, that will expire after some period of seconds have elapsed. The attribute is re-initialized from the given block after it has expired. This is a very simple form of caching.
 email: tim.pease@gmail.com
 executables: []
 
@@ -21,11 +21,12 @@ extensions: []
 
 extra_rdoc_files: 
 - History.txt
-- README.txt
+- README.rdoc
 files: 
+- .gitignore
 - History.txt
 - Manifest.txt
-- README.txt
+- README.rdoc
 - Rakefile
 - lib/expiration-date.rb
 - spec/expiration-date_spec.rb
@@ -46,7 +47,7 @@ homepage: http://codeforpeople.rubyforge.org/expiration-date
 post_install_message: 
 rdoc_options: 
 - --main
-- README.txt
+- README.rdoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement