bchiu-merb_cache_more 0.9.4

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Ben Chiu
+
+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,204 @@
+= merb_cache_more
+
+  Extends merb-cache to use params, work with pagination, auto-cache all actions and use many key formats
+  
+  This plugin is a fork of merb-cache written by Alex Boussinet. Much of the 
+  cache-store stuff is unchanged (I only added it so people can run the tests
+  and use this plugin without any dependencies on merb-cache). 
+  
+  Currently supported methods:
+  
+  - page caching:
+  - action caching
+  - fragment caching
+  - object caching
+  
+  Implemented cache stores:
+  
+  - memory
+  - memcache
+  - file
+  - database (sequel, datamapper, activerecord)
+
+== Installation
+
+  git clone git://github.com/bchiu/merb_cache_more.git
+  cd merb_cache_more
+  rake install
+  remove: dependency 'merb-cache' from init.rb
+  add: dependency 'merb_cache_more' to init.rb
+
+== Quick intro
+  With fragment caching, you can mix dynamic and static content.
+
+  With action caching, the whole template is cached
+  but the before filters are still processed.
+
+  With page caching, the whole template is put in html files in a special
+  directory in order to be handled directly without triggering Merb.
+
+== Quick API
+
+=== Merb::Controller class methods
+  cache_action(action, expiration)
+  cache_action(action, expiration, options)
+  cache_actions(action, [action, expiration], ...)
+  cache_actions(action, [action, expiration], [action, expiration, options], ...)
+  cache_page(action, expiration)
+  cache_page(action, expiration, options)
+  cache_pages(action, [action, expiration], ...)
+  cache_pages(action, [action, expiration], [action, expiration, options], ...)
+
+=== Merb::Controller instance methods
+  expire_page(key)
+  cached_page?(key)
+  expire_all_pages()
+
+  expire_action(key)
+  cached_action?(key)
+
+  cached?(key)
+  cache_get(key)
+  cache_set(key, data, expiration)
+  expire(key)
+  expire_all()
+
+=== Inside your template
+  cache(key, expiration) do ... end
+
+  # expiration is given in minutes
+
+  # key can be a string or a hash
+  # possible keys when it's a hash:
+  # :key (full key)
+  # :params (array of params to be added to the key)
+  # :action, :controller
+  # :match (true or partial key)
+
+  # Don't forget to look at the specs !!
+
+== Specs
+  $ rake specs:<cache_store>
+  example:
+  $ rake specs:memory
+  $ rake specs:file
+  or just:
+  $ cd spec
+  $ STORE=<cache_store> spec merb-cache_spec.rb
+  # cache_store can be:
+  #   memory, memcache, file, sequel, datamapper, activerecord
+
+== Sample configuration
+
+  Merb::Plugins.config[:merb_cache] = {
+    :cache_html_directory => Merb.dir_for(:public) / "cache",
+
+    #:store => "database",
+    #:table_name => "merb_cache",
+
+    #:disable => "development", # disable caching for development
+    #:disable => true, # disable caching for all environments
+
+    :store => "file",
+    :cache_directory => Merb.root_path("tmp/cache"),
+
+    #:store => "memcache",
+    #:host => "127.0.0.1:11211",
+    #:namespace => "merb_cache",
+    #:no_tracking => "false",
+
+    #:store => "memory",
+    # store could be: file, memcache, memory, database, dummy, ...
+
+    # can be nil|:snake|:tree|:hash|:query or a custom string
+    # such as ":paramname1/:paramname2_and_:paramname3"
+    #:cache_key_format => nil,
+
+    # expiration time in minutes
+    #:cache_action_ttl => 10,
+    #:cache_page_ttl => 10
+  }
+
+
+== Quick Example
+
+==== controller part
+  class Users < Merb::Controller
+    cache_page :action_name
+    # this will cache the action in public/cache/something.html
+    # this cache entry will never expire (no expiration provided)
+    # for permanent caching you could set your lighty/nginx so as to handle
+    # the .html file directly
+    # for multiple page caching:
+    # cache_pages :action_name, [:another_action, 5], :some_action
+
+    cache_action :another_action, 10
+    # this will cache the action using the cache store
+    # this cache entry will expire in 10 minutes
+    # for multiple action caching:
+    # cache_actions :action_name, [:another_action, 5], :some_action
+
+    cache_action :action_with_config
+    # this will cache the action using the config settings:
+    # :cache_action_ttl => 10
+    # :cache_key_format => nil|:snake|:tree|:query|:hash or custom
+
+    cache_action :action_with_params, 10, :format => :snake, :params => [:id, :name]
+    # config settings may be overriden per action
+    # this will cache the action using a snake case key
+    # key will only include only the params :id and :name
+    # this cache entry will expire in 10 minutes
+
+    def list
+      unless @users = cache_get("active_users")
+        @users = User.all(:active => true)
+        cache_set("active_users", @users)
+        # object caching can be used to avoid pulling huge amounts of data
+        # from the database.
+        # you could have calle cache_set with an expiration time as well:
+        # cache_set("active_users", @users, 10)
+      end
+      render
+    end
+
+    def some_action_that_invalidates_cache
+      expire_page(:action_name)
+      expire_action(:another_action)
+      render
+    end
+
+    def delete
+      expire("active_users")
+      render
+    end
+
+    def archives
+      @archives = User.archives unless cached?("users_archives")
+      render
+    end
+
+    def index
+      render
+    end
+
+    cache_actions :all, 10, :exclude => [:list]
+    # this will cache all actions in the current controller
+    # except for the :list action
+    # cache entries will expire in 10 minutes
+    # note: this line must appear at the end of the class declaration
+  end
+
+
+====views/users/index.html.erb
+  # this entry will expire in 10 minutes
+  <%- cache "users_index", 10 do %>
+   <div>some big template</div>
+  <% end -%>
+
+====views/users/archive.html.erb
+  <%- cache "users_archives" do %>
+   <div>some big template</div>
+  <% end -%>
+
+== Credits
+  This plugin is a fork of merb-cache written by Alex Boussinet. 

data/Rakefile

@@ -0,0 +1,81 @@
+require 'rubygems'
+require 'rubygems/specification'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'spec/rake/spectask'
+require 'date'
+require 'merb_rake_helper'
+
+PLUGIN = "merb_cache_more"
+NAME = "merb_cache_more"
+GEM_VERSION = "0.9.4"
+AUTHOR = "Ben Chiu"
+EMAIL = "bchiu@yahoo.com"
+HOMEPAGE = "http://github.com/bchiu/merb_cache_more"
+SUMMARY = "Extends merb-cache to use params, work with pagination, auto-cache all actions and use many key formats"
+
+spec = Gem::Specification.new do |s|
+  s.name = NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.add_dependency('merb-core', '>= 0.9.4')
+  s.require_path = 'lib'
+  s.files = %w(LICENSE README Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+task :install => [:package] do
+  sh %{#{sudo} #{gemx} install pkg/#{NAME}-#{GEM_VERSION} --local --no-update-sources}
+end
+
+task :install_frozen => [:package] do
+  sh %{#{sudo} #{gemx} install pkg/#{NAME}-#{GEM_VERSION} -i ../../ --local --no-update-sources}
+end
+
+desc "create a gemspec file"
+task :make_spec do
+  File.open("#{NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+namespace :jruby do
+  desc "Run :package and install the resulting .gem with jruby"
+  task :install => :package do
+    sh %{#{sudo} jruby -S gem install #{install_home} pkg/#{NAME}-#{GEM_VERSION}.gem --local --no-rdoc --no-ri}
+  end
+end
+
+namespace :specs do
+  ["file", "memory", "memcache", "sequel", "datamapper", "activerecord"].each do |store|
+    desc "Run spec with the \"#{store}\" cache store"
+    task "#{store}" do
+      cwd = Dir.getwd
+      Dir.chdir(File.dirname(__FILE__) + "/spec")
+      ENV["STORE"] = store
+      system("spec --format specdoc --colour merb_cache_more_spec.rb")
+      Dir.chdir(cwd)
+    end
+  end
+end
+
+namespace :doc do
+  Rake::RDocTask.new do |rdoc|
+    files = ["README", "LICENSE", "lib/**/*.rb"]
+    rdoc.rdoc_files.add(files)
+    rdoc.main = "README"
+    rdoc.title = "merb_cache_more docs"
+    rdoc.rdoc_dir = "doc/rdoc"
+    rdoc.options << "--line-numbers" << "--inline-source"
+  end
+end

data/TODO

@@ -0,0 +1 @@
+TODO:

data/lib/merb_cache_more.rb

@@ -0,0 +1,33 @@
+if defined?(Merb::Plugins)
+  require 'merb_cache_more/merb-cache.rb'
+  require 'merb_cache_more/cache-action.rb'
+  require 'merb_cache_more/cache-page.rb'
+  require "merb_cache_more/cache-fragment"
+  require 'merb_cache_more/request.rb'
+  require 'merb_cache_more/request_helper.rb'
+  require 'digest/md5'
+
+  unless 1.respond_to? :minutes
+    class Numeric
+      def minutes; self * 60; end
+      def from_now(now = Time.now); now + self; end
+    end
+  end
+
+  module Merb
+    class Controller
+      cattr_reader :_cache
+      @@_cache = Merb::Cache.new
+      include Merb::Cache::ControllerInstanceMethods
+      class << self
+        include Merb::Cache::ControllerClassMethods
+      end
+    end
+  end
+
+  Merb::BootLoader.after_app_loads do
+    Merb::Controller._cache.start
+  end
+
+  Merb::Plugins.add_rakefiles "merb_cache_more/merbtasks"
+end

data/lib/merb_cache_more/cache-action.rb

@@ -0,0 +1,176 @@
+class Merb::Cache
+  cattr_accessor :cached_actions
+  self.cached_actions = {}
+end
+
+module Merb::Cache::ControllerClassMethods
+  # Mixed in Merb::Controller. Provides methods related to action caching
+
+  # Register the action for action caching
+  #
+  # ==== Parameters
+  # action<Symbol>:: The name of the action to register
+  # from_now<~minutes>::
+  #   The number of minutes (from now) the cache should persist
+  # options<Hash>::
+  #   Key formats :format => :snake|:tree|:hash|:query or nil for default
+  #   Custom format :format => ":param1/:param2-and_:param3"
+  #   Params :params => [params to include] or false to disable
+  #
+  # ==== Examples
+  #   cache_action :mostly_static
+  #   cache_action :barely_dynamic, 10
+  #   cache_action :barely_dynamic, 10, {:format => :hash, :params => [:id, :name]}
+  #   cache_action :barely_dynamic, :format => ":param1/:param2-and_:param3[key]"
+  def cache_action(action, from_now = nil, opts = {})
+    from_now, opts = nil, from_now if Hash === from_now
+
+    cache_opts = {:format => opts[:format], :params => opts[:params]}
+    opts.delete(:format); opts.delete(:params); opts.delete(:exclude)
+    
+    before("cache_#{action}_before", opts.merge(:only => action, :with => [cache_opts]))
+    after("cache_#{action}_after", opts.merge(:only => action, :with => [cache_opts]))
+    alias_method "cache_#{action}_before", :cache_action_before
+    alias_method "cache_#{action}_after", :cache_action_after
+    
+    _actions = Merb::Cache.cached_actions[controller_name] ||= {}
+    _actions[action] = from_now
+  end
+
+  # Register actions for action caching (before and after filters)
+  #
+  # ==== Parameter
+  # actions<Symbol,Array[Symbol,~minutes,Hash]>:: See #cache_action
+  #
+  # ==== Example
+  #   cache_actions :mostly_static,  :barely_dynamic
+  #   cache_actions :mostly_static,  [:barely_dynamic, 10]
+  #   cache_actions :barely_dynamic, [:barely_dynamic, 10, :format => :hash]
+  #   cache_actions :barely_dynamic, [:barely_dynamic, 10, :params => [:id, :name]]
+  #   cache_actions :all, 10, :exclude => [:show], :format => :snake, :params => [:id, :name]
+  def cache_actions(*actions)
+    config = Merb::Plugins.config[:merb_cache]
+    
+    if actions[0] == :all
+      from_now = Hash === actions[1] ? config[:cache_action_ttl] : actions[1]
+      opts     = Hash === actions[1] ? actions[1] : actions[2] || {}
+      excludes = opts[:exclude] || []
+      actions  = self.instance_methods(false).map {|action| 
+        [action.to_sym, from_now, opts] unless excludes.include?(action.to_sym)
+      }.compact
+    end
+
+    actions.each do |act_opts|
+      if Array === act_opts
+        action   = act_opts[0]
+        from_now = Hash === act_opts[1] ? config[:cache_action_ttl] : act_opts[1]
+        opts     = Hash === act_opts[1] ? act_opts[1] : act_opts[2]
+      else
+        action   = act_opts
+        from_now = config[:cache_action_ttl]
+        opts     = {}
+      end
+      cache_action(action, from_now, opts||{})
+    end
+    true
+  end
+end
+
+module Merb::Cache::ControllerInstanceMethods
+  # Mixed in Merb::Controller. Provides methods related to action caching
+
+  # Checks whether a cache entry exists
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #key_for
+  #
+  # ==== Returns
+  # true if the cache entry exists, false otherwise
+  #
+  # ==== Example
+  #   cached_action?(:action => 'show', :params => [params[:page]])
+  def cached_action?(options)
+    key = Merb::Controller._cache.key_for(options, controller_name, true)
+    Merb::Controller._cache.store.cached?(key)
+  end
+
+  # Expires the action identified by the key computed after the parameters
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #expire_key_for
+  #
+  # ==== Examples
+  #   expire_action(:action => 'show', :controller => 'news')
+  #   expire_action(:action => 'show', :match => true)
+  def expire_action(options)
+    Merb::Controller._cache.expire_key_for(options, controller_name, true) do |key, match|
+      if match
+        Merb::Controller._cache.store.expire_match(key)
+      else
+        Merb::Controller._cache.store.expire(key)
+      end
+    end
+    true
+  end
+
+  # You can call this method if you need to prevent caching the action
+  # after it has been rendered.
+  def abort_cache_action
+    @capture_action = false
+  end
+
+  private
+
+  # Called by the before and after filters. Stores or recalls a cache entry.
+  # The key is based on the result of request.path
+  # If the key with "/" then it is removed
+  # If the key is "/" then it will be replaced by "index"
+  #
+  # ==== Parameters
+  # data<String>:: the data to put in cache using the cache store
+  #
+  # ==== Examples
+  #   If request.path is "/", the key will be "index"
+  #   If request.path is "/news/show/1", the key will be "/news/show/1"
+  #   If request.path is "/news/show/", the key will be "/news/show"
+  def _cache_action(data = nil, opts = {})
+    controller = controller_name
+    action = action_name.to_sym
+    actions = Merb::Controller._cache.cached_actions[controller]
+    return unless actions && actions.key?(action)
+
+    path = request.path.chomp("/")
+    path = "index" if path.empty?
+
+    _format = opts[:format] || Merb::Controller._cache.config[:cache_key_format]
+    _params = opts[:params]==false ? nil : Merb::Request.query_parse(request.query_string, '&', true)
+    _params.delete_if {|k,v| !opts[:params].include?(k.to_sym) } if _params && opts[:params]
+    
+    key = Merb::Controller._cache.key_for({:key => path, :params => _params, :format => _format})
+
+    if data
+      from_now = Merb::Controller._cache.cached_actions[controller][action]
+      Merb::Controller._cache.store.cache_set(key, data, from_now)
+    else
+      @capture_action = false
+      _data = Merb::Controller._cache.store.cache_get(key)
+      throw(:halt, _data) unless _data.nil?
+      @capture_action = true
+    end
+    true
+  end
+
+  # before filter
+  def cache_action_before(opts)
+    # recalls a cached entry or set @capture_action to true in order
+    # to grab the response in the after filter
+    _cache_action(nil, opts)
+  end
+
+  # after filter
+  def cache_action_after(opts)
+    # takes the body of the response and put it in cache
+    # if the cache entry expired, if it doesn't exist or status is 200
+    _cache_action(body, opts) if @capture_action && status == 200
+  end
+end