sinatra-cache 0.2.3 → 0.3.0

data/.gitignore

@@ -1,9 +1,16 @@
-## OS SPECIFIC
+## OS STUFF
 .DS_Store
+
+## TM SPECIFIC
 *.tmproj
-## 
-# ignore the gem dir
-pkg/*
-vendor/*
-fixtures/public/*
-fixtures/cache/*
+tmtags
+
+## PROJECT::GENERAL
+*.sw?
+coverage
+rdoc
+pkg
+doc
+
+## PROJECT::SPECIFIC
+spec/fixtures/public/*

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2008 kematzy
+Copyright (c) 2009 kematzy
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.rdoc

@@ -0,0 +1,394 @@
+= Sinatra::Cache
+
+A Sinatra Extension that makes Page and Fragment Caching easy.
+
+
+== IMPORTANT INFORMATION
+
+<b>This is a completely rewritten extension that basically breaks all previous versions of it.</b>
+
+So use with care!  You have been warned ;-)
+
+---- 
+
+
+
+With that said, on to the real stuff.
+
+
+== 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) }            # => cached as '../index.html'
+    
+    get('/contact') { erb(:contact) }   # => cached as '../contact.html'
+    
+    # NB! the trailing slash on the URL
+    get('/about/') { erb(:about) }      # => cached as '../about/index.html'
+    
+    get('/feed.rss') { builder(:feed) }  # => 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  => cached as ../articles/a/b/c.html
+    
+    # NB! the trailing slash on the URL
+    # with the '/articles/a/b/c/  => cached as ../articles/a/b/c/index.html
+    
+    # CSS caching via Sass  # => 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'd 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.
+
+
+== RTFM
+
+If the above is not clear enough, please check the Specs for a better understanding.
+
+
+== Errors / Bugs
+
+If something is not behaving intuitively, it is a bug, and should be reported.
+Report it here: http://github.com/kematzy/sinatra-cache/issues 
+
+
+== TODOs
+
+* Improve the fragment caching functionality
+  
+  * Decide on how to handle site-wide shared fragments.
+  
+  * Make the shared fragments more dynamic or usable
+
+* Work out how to use the <tt>cache_expire()</tt> functionality in a logical way.
+
+* Work out and include instructions on how to use a '../public/custom/cache/dir' with Passenger.
+
+* Write more tests to ensure everything is very solid.
+
+* Any other improvements you or I can think of.
+
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  * (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2009-2010 kematzy. Released under the MIT License.
+
+See LICENSE for details.
+
+=== Credits
+
+Included in this gem is code from <tt>SinatraMore::OutputHelpers</tt>, taken from the
+<tt>sinatra_more</tt> gem [ http://github.com/nesquena/sinatra_more/ ] by Nathan Esquenazi.
+
+The code was renamed to Sinatra::Output to prevent any extension clashes. 
+
+Copyright (c) 2009 Nathan Esquenazi.  Released under the MIT License.
+
+
+A big <b>Thank You!</b> goes to rtomayko[http://github/rtomayko], blakemizerany[http://github.com/blakemizerany/] 
+and others working on the Sinatra framework.
+
+=== Inspirations
+
+Inspired by code from Rails[http://rubyonrails.com/] & Merb[http://merbivore.com/]
+and other sources
+

data/Rakefile

@@ -5,42 +5,85 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "sinatra-cache"
-    gem.summary = %Q{Simple Page Caching for Sinatra [www.sinatrarb.com]}
+    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.description = "Simple Page Caching for Sinatra [www.sinatrarb.com]"
     gem.authors = ["kematzy"]
+    gem.add_dependency('sinatra', '>=1.0.a')
+    # gem.add_dependency('dependency', '>=x.x.x')
+    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 not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+  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 verbosely"
+  Spec::Rake::SpecTask.new(:verbose) do |t|
+    t.libs << "lib"
+    t.spec_opts = ["--color", "--format", "specdoc", "--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'
-  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.title = "Sinatra::Cache v#{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib' << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
+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
 
-# begin
-#   require 'rcov/rcovtask'
-#   Rcov::RcovTask.new do |t|
-#     t.libs << 'test'
-#     t.test_files = FileList['test/**/*_test.rb']
-#     t.verbose = true
-#   end
-# rescue LoadError
-#   puts "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
-# end
-# 
-
-task :default => :test
+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