RubyGems - sinatra-cache - Versions diffs - 0.2.3 → 0.3.0 - Mend

sinatra-cache 0.2.3 → 0.3.0

Files changed (27) hide show

data/.gitignore +14 -7
data/LICENSE +1 -1
data/README.rdoc +394 -0
data/Rakefile +66 -23
data/VERSION +1 -0
data/lib/sinatra/cache.rb +10 -136
data/lib/sinatra/cache/helpers.rb +663 -0
data/lib/sinatra/output.rb +147 -0
data/lib/sinatra/templates.rb +55 -0
data/sinatra-cache.gemspec +30 -20
data/spec/fixtures/apps/base/views/css.sass +2 -0
data/spec/fixtures/apps/base/views/fragments.erb +11 -0
data/spec/fixtures/apps/base/views/fragments_shared.erb +11 -0
data/{test/fixtures → spec/fixtures/apps/base}/views/index.erb +0 -0
data/spec/fixtures/apps/base/views/layout.erb +9 -0
data/spec/fixtures/apps/base/views/params.erb +3 -0
data/spec/sinatra/cache_spec.rb +593 -0
data/spec/spec_helper.rb +62 -0
metadata +73 -24
data/README.md +0 -121
data/VERSION.yml +0 -4
data/test/SPECS.rdoc +0 -95
data/test/cache_test.rb +0 -434
data/test/fixtures/classic.rb +0 -25
data/test/fixtures/myapp.rb +0 -36
data/test/fixtures/myapp_default.rb +0 -37
data/test/helper.rb +0 -62

data/VERSION ADDED Viewed

	@@ -0,0 +1 @@
1	+ 0.3.0

data/lib/sinatra/cache.rb CHANGED Viewed

@@ -1,139 +1,13 @@
-require 'fileutils'
 require 'sinatra/base'
-module Sinatra
-  # Sinatra Caching module
-  #
-  #  TODO:: Need to write documentation here
-  #
+module Sinatra
   module Cache
-    VERSION = 'Sinatra::Cache v0.2.2'
-    def self.version; VERSION; end
-    module Helpers
-      # Caches the given URI to a html file in /public
-      #
-      # <b>Usage:</b>
-      #    >> cache( erb(:contact, :layout => :layout))
-      #      =>  returns the HTML output written to /public/<CACHE_DIR_PATH>/contact.html
-      #
-      # Also accepts an Options Hash, with the following options:
-      #  * :extension => in case you need to change the file extension
-      #
-      #  TODO:: implement the opts={} hash functionality. What other options are needed?
-      #
-      def cache(content, opts={})
-        return content unless options.cache_enabled
-        unless content.nil?
-          content = "#{content}\n#{page_cached_timestamp}"
-          path = cache_page_path(request.path_info,opts)
-          FileUtils.makedirs(File.dirname(path))
-          open(path, 'wb+') { |f| f << content }
-          log("Cached Page: [#{path}]",:info)
-          content
-        end
-      end
-      # Expires the cached URI (as .html file) in /public
-      #
-      # <b>Usage:</b>
-      #    >> cache_expire('/contact')
-      #      =>  deletes the /public/<CACHE_DIR_PATH>contact.html page
-      #
-      #    get '/contact' do
-      #     cache_expire   # deletes the /public/<CACHE_DIR_PATH>contact.html page as well
-      #    end
-      #
-      #  TODO:: implement the options={} hash functionality. What options are really needed ?
-      def cache_expire(path = nil, opts={})
-        return unless options.cache_enabled
-        path = (path.nil?) ? cache_page_path(request.path_info) : cache_page_path(path)
-        if File.exist?(path)
-          File.delete(path)
-          log("Expired Page deleted at: [#{path}]",:info)
-        else
-          log("No Expired Page was found at the path: [#{path}]",:info)
-        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 ;-)
-      #
-      # <b>Usage:</b>
-      #    >> <%= page_cached_timestamp %>
-      #      => <!--  page cached: 2009-02-24 12:00:00 -->
-      #
-      def page_cached_timestamp
-        "<!-- page cached: #{Time.now.strftime("%Y-%d-%m %H:%M:%S")} -->\n" if options.cache_enabled
-      end
-      private
-        # Establishes the file name of the cached file from the path given
-        #
-        # TODO:: implement the opts={} functionality, and support for custom extensions on a per request basis.
-        #
-        def cache_file_name(path,opts={})
-          name = (path.empty? || path == "/") ? "index" : Rack::Utils.unescape(path.sub(/^(\/)/,'').chomp('/'))
-          name << options.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.
-        #
-        def cache_page_path(path,opts={})
-          # 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 = (options.cache_output_dir == File.expand_path(options.cache_output_dir)) ?
-              options.cache_output_dir : File.expand_path("#{options.public}/#{options.cache_output_dir}")
-          cache_dir = cache_output_dir[0..-2] if cache_dir[-1,1] == '/'
-          "#{cache_dir}/#{cache_file_name(path,opts)}"
-        end
-        #  TODO:: this implementation really stinks, how do I incorporate Sinatra's logger??
-        def log(msg,scope=:debug)
-          if options.cache_logging
-            "Log: msg=[#{msg}]" if scope == options.cache_logging_level
-          else
-            # just ignore the stuff...
-            # puts "just ignoring msg=[#{msg}] since cache_logging => [#{options.cache_logging.to_s}]"
-          end
-        end
-    end #/module Helpers
-    # Sets the default options:
-    #
-    #  * +:cache_enabled+ => toggle for the cache functionality. Default is: +true+
-    #  * +:cache_page_extension+ => sets the default extension for cached files. Default is: +.html+
-    #  * +:cache_dir+ => sets cache directory where cached files are stored. Default is: ''(empty) == root of /public.<br>
-    #      set to empty, since the ideal 'system/cache/' does not work with Passenger & mod_rewrite :(
-    #  * +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>
-    #      Options:(unused atm) [:info, :warn, :debug]
-    #
-    def self.registered(app)
-      app.helpers(Cache::Helpers)
-      app.set :cache_enabled, true
-      app.set :cache_page_extension, '.html'
-      app.set :cache_output_dir, ''
-      app.set :cache_logging, true
-      app.set :cache_logging_level, :info
-    end
-  end #/module Cache
-  register(Sinatra::Cache)
-end #/module Sinatra
+    VERSION = '0.3.0' unless const_defined?(:VERSION)
+    def self.version; "Sinatra::Cache v#{VERSION}"; end
+  end #/ Cache
+end #/ Sinatra
+%w(templates output cache/helpers).each do |lib|
+  require "sinatra/#{lib}"
+end

data/lib/sinatra/cache/helpers.rb ADDED Viewed

@@ -0,0 +1,663 @@
+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 )
+  #
+  #
+  # === 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}/#{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.helpers Sinatra::Output::Helpers
+      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 }
+      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) # not really needed here
+end #/ Sinatra