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

sinatra-cache 0.2.3 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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