flagpole_sitta 0.5.0

data/.gitignore

@@ -0,0 +1,7 @@
+.bundle/
+log/*.log
+pkg/
+test/dummy/db/*.sqlite3
+test/dummy/log/*.log
+test/dummy/tmp/
+.DS_Store

data/Gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+gem "capybara", ">= 0.4.0"
+gem "sqlite3"
+
+# To use debugger (ruby-debug for Ruby 1.8.7+, ruby-debug19 for Ruby 1.9.2+)
+# gem 'ruby-debug'
+# gem 'ruby-debug19'

data/Gemfile.lock

@@ -0,0 +1,38 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.8)
+    capybara (1.1.2)
+      mime-types (>= 1.16)
+      nokogiri (>= 1.3.3)
+      rack (>= 1.0.0)
+      rack-test (>= 0.5.4)
+      selenium-webdriver (~> 2.0)
+      xpath (~> 0.1.4)
+    childprocess (0.3.3)
+      ffi (~> 1.0.6)
+    ffi (1.0.11)
+    libwebsocket (0.1.3)
+      addressable
+    mime-types (1.19)
+    multi_json (1.3.6)
+    nokogiri (1.5.5)
+    rack (1.4.1)
+    rack-test (0.6.1)
+      rack (>= 1.0)
+    rubyzip (0.9.9)
+    selenium-webdriver (2.24.0)
+      childprocess (>= 0.2.5)
+      libwebsocket (~> 0.1.3)
+      multi_json (~> 1.0)
+      rubyzip
+    sqlite3 (1.3.6)
+    xpath (0.1.4)
+      nokogiri (~> 1.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  capybara (>= 0.4.0)
+  sqlite3

data/README.rdoc

@@ -0,0 +1,121 @@
+= FlagpoleSitta
+
+I had visions, I was in them,
+
+I was looking into the mirror
+
+To see a little bit clearer
+
+The rottenness and evil in me.
+
+♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫~♫
+
+== Preface
+
+===This gem should be considered in early beta and highly unstable. Do not use in a production app!
+
+This gem was inspired in part by the song Flagpole Sitta by Harvey Danger. So if you like the gem and are wanting to help out please either donate your time and submits some patches, or donate to the band who wrote the song. They put there last two albums out there all open source like, only asking that those that could donate after downloading. While your donating, if you choose to do so, don't be afraid to download there albums, its good stuff!
+
+http://www.harveydanger.com/contribute.php
+
+Another note on a personal level, I have some learning disabilities that make it so I frequently make grammar mistake, and once and a while just drop random articles out of my sentences. All this only happens when writing. So if something doesn't make sense in the docs don't be afraid to point it out or submit a patch. Because to me it all looks right.....
+
+This gem has also only so far been tested with memcache using the Dalli adapter. File System caching and memory caching are not recommended.Redis/Memcache are defiantly suggested and strongly encouraged for this gem.
+
+== Installation
+
+For now add the following line to your gemfile
+
+gem 'flagpole_sitta', :git => "git://github.com/rovermicrover/FlagpoleSitta.git"
+
+Then bundle install.
+
+== About
+
+Flagpole Sitta is a gem that main purpose is to make it easier to effectively fragment cache in dynamic fashions in Rails.
+
+When ever a cache is created it is associated with any model and/or record you tell it to be from the view helper method. When that model and/or record is updated all it's associated cache's are cleared. 
+
+Flagpole also expects you to put all your database calls into Procs/Lamdbas. This makes it so that your database calls wont have to happen unless your cache hasn't been created. Thus speeding up response time and reducing database traffic.
+
+For a simple application you could do something like this.
+
+=== PageModel
+
+  cache_sitta :route_id => "url"
+
+=== PagesController
+
+  def show
+
+    @page_call = lambda {
+      if params[:url]
+        @page = Page.find_by_url params[:url]
+      else
+        @page = Page.find_by_url 'home'
+      end
+    }
+
+    @body_calls = [
+      ['page', @page_call]
+    ]
+
+  end
+
+=== show.haml for Pages
+
+  - cache_sitta :model => Page, :route_id => params[:url], :section => "body" do
+    = @page.content.try(:html_safe)
+
+First off lets look at @body_calls. The if you don't provide cache_sitta :calls, then it will look for @#{:section}_calls. So in this case it will look for @body_calls.
+
+Second off @body_calls is an array of arrays. This is because you can have multiple calls, and each call must be given a target instance variable ('page') and a call object (@page_call). So in this instance the cache_sitta helper will do 
+
+    @page = @page_call.call
+
+You can also pass your calls options by providing :calls_args to the helper. You must though set up your calls to expect an options hash.
+
+:route_id and :model must be provide so that the cache can be associated with the correct object, and the cache clear when its supposed to.
+
+:route_id must also be a unquie field on the model, other wise the cache won't connect properly to the object.
+
+For an index page you could do something like the following for a simple app.
+
+=== BlogModel
+
+  cache_sitta :route_id => "url"
+
+=== BlogsController
+
+  def index
+
+    @blogs_call = lambda {
+      @blogs = Blog.all
+    }
+
+    @body_calls = [
+      ['blogs', @blogs_call]
+    ]
+
+  end
+
+=== index.haml for Blogs
+
+  - cache_sitta :models_in_index => Blog, :index_only => true, :section => "body" do
+    - @blogs.each do |blog|
+      = blog.title
+      etc
+      etc
+
+First notice you don't have to pass :route_id if you pass :index_only => true. And you don't have to pass :model if you pass :models_in_index.
+
+:models_in_index tells the helper which Model to associated with the index, so if any objects in that model update the index cache gets nuked.
+
+:index_only => true, tells the helper to not bother trying to associated this cache with anyone item in particular.
+
+== Footer
+
+More examples to come in the wiki, and in the coming example app.
+
+===This gem should be considered in early beta and highly unstable. Do not use in a production app!
+

data/Rakefile

@@ -0,0 +1,29 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+require 'rake/rdoctask'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task :default => :test
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'FlagpoleSitta'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/app/helpers/flagpole_sitta_helper.rb

@@ -0,0 +1,169 @@
+module FlagpoleSittaHelper
+
+  def update_index_array_cache model, key
+    model.try(:update_index_array_cache, key)
+  end
+
+  def update_show_array_cache model, key, route_id
+    model.try(:update_show_array_cache, key, route_id)
+  end
+
+  #AR - cache_sitta helper
+
+  #NOTE This is not safe for .builder xml files.
+
+  #Options are for cache_sitta
+  
+  #key_args, passed to route_id if its a proc or lamdba
+  #all args must be passed in this manner if proc or lamdba
+  #so start your proc or lamdba with |options = {}|
+
+  #call_args, passed to call_path if its a proc of lamdba
+  #all args must be passed in this manner if proc or lamdba
+  #so start your proc or lamdba with |options = {}|
+
+  #models_in_index
+  #Use this if the fragment you are rendering is an index
+  #pass it all the different types of models/classes could be
+  #included in the index. All the include classes must have cache
+  #sitta enabled. The cache for the used index pages will then be
+  #wiped clear when anyone of these models/classes has an object
+  #created or updated.
+  def cache_sitta  options={}, &block
+
+    #AR - If its a string, then just use that value, other wise it
+    #assumes that the route_id is a proc or lamdba and call its
+    #with the provide args.
+
+    if options[:route_id_args]
+      options[:route_id] = options[:route_id].call(options[:route_id_args])
+    elsif options[:route_id].class.eql?(Proc)
+      options[:route_id] = options[:route_id].call()
+    end
+
+    if options[:route_id].class.eql?(Array)
+      main_route_id = options[:route_id][0]
+    else
+      main_route_id = options[:route_id]
+    end
+
+
+    #Use subroute idea if the view can differ on things like current day, or any type of passed params that can effect how
+    #the page will look.
+    if options[:sub_route_id_args]
+      options[:sub_route_id] = options[:sub_route_id].call(options[:sub_route_id_args])
+    elsif options[:sub_route_id_args].class.eql?(Proc)
+      options[:sub_route_id] = options[:sub_route_id].call()
+    end
+
+    if options[:model]
+      if options[:model_args]
+        options[:model] = options[:model].call(options[:model_args])
+      elsif options[:model].class.eql?(Proc)
+        options[:model] = options[:model].call()
+      end
+
+      if options[:model].class.eql?(Array)
+        main_model = options[:model][0]
+      else
+        main_model = options[:model]
+      end
+
+    elsif params[:model]
+
+      main_model = params[:model]
+
+    elsif options[:models_in_index]
+
+      if options[:models_in_index].class.eql?(Array)
+        main_model = options[:models_in_index][0]
+      else
+        main_model = options[:models_in_index]
+      end
+      
+    end
+
+    main_model = main_model.respond_to?(:constantize) ? main_model.constantize : main_model
+
+    action = options[:action] || params[:action]
+
+    key = "views/#{main_model}/#{action}"
+
+    key = key + (main_route_id ? ('/' + main_route_id) : '')
+
+    key = key + (options[:sub_route_id] ? ('/' + options[:sub_route_id]) : '')
+
+    key = key + (options[:section] ? ('/' + options[:section]) : '')
+
+    calls = instance_variable_get(
+      "@" + (options[:section] ? options[:section] : 'body') + "_calls"
+    )
+
+    if content = Rails.cache.read(key)
+      #Do nothing the content is ready to render
+    else
+      #NOTE This is not safe for .builder xml files, and using capture here is why.
+      #Its either this or a really complicated hack, from the rails source code, which
+      #at the moment I don't feel comfortable using. Waiting for an official solution for
+      #the ability to use capture with .builders.
+      content = capture do
+        #AR - If call_path is an array render each one, other
+        #wise just render call_path, because it must
+        #be a string or array by this point or something went
+        #terribly terribly wrong.
+
+        if calls
+          calls.each do |c|
+            if instance_variable_get("@#{c[0]}").nil?
+              if options[:calls_args]
+                instance_variable_set("@#{c[0]}", c[1].call(options[:calls_args]))
+              else
+                instance_variable_set("@#{c[0]}", c[1].call())
+              end
+            end
+          end
+        end
+
+        yield
+
+      end
+
+      #AR - If the cache is an index or includes an index
+      #then models_in_index should be passed with all the
+      #models that could show up in the index.
+      #Then on save of any model include here this index will be cleared.
+      #This can also be used for fragments where there are just so many objects,
+      #that while its not an index, there isn't a clear way expect to nuke it when
+      #any of the model types involved are updated.
+
+      if options[:models_in_index].class.eql?(Array)
+        options[:models_in_index].each do |m|
+          processed_m = m.respond_to?(:constantize) ? m.constantize : m
+          update_index_array_cache(processed_m, key)
+        end
+      elsif options[:models_in_index]
+        processed_model = options[:models_in_index].respond_to?(:constantize) ? options[:models_in_index].constantize : options[:models_in_index]
+        update_index_array_cache(options[:models_in_index], key)
+      end
+
+      #AR - Create a link between each declared object and the cache.
+
+      if !options[:index_only] && options[:route_id]
+        if options[:route_id].class.eql?(Array) && options[:model].class.eql?(Array)
+          options[:model].each_index do |i|
+            update_show_array_cache(options[:model][i], key, options[:route_id][i])
+          end
+        else
+          update_show_array_cache(main_model, key, main_route_id)
+        end
+      end
+
+      Rails.cache.write(key, content)
+
+    end
+
+    safe_concat content
+
+  end
+
+end

data/flagpole_sitta.gemspec

@@ -0,0 +1,23 @@
+require File.expand_path("../lib/flagpole_sitta/version", __FILE__)
+
+# Provide a simple gemspec so you can easily use your enginex
+# project in your rails apps through git.
+Gem::Specification.new do |s|
+  s.name = "flagpole_sitta"
+  s.version = FlagpoleSitta::VERSION
+  s.platform = Gem::Platform::RUBY
+  s.authors     = ["Andrew Rove (Rover)"]
+  s.email       = ["rovermicrover@gmail.com"]
+  s.homepage    = "https://github.com/rovermicrover/FlagpoleSitta"
+  s.summary     = "FlagpoleSitta a gem for effective dynamic caching"
+  s.description = "Flagpole Sitta is a gem that main purpose is to make it easier to effectively fragment cache in dynamic fashions.\n When ever a cache is created it is associated with any model and/or record you tell it to be from the helper method. When that model and/or record is updated all it's associated cache's are cleared.\n Flagpole also expects you to put all your database calls into Procs/Lamdbas. This makes it so that your database calls wont have to happen unless your cache hasn't been created. Thus speeding up response time and reducing database traffic."
+
+  s.files = `git ls-files`.split("\n")
+  s.executables = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+  s.require_path = 'lib'
+
+  #add dependecy here and in the engine file as a required.
+
+  s.add_dependency('dalli')
+
+end

data/lib/flagpole_sitta/bracket_retrieval.rb

@@ -0,0 +1,83 @@
+module FlagpoleSitta
+  module BracketRetrieval
+
+    extend ActiveSupport::Concern
+
+    #When forcing a call back into a class from a module you must do it inside an include block
+    included do
+      validates_uniqueness_of (@_key_field || "name").to_sym
+      validates_presence_of (@_key_field || "name").to_sym
+      before_save :br_update_save
+      before_destroy :br_update_destroy
+    end
+
+    def br_update_save
+      self.br_update(true)
+    end
+
+    def br_update_destroy
+      self.br_update(false)
+    end
+
+    def br_update alive
+      downcased = self.class.name.downcase
+      #Checks to make sure Controller Caching is on
+      if Rails.application.config.action_controller.perform_caching
+        Rails.cache.delete("#{downcased}/#{self.send(self.class.key_field + "_was")}")
+        Rails.cache.write("#{downcased}/#{self.send(self.class.key_field)}", self.send(self.class.value_field))
+      end
+    end
+
+    module ClassMethods
+
+      #Will look up the object chain till it finds what it was set to, or not set too.
+      def safe_content?
+        result = @_safe_content || (self.superclass.respond_to?(:safe_content?) ? self.superclass.safe_content? : nil) || false
+      end
+
+      #Will look up the object chain till it finds what it was set to, or not set too.
+      def key_field
+        result = @_key_field || (self.superclass.respond_to?(:key_field) ? self.superclass.key_field : nil) || "name"
+      end
+
+      #Will look up the object chain till it finds what it was set to, or not set too.
+      def value_field
+        result = @_value_field || (self.superclass.respond_to?(:value_field) ? self.superclass.value_field : nil) || "content"
+      end
+
+      def default_value
+        result = @_default_value || (self.superclass.respond_to?(:default_value) ? self.superclass.default_value : nil) || ""
+      end
+
+      def [] key 
+        downcased = self.to_s.downcase
+        #If its in cache return that, unless blank, then return nil
+        #elsif the object is in the database put it into the cache
+        #then return it.
+        #else create the corresponding object as blank, and return nil.
+        #The last line there is why this extension should never be used
+        #with user generated content.
+        if value = Rails.cache.read("#{downcased}/#{key}") || Rails.cache.exist?("#{downcased}/#{key}")
+          if value.present?
+            value = self.safe_content? ? value.html_safe : value
+          else
+            #Always return nil even if the return value is blank.
+            #Also if its blank we don't want to try to create it again
+            #thus the reason for this odd nested if statement.
+            value = nil
+          end
+        elsif obj = self.send("find_by_#{self.key_field}", key)
+          value = obj.send(self.value_field)
+          Rails.cache.write("#{downcased}/#{key}", value)
+          value = value && self.safe_content? ? value.html_safe : value
+        else
+          rec = self.create(self.key_field.to_sym => key, self.value_field.to_sym => self.default_value)
+          Rails.cache.write("#{downcased}/#{key}", rec.send(self.value_field))
+          value = nil
+        end
+        value
+      end
+    end
+
+  end
+end

data/lib/flagpole_sitta/cache_sitta.rb

@@ -0,0 +1,198 @@
+module FlagpoleSitta
+  module CacheSitta
+    extend ActiveSupport::Concern
+
+    #When forcing a call back into a class from a module you must do it inside an include block
+    included do
+      before_save :cache_sitta_save
+      before_destroy :cache_sitta_destory
+    end
+
+    module ClassMethods
+
+      def initialize_index_array_cache
+
+        clazz = self
+
+        flag = {:space => - 1}
+
+        Rails.cache.write("#{clazz}/IndexArray/Flag", flag)
+
+        flag
+
+      end
+
+      def update_index_array_cache key
+
+        clazz = self
+
+        flag = Rails.cache.read("#{clazz}/IndexArray/Flag")
+
+        #AR - If it doesn't exist start the process of creating it
+        if flag.nil?
+          flag = initialize_index_array_cache
+        end
+
+        #AR - update the array's end point
+        flag[:space] = flag[:space] + 1
+       
+        #AR - write out the new index at the end of the array
+        Rails.cache.write("#{clazz}/IndexArray/#{flag[:space]}", {:key => key})
+
+        #AR - update flag in the cache
+        Rails.cache.write("#{clazz}/IndexArray/Flag", flag)
+
+      end
+
+      def each_index_cache &block
+
+        clazz = self
+
+        flag = Rails.cache.read("#{clazz}/IndexArray/Flag")
+        
+        #AR - If it doesn't exist start the process of creating it
+        if flag.nil?
+          flag = initialize_index_array_cache
+        end
+
+        #AR - If there aren't any index do nothing.
+        #Else wise loop through every index.
+        #If it actually does exist then yield.
+        for i in 0..flag[:space] do
+          hash = Rails.cache.read("#{clazz}/IndexArray/#{i}")
+          if hash
+            yield hash[:key]
+          end
+        end
+
+        nil
+
+      end
+
+      def destroy_index_array_cache
+
+        clazz = self
+
+        each_index_cache do |key|
+          Rails.cache.delete(key)
+        end
+
+        Rails.cache.delete("#{clazz}/IndexArray/Flag")
+      end
+
+      def initialize_show_array_cache route_id
+
+        clazz = self
+
+        #AR - Its negative one to stop the for loops in the each method if its empty
+        flag = {:space => - 1}
+
+        Rails.cache.write("#{clazz}/#{route_id}/ShowArray/Flag", flag)
+
+        flag
+
+      end
+
+      def update_show_array_cache key, route_id
+
+        clazz = self
+
+        flag = Rails.cache.read("#{clazz}/#{route_id}/ShowArray/Flag")
+
+        #AR - If it doesn't exist start the process of creating it
+        if flag.nil?
+          flag = initialize_show_array_cache(route_id)
+        end
+
+        #AR - Update the array's end point
+        flag[:space] = flag[:space] + 1
+
+        #AR - Write out the new index at the end of the array
+        Rails.cache.write("#{clazz}/#{route_id}/ShowArray/#{flag[:space]}", {:key => key})
+
+        #AR - Update flag in the cache
+        Rails.cache.write("#{clazz}/#{route_id}/ShowArray/Flag", flag)
+
+      end
+
+      def each_show_cache route_id, &block
+
+        clazz = self
+
+        flag = Rails.cache.read("#{clazz}/#{route_id}/ShowArray/Flag")
+        
+        #AR - If it doesn't exist start the process of creating it
+        if flag.nil?
+          flag = initialize_show_array_cache(route_id)
+        end
+
+        #AR - If there aren't any shows caches do nothing, this happens when space is -1.
+        #Else wise loop through every caches.
+        #If it actually does exist then yield.
+        for i in 0..flag[:space] do
+          hash = Rails.cache.read("#{clazz}/#{route_id}/ShowArray/#{i}")
+          if hash
+            yield hash[:key]
+          end
+        end
+
+        nil
+
+      end
+
+      def destroy_show_array_cache route_id
+
+        clazz = self
+
+        each_show_cache route_id do |k|
+          Rails.cache.delete(k)
+        end
+
+        Rails.cache.delete("#{clazz}/#{route_id}/ShowArray/Flag")
+      end
+
+    end
+
+    def cache_sitta_save
+      self.cache_work(true)
+    end
+
+    def cache_sitta_destory
+      self.cache_work(false)
+    end
+
+    def cache_work(alive)
+      original_clazz = self.class
+      # Also have to go through all its super objects till the super objects aren't cache sittaed
+      # this is because the new updated object for a sub class, could have also been in a cache for
+      # said sub class, but also in a cache for its super.
+      clazz = original_clazz
+      while(clazz.respond_to? :destroy_show_array_cache)
+
+        #AR - Clear all caches related to the old route_id
+        clazz.destroy_show_array_cache(self.try(:send, ("#{clazz.route_id}_was")).to_s)
+        #AR - Clear all caches related to the new route_id just in case
+        clazz.destroy_show_array_cache(self.try(:send, ("#{clazz.route_id}")).to_s)
+        #AR - If the new and old are the same All that will happen on the second call is that
+        #it will write the flag out and then destroy it. A very tiny bit of work
+        #for a great amount of extra protection.
+
+        # AR - Remember to include models_in_index in your helper call in the corresponding index cache.
+        clazz.destroy_index_array_cache
+
+        clazz = clazz.superclass
+      end
+
+      #AR - For Safety this will not recurse upwards for the extra cache maintenance
+      extra_cache_maintenance(alive)
+
+    end
+
+    #AR - For Safety this will not recurse upwards for the extra cache maintenance
+    def extra_cache_maintenance alive
+      method = (@_cache_extra_maintance || Proc.new{})
+      method.call
+    end
+
+  end
+end