merb_piece_cache 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright(c) 2009 kuwata-lab.com all rights reserverd.
+
+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,142 @@
+======
+README
+======
+
+$Release: 0.1.0 $
+
+
+About
+-----
+
+merb_piece_cache is a Merb plug-in to cache html fragments.
+You can eliminate database access with this plugin.
+
+Currently only file-base cache store is provided.
+(Memory-base cache store may be provided in future.)
+
+
+Install
+-------
+
+    ### install gem
+    $ sudo gem install merb_helpers_monkey
+    ## add 'dependency "merb_piece_cache"'
+    $ vi config/dependencies.rb
+
+This plugin requires 'called_from' library.
+If you install this plugin manually, don't forget to install 'called_from'.
+
+
+Example
+-------
+
+* [controller] delay database access by if_not_cached() helper.
+* [template] specify cache area by cache_with() helper.
+
+
+controller:
+
+    def index
+      ## @user is necessary every time
+      @user = User.current()
+      ## @members is necessary only when cache is refreshed
+      ## (block parameter is called only when cache is expired or not found)
+      if_not_cached {|cache_key|
+        @members = Members.all(:order=>[:created_at])
+      }
+      render
+    end
+
+
+template:
+
+    <!-- rendered every time (because never cached) -->
+    <% if @user %>
+      Hello <%=h @user %>!
+    <% else %>
+      <a href="/login">Login</a>
+    <% end %>
+
+    <!-- rendered only when cache is expired or not found -->
+    <% lifetime = 5*60  # sec, default is nil(=infinity) %>
+    <% cache_with("members/index", lifetime) do %>
+      <ul>
+      <% for member in @members %>
+        <li><%=h @member.name %></li>
+      <% end %>
+      <ul>
+    <% end %>
+
+
+Reference
+---------
+
+Merb_piece_cache plugin provides the following helpers.
+
+* if_not_cached() {|cache_key| ... }
+     Register block as callback object which is called when fragment
+     cache is re-generated (In other words, block parameter is called
+     only when cache is re-generated).
+     Block paramter can receive cache_key as 1st argument so that
+     you can switch data processing according to cache_key.
+     
+* piece_cache(cache_key, lifetime=nil) { ... }
+     When cache is found and not expired, then add cache data into view.
+     Otherwise, call block to re-generate cache data and cache it.
+     (Notice that block parameter is called only when cache is re-generated.)
+     It is able to specify cache lifetime. For example, if you specify
+     lifetime=5*60, cache data will be expired after 5 minutes.
+
+* cache_with(cache_key, lifetime=nil) { ... }
+     Alias of piece_cache().
+     You can re-define this helper to extend cache behaviour.
+
+
+Configuration
+-------------
+
+You can configure merb_piece_cache plugin in your environment file.
+(config/environments/{production,development,test}.rb).
+For example, add the followings into your 'development.rb':
+
+    Merb::Plugins.config[:merb_piece_cache] = {
+      ## show cached area in template (convenient for debug!)
+      :show_area => true,
+      ## directory to place cache files (default: "MERB_ROOT/tmp/cache")
+      :root_dir  => "/var/tmp",
+    }
+
+
+Tips
+----
+
+* You can prepare different data in if_not_exist() according to cache_key.
+
+      def index
+        if_not_cached {|cache_key|
+	  case cache_key
+	  when /^post\/(\d+)$/
+	    @post = BlogPost.get($1)
+          when /^post\/(\d+)/comments$/
+	    @comments = BlogComment.all(:post_id=>$1)
+	  end
+	}
+	render
+      end
+
+* piece_cache() (and also cache_with()) checks template timestamp.
+  If cache data is older than template timestamp, then cache data will be
+  re-generated.
+
+
+Author
+------
+
+makoto kuwata <kwa(at)kuwata-lab.com>
+copyright(c) 2009 kuwata-lab.com all rights reserved.
+
+
+License
+-------
+
+MIT License

data/Rakefile

@@ -0,0 +1,87 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+require 'merb-core'
+require 'merb-core/tasks/merb'
+
+GEM_NAME = "merb_piece_cache"
+GEM_VERSION = "0.1.0"
+AUTHOR = "makoto kuwata"
+EMAIL = "kwa.at.kuwata-lab.com"
+HOMEPAGE = "http://github.com/kwatch/merb_piece_cache/"
+SUMMARY = "Merb plugin to cache html fragment"
+
+@copyright = 'copyright(c) 2009 kuwata-lab.com all rights reserved.'
+@license = 'MIT License'
+
+spec = Gem::Specification.new do |s|
+  s.rubyforge_project = 'merb_piece_cache'
+  s.name = GEM_NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = false
+  s.extra_rdoc_files = ["README", "MIT-LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  #s.add_dependency('merb', '>= 1.0.12')
+  s.add_dependency('called_from', ['>= 0.1.0'])
+  s.require_path = 'lib'
+  #s.files = %w(MIT-LICENSE README Rakefile TODO) + Dir.glob("{lib,spec}/**/*")
+  s.files = %w(MIT-LICENSE README Rakefile TODO) + Dir.glob("{lib}/**/*")
+end
+
+#Rake::GemPackageTask.new(spec) do |pkg|
+#  pkg.gem_spec = spec
+#end
+
+desc "install the plugin as a gem"
+task :install do
+  Merb::RakeHelper.install(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Uninstall the gem"
+task :uninstall do
+  Merb::RakeHelper.uninstall(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Create a gemspec file"
+task :gemspec do
+  File.open("#{GEM_NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+desc "create gem package"
+task :package => [:gemspec] do
+  dir = "build"
+  rm_rf dir
+  mkdir dir
+  #cp_r spec.files, dir
+  sh "tar cf - #{spec.files.join(' ')} | (cd #{dir}; tar xf -)"
+  Dir.glob("#{dir}/**/*").each do |fpath|
+    next unless File.file?(fpath)
+    next if File.basename(fpath) == 'Rakefile'
+    s = File.open(fpath, 'rb') {|f| f.read }
+    s.gsub! /\$Release\$/,     GEM_VERSION
+    s.gsub! /\$Release:.*?\$/, "$Release: #{GEM_VERSION} $"
+    s.gsub! /\$Copyright\$/,   @copyright
+    s.gsub! /\$License\$/,     @license
+    File.open(fpath, 'wb') {|f| f.write s }
+  end
+  cp "#{GEM_NAME}.gemspec", dir
+  chdir dir do
+    sh "gem build #{GEM_NAME}.gemspec"
+    mv "#{GEM_NAME}-#{GEM_VERSION}.gem", ".."
+  end
+end
+
+desc "install gem package"
+task :inst => [:package] do
+  sh "gem install #{GEM_NAME}-#{GEM_VERSION}.gem"
+end
+
+
+spec

data/TODO

@@ -0,0 +1,2 @@
+TODO:
+* implement MemcachedCacheStore

data/lib/merb_piece_cache.rb

@@ -0,0 +1,47 @@
+###
+### $Release: 0.1.0 $
+### copyright(c) 2009 kuwata-lab.com all rights reserved.
+### MIT License
+###
+
+
+# make sure we're running inside Merb
+if defined?(Merb::Plugins)
+
+  # Merb gives you a Merb::Plugins.config hash...feel free to put your stuff in your piece of it
+  default_conf = {
+    :show_area   => false,
+    :root_dir    => nil,
+    :cache_store => nil,
+  }
+  curr_conf = Merb::Plugins.config[:merb_piece_cache]
+  Merb::Plugins.config[:merb_piece_cache] = default_conf.merge(curr_conf || {})
+
+  Merb::BootLoader.before_app_loads do
+    # require code that must be loaded before the application
+    require 'merb-cache/cache'
+    require 'merb_piece_cache/file_cache_store'
+    require 'merb_piece_cache/helpers'
+    begin
+      require 'called_from.so'
+    rescue LoadError
+      require 'called_from.rb'
+      Merb.logger.info "[piece_cache] it is strongly recommended to install 'called_from.so' instead of 'called_from.rb' for good performance"
+    end
+  end
+
+  Merb::BootLoader.after_app_loads do
+    # code that can be required after the application loads
+    cache_store = Merb::Plugins.config[:merb_piece_cache][:cache_store]
+    if cache_store
+      Merb.logger.debug "[piece_cache] using #{cache_store.class}"
+    else
+      root_dir = Merb::Plugins.config[:merb_piece_cache][:root_dir]
+      cache_store = PieceCache::FileCacheStore.new(:dir=>root_dir)
+      Merb::Plugins.config[:merb_piece_cache][:cache_store] = cache_store
+      Merb.logger.debug "[piece_cache] using #{cache_store.class} (root_dir=#{cache_store.dir})"
+    end
+  end
+
+  #Merb::Plugins.add_rakefiles "merb_piece_cache/merbtasks"
+end

data/lib/merb_piece_cache/file_cache_store.rb

@@ -0,0 +1,77 @@
+###
+### $Release: 0.1.0 $
+### copyright(c) 2009 kuwata-lab.com all rights reserved.
+### MIT License
+###
+
+
+module PieceCache
+
+
+  class FileCacheStore < Merb::Cache::FileStore
+
+    def pathify(key, parameters = {})
+      filename = super
+      ctype = parameters[:content_type]
+      ctype ? "#{filename}.#{ctype}" : filename
+    end
+
+    def read(key, parameters = {})
+      ## if cache file is not found, return nil
+      fpath = pathify(key)  # or pathify(key, parameters)
+      return nil unless File.exist?(fpath)
+      ## if cache file is created before timestamp, return nil
+      timestamp = parameters[:timestamp]
+      return nil if timestamp && File.ctime(fpath) < timestamp
+      ## if cache file is expired, return nil
+      return nil if File.mtime(fpath) <= Time.now
+      ## return cache file content
+      return read_file(fpath)
+    end
+
+    MAX_TIMESTAMP = Time.at(0x7fffffff)  # Tue Jan 19 03:14:07 UTC 2038
+
+    def write(key, data = nil, parameters = {}, conditions = {})
+      ## create directory for cache
+      fpath = pathify(key)  # or pathify(key, parameters)
+      dir = File.dirname(fpath)
+      FileUtils.mkdir_p(dir) unless File.exist?(dir)
+      ## write data into file
+      File.unlink(fpath) if File.exist?(fpath)
+      write_file(fpath, data)
+      ## set mtime (which is regarded as cache expired timestamp)
+      lifetime = parameters[:lifetime]
+      timestamp = lifetime && lifetime > 0 ? Time.now + lifetime : MAX_TIMESTAMP
+      File.utime(timestamp, timestamp, fpath)
+      ## return data
+      return data
+    end
+
+    if RUBY_PLATFORM =~ /mswin(?!ce)|mingw|cygwin|bccwin/i
+      def read_file(path)
+        File.open(path, 'rb') {|f| f.read() }
+      end
+    else
+      def read_file(path)
+        File.read(path)
+      end
+    end
+
+    def write_file(path, data)
+      ## write into tempoary file and rename it to path (in order not to call flock)
+      tmppath = "#{path}#{rand().to_s[1,6]}"
+      begin
+        File.open(tmppath, 'wb') {|f| f.write(data) }
+        File.rename(tmppath, path)
+      rescue => ex
+        File.unlink tmppath if File.exist?(tmppath)
+        File.unlink path    if File.exist?(path)
+        raise ex
+      end
+      true
+    end
+
+  end
+
+
+end

data/lib/merb_piece_cache/helpers.rb

@@ -0,0 +1,45 @@
+###
+### $Release: 0.1.0 $
+### copyright(c) 2009 kuwata-lab.com all rights reserved.
+### MIT License
+###
+
+
+module Merb
+  module GlobalHelpers
+
+    def if_not_cached(&block)
+      @_callback = block    # or @_deffered?
+    end
+
+    def piece_cache(cache_key, lifetime=nil)
+      #caller_str = caller(1)[0]    # caller() is too high cost to use in production mode
+      #template_path = caller_str =~ /:\d+:in `/ && $`   #`
+      template_path, linenum, funcname = called_from()
+      ts = File.exist?(template_path) && File.mtime(template_path)
+      cache_store = Merb::Plugins.config[:merb_piece_cache][:cache_store]
+      piece = cache_store.read(cache_key, :timestamp=>ts, :content_type=>self.content_type)
+      show_area = Merb::Plugins.config[:merb_piece_cache][:show_area]
+      if piece
+        Merb.logger.debug "[piece_cache] #{cache_key.inspect}: found."
+        @_erb_buf << "<div style=\"font-weight:bold\">----- cached key=#{cache_key.inspect} -----</div>\n" if show_area
+        @_erb_buf << piece
+        @_erb_buf << "<div style=\"font-weight:bold\">----- /cached -----</div>\n" if show_area
+      else
+        Merb.logger.debug "[piece_cache] #{cache_key.inspect}: expired or not found."
+        values = @_callback && @_callback.call(cache_key) || {}
+        #values.each_pair {|k, v| self.instance_variable_set("@#{k}", v) } if values.is_a?(Hash)
+        @_erb_buf << "<div style=\"font-weight:bold;color:red\">----- rendered key=#{cache_key.inspect} -----</div>\n" if show_area
+        pos = @_erb_buf.length
+        yield(values)
+        piece = @_erb_buf[pos..-1]
+        @_erb_buf << "<div style=\"font-weight:bold;color:red\">----- /rendered -----</div>\n" if show_area
+        cache_store.write(cache_key, piece, :lifetime=>lifetime, :content_type=>self.content_type)
+      end
+      nil
+    end
+
+    alias cache_with piece_cache
+
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: merb_piece_cache
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- makoto kuwata
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-30 00:00:00 +09:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: called_from
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.0
+    version: 
+description: Merb plugin to cache html fragment
+email: kwa.at.kuwata-lab.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- MIT-LICENSE
+- TODO
+files: 
+- MIT-LICENSE
+- README
+- Rakefile
+- TODO
+- lib/merb_piece_cache/file_cache_store.rb
+- lib/merb_piece_cache/helpers.rb
+- lib/merb_piece_cache.rb
+has_rdoc: true
+homepage: http://github.com/kwatch/merb_piece_cache/
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: merb_piece_cache
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Merb plugin to cache html fragment
+test_files: []
+