benjaminjackson-sinatra-cache 0.3.8

data/Rakefile

@@ -0,0 +1,89 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sinatra-cache"
+    gem.summary = %Q{A Sinatra Extension that makes Page and Fragment Caching easy.}
+    gem.description = %Q{A Sinatra Extension that makes Page and Fragment Caching easy.}
+    gem.email = "kematzy@gmail.com"
+    gem.homepage = "http://github.com/kematzy/sinatra-cache"
+    gem.authors = ["kematzy"]
+    gem.add_dependency('sinatra', '>=1.1.0')
+    gem.add_dependency('sinatra-outputbuffer', '>=0.1.0')
+    gem.add_development_dependency "sinatra-tests", ">= 0.1.6"
+    gem.add_development_dependency "rspec", ">= 1.3.0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_opts = ["--color", "--format", "specdoc", "--require", "spec/spec_helper.rb"]  
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_opts = ["--color", "--format", "specdoc", "--require", "spec/spec_helper.rb"]
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+namespace :spec do
+  
+  desc "Run all specifications quietly"
+  Spec::Rake::SpecTask.new(:quiet) do |t|
+    t.libs << "lib"
+    t.spec_opts = ["--color", "--require", "spec/spec_helper.rb"]
+  end
+  
+  desc "Run specific spec verbosely (SPEC=/path/2/file)"
+  Spec::Rake::SpecTask.new(:select) do |t|
+    t.libs << "lib"
+    t.spec_files = [ENV["SPEC"]]
+    t.spec_opts = ["--color", "--format", "specdoc", "--require", "spec/spec_helper.rb"] 
+  end
+  
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? IO.read('VERSION').chomp : "[Unknown]"
+  
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Sinatra::Cache v#{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc 'Build the rdoc HTML Files'
+task :docs do
+  version = File.exist?('VERSION') ? IO.read('VERSION').chomp : "[Unknown]"
+    
+  sh "sdoc -N --title 'Sinatra::Cache v#{version}' lib/ README.rdoc"
+end
+
+namespace :docs do
+  
+  desc 'Remove rdoc products'
+  task :remove => [:clobber_rdoc]
+  
+  desc 'Force a rebuild of the RDOC files'
+  task :rebuild => [:rerdoc]
+  
+  desc 'Build docs, and open in browser for viewing (specify BROWSER)'
+  task :open => [:docs] do
+    browser = ENV["BROWSER"] || "safari"
+    sh "open -a #{browser} doc/index.html"
+  end
+  
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.8

data/lib/sinatra/cache.rb

@@ -0,0 +1,13 @@
+
+require 'sinatra/outputbuffer'
+
+module Sinatra
+  module Cache
+    VERSION = '0.3.8' unless const_defined?(:VERSION)
+    def self.version; "Sinatra::Cache v#{VERSION}"; end
+  end #/ Cache
+end #/ Sinatra
+
+%w(templates cache/helpers).each do |lib|
+  require "sinatra/#{lib}"
+end

data/lib/sinatra/cache/helpers.rb

@@ -0,0 +1,667 @@
+
+module Sinatra 
+  
+  # = Sinatra::Cache
+  # 
+  # A Sinatra Extension that makes Page and Fragment Caching easy wthin your Sinatra apps.
+  # 
+  # == Installation
+  # 
+  #   #  Add RubyGems.org (former Gemcutter) to your RubyGems sources 
+  #   $  gem sources -a http://rubygems.org
+  # 
+  #   $  (sudo)? gem install sinatra-cache
+  # 
+  # == Dependencies
+  # 
+  # This Gem depends upon the following:
+  # 
+  # === Runtime:
+  # 
+  # * sinatra ( >= 1.0.a )
+  # * sinatra-outputbuffer[http://github.com/kematzy/sinatra-outputbuffer] (>= 0.1.0)
+  # 
+  # Optionals:
+  # 
+  # * sinatra-settings[http://github.com/kematzy/sinatra-settings] (>= 0.1.1) # to view default settings in a browser display.
+  # 
+  # === Development & Tests:
+  # 
+  # * rspec (>= 1.3.0 )
+  # * rack-test (>= 0.5.3)
+  # * rspec_hpricot_matchers (>= 0.1.0)
+  # * sinatra-tests (>= 0.1.6)
+  # * fileutils
+  # * sass
+  # * ostruct
+  # * yaml
+  # * json
+  # 
+  # 
+  # == Getting Started
+  # 
+  # To start caching your app's ouput, just require and register 
+  # the extension in your sub-classed Sinatra app:
+  # 
+  #   require 'sinatra/cache'
+  # 
+  #   class YourApp < Sinatra::Base
+  # 
+  #     # NB! you need to set the root of the app first
+  #     set :root, '/path/2/the/root/of/your/app'
+  # 
+  #     register(Sinatra::Cache)
+  # 
+  #     set :cache_enabled, true  # turn it on
+  # 
+  #     <snip...>
+  # 
+  #   end
+  # 
+  # 
+  # That's more or less it. 
+  # 
+  # You should now be caching your output by default, in <tt>:production</tt> mode, as long as you use 
+  # one of Sinatra's render methods:
+  # 
+  #   erb(),  erubis(), haml(), sass(), builder(), etc..
+  # 
+  # ...or any render method that uses <tt>Sinatra::Templates#render()</tt> as its base.
+  # 
+  # 
+  # 
+  # == Configuration Settings
+  # 
+  # The default settings should help you get moving quickly, and are fairly common sense based.
+  # 
+  # 
+  # === <tt>:cache_enabled</tt>
+  # 
+  # This setting toggles the cache functionality On / Off. 
+  # Default is: <tt>false</tt>
+  # 
+  # 
+  # === <tt>:cache_environment</tt>
+  # 
+  # Sets the environment during which the cache functionality is active. 
+  # Default is: <tt>:production</tt>
+  # 
+  # 
+  # === <tt>:cache_page_extension</tt>+ 
+  # 
+  # Sets the default file extension for cached files. 
+  # Default is: <tt>.html</tt>
+  # 
+  # 
+  # === <tt>:cache_output_dir</tt>
+  # 
+  # Sets cache directory where the cached files are stored. 
+  # Default is:  == "/path/2/your/app/public"
+  # 
+  # Although you can set it to the more ideal '<tt>..public/system/cache/</tt>' 
+  # if you can get that to work with your webserver setup.
+  # 
+  # 
+  # === <tt>:cache_fragments_output_dir</tt>
+  # 
+  # Sets the directory where cached fragments are stored. 
+  # Default is the '../tmp/cache_fragments/' directory at the root of your app.
+  # 
+  # This is for security reasons since you don't really want your cached fragments publically available.
+  # 
+  # 
+  # === <tt>:cache_fragments_wrap_with_html_comments</tt>
+  # 
+  # This setting toggles the wrapping of cached fragments in HTML comments. (see below)
+  # Default is: <tt>true</tt>
+  # 
+  # 
+  # === <tt>:cache_logging</tt>
+  # 
+  # This setting toggles the logging of various cache calls. If the app has access to the <tt>#logger</tt> method,
+  # curtesy of Sinatra::Logger[http://github.com/kematzy/sinatra-logger] then it will log there, otherwise logging 
+  # is silent.
+  # 
+  # Default is: <tt>true</tt>
+  # 
+  # 
+  # === <tt>:cache_logging_level</tt>
+  # 
+  # Sets the level at which the cache logger should log it's messages. 
+  # Default is: <tt>:info</tt>
+  # 
+  # Available options are: [:fatal, :error, :warn, :info, :debug]
+  # 
+  # 
+  # == Basic Page Caching
+  # 
+  # By default caching only happens in <tt>:production</tt> mode, and via the Sinatra render methods, erb(), etc,
+  # 
+  # So asuming we have the following setup (continued from above)
+  # 
+  # 
+  #   class YourApp
+  # 
+  #     <snip...>
+  # 
+  #     set :cache_output_dir, "/full/path/2/app/root/public/system/cache"
+  # 
+  #     <snip...>
+  # 
+  #     get('/') { erb(:index) }            # => is cached as '../index.html'
+  # 
+  #     get('/contact') { erb(:contact) }   # => is cached as '../contact.html'
+  # 
+  #     # NB! the trailing slash on the URL
+  #     get('/about/') { erb(:about) }      # => is cached as '../about/index.html'
+  # 
+  #     get('/feed.rss') { builder(:feed) }  # => is cached as '../feed.rss' 
+  #     # NB! uses the extension of the passed URL, 
+  #     # but DOES NOT ensure the format of the content based on the extension provided.
+  # 
+  #     # complex URL with multiple possible params  
+  #     get %r{/articles/?([\s\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?/?([\w-]+)?}  do
+  #       erb(:articles)
+  #     end
+  #     # with the '/articles/a/b/c  => is cached as ../articles/a/b/c.html
+  # 
+  #     # NB! the trailing slash on the URL
+  #     # with the '/articles/a/b/c/  => is cached as ../articles/a/b/c/index.html
+  # 
+  #     # CSS caching via Sass  # => is cached as '.../css/screen.css'
+  #     get '/css/screen.css' do 
+  #       content_type 'text/css'
+  #       sass(:'css/screen')
+  #     end
+  # 
+  #     # to turn off caching on certain pages.
+  #     get('/dont/cache/this/page') { erb(:aview, :cache => false) }   # => is NOT cached
+  # 
+  # 
+  #     # NB! any query string params - [ /?page=X&id=y ] - are stripped off and TOTALLY IGNORED 
+  #     # during the caching process.
+  # 
+  #   end
+  # 
+  # OK, that's about all you need to know about basic Page Caching right there. Read the above example
+  # carefully until you understand all the variations.
+  # 
+  # 
+  # == Fragment Caching 
+  # 
+  # If you just need to cache a fragment of a page, then you would do as follows:
+  # 
+  #   class YourApp
+  # 
+  #     set :cache_fragments_output_dir, "/full/path/2/fragments/store/location"
+  # 
+  #   end
+  # 
+  # Then in your views / layouts add the following:
+  # 
+  #   <% cache_fragment(:name_of_fragment) do %>
+  #    # do something worth caching
+  #   <% end %>
+  # 
+  # 
+  # Each fragment is stored in the same directory structure as your request
+  # so, if you have a request like this:
+  # 
+  #   get '/articles/2010/02' ...
+  # 
+  # ...the cached fragment will be stored as:
+  # 
+  #   ../tmp/cache_fragments/articles/2010/02/< name_of_fragment >.html
+  # 
+  # This enables you to use similar names for your fragments or have 
+  # multiple URLs use the same view / layout.
+  # 
+  # 
+  # === An important limitation
+  # 
+  # The fragment caching is dependent upon the final URL, so in the case of 
+  # a blog, where each article uses the same view, but through different URLs,
+  # each of the articles would cache it's own fragment, which is ineffecient.
+  # 
+  # To sort-of deal with this limitation I have temporarily added a very hackish 
+  # 'fix' through adding a 2nd parameter (see example below), which will remove the 
+  # last part of the URL and use the rest of the URL as the stored fragment path.
+  # 
+  # So given the URL:
+  # 
+  #   get '/articles/2010/02/fragment-caching-with-sinatra-cache' ...
+  # 
+  # and the following <tt>#cache_fragment</tt> declaration in your view
+  # 
+  #   <% cache_fragment(:name_of_fragment, :shared) do %>
+  #     # do something worth caching
+  #   <% end %>
+  # 
+  # ...the cached fragment would be stored as:
+  # 
+  #   ../tmp/cache_fragments/articles/2010/02/< name_of_fragment >.html
+  # 
+  # Any other URLs with the same URL root, like...
+  # 
+  #   get '/articles/2010/02/writing-sinatra-extensions' ...
+  # 
+  # ... would use the same cached fragment.
+  # 
+  # 
+  # <b>NB!</b> currently only supports one level, but Your fork might fix that ;-)
+  # 
+  # 
+  # == Cache Expiration
+  # 
+  # <b>Under development, and not entirely final.</b> See Todo's below for more info.
+  # 
+  # 
+  # To expire a cached item - file or fragment - you use the :cache_expire() method.
+  # 
+  # 
+  #   cache_expire('/contact')  =>  expires ../contact.html
+  # 
+  # 
+  #   # NB! notice the trailing slash
+  #   cache_expire('/contact/')  =>  expires ../contact/index.html
+  # 
+  # 
+  #   cache_expire('/feed.rss')  =>  expires ../feed.rss
+  # 
+  # 
+  # To expire a cached fragment:
+  # 
+  #   cache_expire('/some/path', :fragment => :name_of_fragment )  
+  # 
+  #     =>  expires ../some/path/:name_of_fragment.html
+  # 
+  # 
+  # 
+  # == A few important points to consider 
+  # 
+  # 
+  # === The DANGERS of URL query string params
+  # 
+  # By default the caching ignores the query string params, but that's not the only problem with query params.
+  # 
+  # Let's say you have a URL like this:
+  # 
+  #   /products/?product_id=111
+  # 
+  # and then inside that template [ .../views/products.erb ], you use the <tt>params[:product_id]</tt> 
+  # param passed in for some purpose.
+  # 
+  #   <ul>
+  #     <li>Product ID: <%= params[:product_id] %></li>  # => 111
+  #     ...
+  #   </ul>
+  # 
+  # If you cache this URL, then the cached file [ ../cache/products.html ] will be stored with that
+  # value embedded. Obviously not ideal for any other similar URLs with different <tt>product_id</tt>'s
+  # 
+  # To overcome this issue, use either of these two methods.
+  # 
+  #   # in your_app.rb
+  # 
+  #   # turning off caching on this page
+  # 
+  #   get '/products/' do
+  #     ...
+  #     erb(:products, :cache => false)
+  #   end
+  # 
+  #   # or
+  # 
+  #   # rework the URLs to something like '/products/111 '
+  # 
+  #   get '/products/:product_id' do
+  #     ...
+  #     erb(:products)
+  #   end
+  # 
+  # 
+  # 
+  # Thats's about all the information you need to know.
+  # 
+  # 
+  module Cache
+    
+    module Helpers 
+      
+      ##
+      # This method either caches the code fragment and then renders it,
+      # or locates the cached fragement and renders that.
+      # 
+      # By default the cached fragement is stored in the ../tmp/cache_fragments/ 
+      # directory at the root of your app.
+      # 
+      # Each fragment is stored in the same directory structure as your request
+      # so, if you have a request like this:
+      # 
+      #   get '/articles/2010/02' ...
+      # 
+      # ...the cached fragment will be stored as:
+      # 
+      #   ../tmp/cache_fragments/articles/2010/02/< name_of_fragment >.html
+      # 
+      # This enables you to use similar names for your fragments or have 
+      # multiple URLs use the same view / layout.
+      # 
+      # ==== Examples
+      # 
+      #   <% cache_fragment(:name_of_fragment) do %>
+      #     # do something worth caching
+      #   <% end %>
+      # 
+      # === GOTCHA
+      # 
+      # The fragment caching is dependent upon the final URL, so in the case of 
+      # a blog, where each article uses the same view, but through different URLs,
+      # each of the articles would cache it's own fragment.
+      # 
+      # To sort-of deal with this limitation I have added a very hackish 'fix'
+      # through adding a 2nd parameter (see example below), which will 
+      # remove the last part of the URL and use the rest of the URL as 
+      # the stored fragment path.
+      # 
+      # ==== Example
+      # 
+      # Given the URL:
+      # 
+      #   get '/articles/2010/02/fragment-caching-with-sinatra-cache' ...
+      # 
+      # and the following <tt>#cache_fragment</tt> declaration in your view
+      # 
+      #   <% cache_fragment(:name_of_fragment, :shared) do %>
+      #     # do something worth caching
+      #   <% end %>
+      # 
+      # ...the cached fragment would be stored as:
+      # 
+      #   ../tmp/cache_fragments/articles/2010/02/< name_of_fragment >.html
+      # 
+      # Any other URLs with the same URL root, like...
+      # 
+      #   get '/articles/2010/02/writing-sinatra-extensions' ...
+      # 
+      # ... would use the same cached fragment.
+      # 
+      # @api public
+      def cache_fragment(fragment_name, shared = nil, &block) 
+        # 1. check for a block, there must always be a block
+        raise ArgumentError, "Missing block" unless block_given?
+        
+        # 2. get the fragment path, by combining the PATH_INFO of the request, and the fragment_name
+        dir_structure = request.path_info.empty? ? '' : request.path_info.gsub(/^\//,'').gsub(/\/$/,'')
+        # if we are sharing this fragment with other URLs (as in the all the articles in a category of a blog) 
+        # then lob off the last part of the URL
+        unless shared.nil?
+          dirs = dir_structure.split('/')
+          dir_structure = dirs.first(dirs.length-1).join('/')
+        end
+        cf = "#{settings.cache_fragments_output_dir}/#{dir_structure}/#{fragment_name}.html"
+        # 3. ensure the fragment cache directory exists for this fragment
+        FileUtils.mkdir_p(File.dirname(cf)) rescue "ERROR: could NOT create the cache directory: [ #{File.dirname(cf)} ]"
+        
+        # 3. check if the fragment is already cached ?
+        if test(?f, cf)
+          # 4. yes. cached, so load it up into the ERB buffer .  Sorry, don't know how to do this for Haml or any others.
+          block_content = IO.read(cf)
+        else
+          # 4. not cached, so process the block and then cache it
+          block_content = capture_html(&block) if block_given?
+          # 5. add some timestamp comments around the fragment, if the end user wants it
+          if settings.cache_fragments_wrap_with_html_comments
+            content_2_cache = "<!-- cache fragment: #{dir_structure}/#{fragment_name} -->"
+            content_2_cache << block_content
+            content_2_cache << "<!-- /cache fragment: #{fragment_name} cached at [ #{Time.now.strftime("%Y-%m-%d %H:%M:%S")}] -->\n"
+          else
+            content_2_cache = block_content
+          end
+          # 6. write it to cache
+          cache_write_file(cf, content_2_cache)
+        end
+        # 5. 'return' the content by
+        block_is_template?(block) ? concat_content(block_content) : block_content
+      end
+      # for future versions once old habits are gone
+      # alias_method :cache, :cache_fragment
+      
+      
+      ##
+      # <b>NB!! Deprecated method.</b>
+      # 
+      # Just returns the content after throwing out a warning.
+      # 
+      def cache(content, opts={}) 
+        warn("Deprecated method, caching is now happening by default if the :cache_enabled option is true")
+        content
+      end
+      
+      
+      ##
+      # Expires the cached file (page) or fragment.
+      #  
+      # ==== Examples
+      # 
+      #   cache_expire('/contact')  =>  expires ../contact.html
+      # 
+      #   cache_expire('/feed.rss')  =>  expires ../feed.rss
+      # 
+      # To expire a cached fragment:
+      # 
+      #   cache_expire('/some/path', :fragment => :name_of_fragment )  
+      #     =>  expires ../some/path/:name_of_fragment.html
+      # 
+      # 
+      # @api public
+      def cache_expire(path, options={}) 
+        # 1. bail quickly if we don't have caching enabled
+        return unless settings.cache_enabled
+        options = { :fragment => false }.merge(options)
+        
+        if options[:fragment] # dealing with a fragment 
+          dir_structure = path.gsub(/^\//,'').gsub(/\/$/,'')
+          file_path = "#{settings.cache_fragments_output_dir}/#{dir_structure}/#{options[:fragment]}.html"
+        else
+          file_path = cache_file_path(path)
+        end
+        
+        if test(?f, file_path)
+          File.delete(file_path)
+          log(:info,"Expired [#{file_path.sub(settings.root,'')}] successfully")
+        else
+          log(:warn,"The cached file [#{file_path}] could NOT be expired as it was NOT found")
+        end
+      end
+      
+      
+      ##
+      # Prints a basic HTML comment with a timestamp in it, so that you can see when a file was cached last.
+      # 
+      # *NB!* IE6 does NOT like this to be the first line of a HTML document, so output
+      # inside the <head> tag. Many hours wasted on that lesson ;-)
+      # 
+      # ==== Examples 
+      # 
+      #   <%= cache_timestamp %>  # => <!--  page cached: 2009-12-21 12:00:00 -->
+      # 
+      # @api public
+      def cache_timestamp 
+        if settings.cache_enabled && settings.cache_environment == settings.environment
+          "<!-- page cached: #{Time.now.strftime("%Y-%m-%d %H:%M:%S")} -->\n"
+        end
+      end
+      # backwards compat and syntactic sugar for others
+      alias_method :cache_page_timestamp, :cache_timestamp
+      alias_method :page_cached_at, :cache_timestamp
+      
+      
+      ## PRIVATE METHODS
+      private
+        
+        ##
+        # Converts the PATH_INFO path into the full cached file path.
+        # 
+        # ==== GOTCHA:
+        # 
+        # <b>NB!</b> completely ignores the URL query params passed such as 
+        # in this example:
+        # 
+        #   /products?page=2 
+        # 
+        # To capture and cache those query strings, please do as follows:
+        # 
+        #   get 'products/page/:page' { ... }  # in your Sinatra app
+        # 
+        #   /products/page/2  => .../public/cache/products/page/2.html
+        # 
+        #  
+        # ==== Examples
+        # 
+        #   /  => .../public/cache/index.html
+        # 
+        #   /contact  => .../public/cache/contact.html
+        # 
+        #   /contact/  => .../public/cache/contact/index.html
+        # 
+        # 
+        # @api public
+        def cache_file_path(in_path = nil) 
+          path = settings.send(:cache_output_dir).dup
+          
+          
+          path_info = in_path.nil? ? request.path_info : in_path
+          if (path_info.empty? || path_info == "/" ) 
+            path << "/index"
+          elsif ( path_info[-1, 1] == '/' )
+            path << ::Rack::Utils.unescape(path_info.chomp('/') << '/index')
+          else
+             path << ::Rack::Utils.unescape(path_info.chomp('/'))
+          end
+          path << settings.cache_page_extension if File.extname(path) == ''
+          return path
+        end
+        
+        ##
+        # Writes the cached file to disk, only during GET requests, 
+        # and then returns the content.
+        # 
+        # ==== Examples
+        # 
+        # 
+        # @api private
+        def cache_write_file(cache_file, content) 
+          # only cache GET request [http://rack.rubyforge.org/doc/classes/Rack/Request.html#M000239]
+          if request.get?
+            FileUtils.mkdir_p(File.dirname(cache_file)) rescue "ERROR: could NOT create the cache directory: [ #{File.dirname(cache_file)} ]"
+            File.open(cache_file, 'wb'){ |f| f << content}
+          end
+          return content
+        end
+        
+        ##
+        # Establishes the file name of the cached file from the path given
+        # 
+        # @api private
+        def cache_file_name(path, options={}) 
+          name = (path.empty? || path == "/") ? "index" : Rack::Utils.unescape(path.sub(/^(\/)/,'').chomp('/'))
+          name << settings.cache_page_extension unless (name.split('/').last || name).include? '.'
+          return name
+        end
+        
+        ##
+        # Sets the full path to the cached page/file
+        # Dependent upon Sinatra.options .public and .cache_dir variables being present and set.
+        # 
+        # 
+        # @api private
+        def cache_page_path(path, options={}) 
+          # test if given a full path rather than relative path, otherwise join the public path to cache_dir 
+          # and ensure it is a full path
+          cache_dir = (settings.cache_output_dir == File.expand_path(settings.cache_output_dir)) ? 
+              settings.cache_output_dir : File.expand_path("#{settings.public_folder}/#{settings.cache_output_dir}")
+          cache_dir = cache_output_dir[0..-2] if cache_dir[-1,1] == '/'
+          "#{cache_dir}/#{cache_file_name(path, options)}"
+        end
+        
+        ##
+        # Convenience method that handles logging of Cache related stuff.
+        # 
+        # Uses Sinatra::Logger's #logger method if available, otherwise just
+        # puts out the log message.
+        # 
+        def log(scope, msg) 
+          if settings.cache_logging
+            if scope.to_sym == settings.cache_logging_level.to_sym
+              if self.respond_to?(:logger)
+                logger.send(scope, msg) 
+              else
+                puts "#{scope.to_s.upcase}: #{msg}"
+              end
+            end
+          end
+        end
+        
+      
+    end #/ Helpers
+    
+    
+    ##
+    # The default options:
+    # 
+    # * +:cache_enabled+ => toggle for the cache functionality. Default is: +false+
+    # 
+    # * +:cache_environment+ => sets the environment during which to cache. Default is: +:production+
+    # 
+    # * +:cache_page_extension+ => sets the default extension for cached files. Default is: +.html+
+    # 
+    # * +:cache_output_dir+ => sets cache directory where cached files are stored. Default is: == "/path/2/your/app/public"
+    #   Although you can set it to the more ideal '<tt>..public/system/cache/</tt>' 
+    #   if you can get that to work with your webserver setup.
+    # 
+    # * +:cache_fragments_output_dir+ => sets the directory where cached fragments are stored. 
+    #   Default is the '../tmp/cache_fragments/' directory at the root of your app.
+    # 
+    # * +:cache_fragments_wrap_with_html_comments+ => toggle for wrapping the cached fragment in HTML comments. 
+    #   Default is: +true+
+    # 
+    # * +:cache_logging+ => toggle for logging the cache calls. Default is: +true+
+    # 
+    # * +:cache_logging_level+ => sets the level of the cache logger. Default is: <tt>:info</tt>.<br>
+    #   Available options are: [:fatal, :error, :warn, :info, :debug]
+    # 
+    # 
+    def self.registered(app)
+      app.register(Sinatra::OutputBuffer)
+      app.helpers Cache::Helpers
+      
+      ## CONFIGURATIONS::
+      app.set :cache_enabled, false
+      app.set :cache_environment, :production
+      app.set :cache_page_extension, '.html'
+      app.set :cache_output_dir, lambda { app.public_folder }
+      app.set :cache_fragments_output_dir, lambda { "#{app.root}/tmp/cache_fragments" }
+      app.set :cache_fragments_wrap_with_html_comments, true
+      
+      app.set :cache_logging, true
+      app.set :cache_logging_level, :info
+      
+      
+      ## add the extension specific options to those inspectable by :settings_inspect method
+      if app.respond_to?(:sinatra_settings_for_inspection)
+        %w( cache_enabled cache_environment cache_page_extension cache_output_dir
+            cache_fragments_output_dir cache_fragments_wrap_with_html_comments 
+            cache_logging cache_logging_level
+        ).each do |m|
+          app.sinatra_settings_for_inspection << m
+        end
+      end
+      
+    end #/ self.registered
+    
+  end #/ Cache
+  
+  register(Sinatra::Cache) # support classic apps
+  
+end #/ Sinatra