thorero-cache 0.9.4

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Alex Boussinet
+
+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,160 @@
+= merb-cache
+
+A plugin for the Merb framework that provides caching
+
+Currently supported methods:
+
+- page caching:
+- action caching
+- fragment caching
+- object caching
+
+Implemented cache stores:
+
+- memory
+- memcache
+- file
+- database (sequel, datamapper, activerecord)
+
+== 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_actions(action, [action, expiration], ...)
+  cache_page(action, expiration)
+  cache_pages(action, [action, expiration], ...)
+
+=== 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 merb-cache in development
+    #:disable => true, # disable merb-cache in 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, ...
+  }
+
+
+== 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
+
+    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
+  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 -%>

data/Rakefile

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require "extlib"
+require 'merb-core/tasks/merb_rake_helper'
+
+##############################################################################
+# Package && release
+##############################################################################
+RUBY_FORGE_PROJECT  = "thorero"
+PROJECT_URL         = "http://merbivore.com"
+PROJECT_SUMMARY     = "Merb plugin that provides caching (page, action, fragment, object)"
+PROJECT_DESCRIPTION = PROJECT_SUMMARY
+
+GEM_AUTHOR = "Alex Boussinet"
+GEM_EMAIL  = "alex.boussinet@gmail.com"
+
+GEM_NAME    = "thorero-cache"
+PKG_BUILD   = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
+GEM_VERSION = (Merb::MORE_VERSION rescue "0.9.4") + PKG_BUILD
+
+RELEASE_NAME    = "REL #{GEM_VERSION}"
+
+require "extlib/tasks/release"
+
+spec = Gem::Specification.new do |s|
+  s.rubyforge_project = RUBY_FORGE_PROJECT
+  s.name = GEM_NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "LICENSE", 'TODO']
+  s.summary = PROJECT_SUMMARY
+  s.description = PROJECT_DESCRIPTION
+  s.author = GEM_AUTHOR
+  s.email = GEM_EMAIL
+  s.homepage = PROJECT_URL
+  s.add_dependency('merb-core', '>= 0.9.4')
+  s.add_dependency('builder', '>= 2.0.0')
+  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
+
+desc "Install the gem"
+task :install => [:package] do
+  sh %{#{sudo} gem install #{install_home} pkg/#{GEM_NAME}-#{GEM_VERSION} --no-update-sources}
+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/#{GEM_NAME}-#{GEM_VERSION}.gem --no-rdoc --no-ri}
+  end
+
+end

data/TODO

@@ -0,0 +1,2 @@
+capture_#{engine} and concat_#{engine} are required for cache()
+implement other cache store ?

data/lib/merb-cache.rb

@@ -0,0 +1,10 @@
+if defined?(Merb::Plugins)
+  Merb::Plugins.add_rakefiles "merb-cache/merbtasks"
+  unless 1.respond_to? :minutes
+    class Numeric
+      def minutes; self * 60; end
+      def from_now(now = Time.now); now + self; end
+    end
+  end
+  require "merb-cache/merb-cache"
+end

data/lib/merb-cache/cache-action.rb

@@ -0,0 +1,135 @@
+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
+  #
+  # ==== Examples
+  #   cache_action :mostly_static
+  #   cache_action :barely_dynamic, 10
+  def cache_action(action, from_now = nil, opts = {})
+    cache_actions([action, from_now, opts])
+  end
+
+  # Register actions for action caching (before and after filters)
+  #
+  # ==== Parameter
+  # actions<Symbol,Array[Symbol,~minutes]>:: See #cache_action
+  #
+  # ==== Example
+  #   cache_actions :mostly_static, [:barely_dynamic, 10]
+  def cache_actions(*actions)
+    actions.each do |action, from_now, opts|
+      from_now, opts = nil, from_now if Hash === from_now
+      
+      before("cache_#{action}_before", opts.merge(:only => action))
+      after("cache_#{action}_after", opts.merge(:only => action))
+      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
+    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)
+    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?
+    if data
+      from_now = Merb::Controller._cache.cached_actions[controller][action]
+      Merb::Controller._cache.store.cache_set(path, data, from_now)
+    else
+      @capture_action = false
+      _data = Merb::Controller._cache.store.cache_get(path)
+      throw(:halt, _data) unless _data.nil?
+      @capture_action = true
+    end
+    true
+  end
+
+  # before filter
+  def cache_action_before
+    # recalls a cached entry or set @capture_action to true in order
+    # to grab the response in the after filter
+    _cache_action
+  end
+
+  # after filter
+  def cache_action_after
+    # 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) if @capture_action && status == 200
+  end
+end

data/lib/merb-cache/cache-fragment.rb

@@ -0,0 +1,95 @@
+module Merb::Cache::ControllerInstanceMethods
+  # Mixed in Merb::Controller. Provides methods related to fragment 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?("my_key")
+  def cached?(options)
+    key = Merb::Controller._cache.key_for(options, controller_name)
+    Merb::Controller._cache.store.cached?(key)
+  end
+
+  # ==== Example
+  #   In your view:
+  #   <%- cache("my_key") do -%>
+  #     <%= partial :test, :collection => @test %>
+  #   <%- end -%>
+  def cache(options, from_now = nil, &block)
+    key = Merb::Controller._cache.key_for(options, controller_name)
+    Merb::Controller._cache.store.cache(self, key, from_now, &block)
+  end
+
+  # Fetch data from cache
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #key_for
+  #
+  # ==== Returns
+  # data<Object,NilClass>::
+  #   nil is returned if the cache entry is not found
+  #
+  # ==== Example
+  #   if cache_data = cache_get("my_key")
+  #     @var1, @var2 = *cache_data
+  #   else
+  #     @var1 = MyModel.big_query1
+  #     @var2 = MyModel.big_query2
+  #     cache_set("my_key", nil, [@var1, @var2])
+  #   end
+  def cache_get(options)
+    key = Merb::Controller._cache.key_for(options, controller_name)
+    Merb::Controller._cache.store.cache_get(key)
+  end
+
+  # Store data to cache
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #key_for
+  # object<Object>:: The object(s) to put in cache
+  # from_now<~minutes>::
+  #   The number of minutes (from now) the cache should persist
+  #
+  # ==== Returns
+  # data<Object,NilClass>::
+  #   nil is returned if the cache entry is not found
+  #
+  # ==== Example
+  #   if cache_data = cache_get("my_key")
+  #     @var1, @var2 = *cache_data
+  #   else
+  #     @var1 = MyModel.big_query1
+  #     @var2 = MyModel.big_query2
+  #     cache_set("my_key", nil, [@var1, @var2])
+  #   end
+  def cache_set(options, object, from_now = nil)
+    key = Merb::Controller._cache.key_for(options, controller_name)
+    Merb::Controller._cache.store.cache_set(key, object, from_now)
+  end
+
+  # Expires the entry identified by the key computed after the parameters
+  #
+  # ==== Parameter
+  # options<String,Hash>:: The options that will be passed to #key_for
+  #
+  # ==== Examples
+  #   expire("my_key")
+  #   expire(:key => "my_", :match => true)
+  #   expire(:key => "my_key", :params => [session[:me], params[:ref]])
+  def expire(options)
+    Merb::Controller._cache.expire_key_for(options, controller_name) do |key, match|
+      if match
+        Merb::Controller._cache.store.expire_match(key)
+      else
+        Merb::Controller._cache.store.expire(key)
+      end
+    end
+    true
+  end
+end