Permalink
Browse files

Updated License, README and Rakefile

  • Loading branch information...
kematzy committed Nov 4, 2009
1 parent 9b36d04 commit da5f5566accf34c8ba74e17cc85810f44a54c90d
Showing with 236 additions and 29 deletions.
  1. +1 −1 LICENSE
  2. +164 −0 README.rdoc
  3. +71 −28 Rakefile
View
@@ -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
View
@@ -0,0 +1,164 @@
+= Sinatra::Cache
+
+Adds a very *simple* Page Caching functionality to "Sinatra":http://www.sinatrarb.com/
+
+<hr>
+
+== *PLEASE KEEP THIS IN MIND*
+
+This is *unfinished work*, so use with care.
+
+If you find it lacking or badly coded, please feel free to fork and improve. I'll be very happy :)
+
+<hr>
+
+
+== TODO's
+
+
+* Make caching an option of the normal <tt>erb()/haml()/sass()</tt> methods, sort of like this:
+
+ erb(:index, :cache => true/false)
+
+ # alternatively enable caching by setting a global config like this
+ set :cache_enabled_for :all || :only/except => ['/','/contact',...]
+
+
+* Improve the logging output to the standard Sinatra output (if we are having :logging enabled )
+
+* Add fragment caching...
+
+* Enable the options functionality for the <tt>:cache</tt> & <tt>:cache_expire</tt> methods, so that they can take custom extensions and more
+
+
+<hr>
+
+
+== CONFIGURATION
+
+* Example 1: Sinatra 'classic' app.*
+
+ <snip....>
+ require 'sinatra/cache'
+
+ # toggle for the cache functionality.
+ set :cache_enabled, true
+ # sets the default extension for cached files
+ set :cache_page_extension, '.html'
+ # sets the Cache dir to the root of the /public directory.
+ set :cache_output_dir, '' # was :cache_dir
+ ...
+
+*Example 2: Sinatra 'sub-classed' app.*
+
+ <snip....>
+ require 'sinatra/cache'
+
+ class MyApp < Sinatra::Base
+
+ register Sinatra::Cache
+
+ # toggle for the cache functionality.
+ set :cache_enabled, true
+ # sets the default extension for cached files
+ set :cache_page_extension, '.html'
+ # sets the Cache output dir to the root of the /public directory.
+ set :cache_output_dir, '' # was :cache_dir
+
+ <snip....>
+
+
+<hr>
+
+
+== USAGE
+
+
+Basic Page Caching into static HTML files
+
+ get '/contact' do
+ # NB! options is currently not working
+ cache( erb( :contact ), :options => 'should go here' )
+ end
+
+Expiring old pages (ie: after POST or PUT events)
+
+ # not very good example
+ post '/contact' do
+ cache_expire( '/contact', options )
+ end
+
+See the "test":test/ and "test/fixtures":test/fixtures/ directories for more examples.
+
+
+<hr>
+
+
+=== DEFAULT OPTIONS
+
+* <tt>:cache_enabled</tt> => toggle for the cache functionality. Default is: <tt>true</tt>
+* <tt>:cache_page_extension</tt> => sets the default extension for cached files. Default is: <tt>.html</tt>
+* <tt>:cache_output_dir</tt> => 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 currently work with Passenger & mod_rewrite :(
+* <tt>:cache_logging</tt> => toggle for logging the cache calls. Default is: <tt>true</tt>
+* <tt>:cache_logging_level</tt> => sets the level of the cache logger. Default is: <tt>:info</tt>.<br>
+ Options:(unused atm) [:info, :warn, :debug]
+
+
+<hr>
+
+=== Credits
+
+A big *Thank You!* goes to "*rtomayko*":http://github.com/rtomayko/, "*blakemizerany*":http://github.com/blakemizerany/ and others working on the Sinatra framework.
+
+Inspired by code from "Rails":http://rubyonrails.com/ &amp; "Merb":http://merbivore.com/
+and "sinatra-mailer":http://github.com/foca/sinatra-mailer/tree/master
+
+
+
+
+
+
+
+== IMPORTANT POINTS TO CONSIDER
+
+=== The DANGERs of URL Query Params
+
+Let's say you have URL like this:
+
+ /products/?product_id=111
+
+and then inside the that template [ .../views/products.erb ],
+you take the product_id param passed in and defines something.
+
+ <h2>Product ID: <%= params[:product_id] %></h2> # => 111
+
+
+The caching of this URL then happens with the value provided,
+and the cached file [ ../public/cache/products.html ] has that same value inside itself.
+
+Now someone comes along and ....
+
+
+
+
+
+
+
+
+Description goes here.
+
+== 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 kematzy. See LICENSE for details.
View
@@ -1,45 +1,88 @@
+require 'rubygems'
require 'rake'
begin
require 'jeweler'
- Jeweler::Tasks.new do |s|
- s.name = "sinatra-cache"
- s.summary = %Q{Simple Page Caching for Sinatra [www.sinatrarb.com]}
- s.email = "kematzy@gmail.com"
- s.homepage = "http://github.com/kematzy/sinatra-cache"
- s.description = "Simple Page Caching for Sinatra [www.sinatrarb.com]"
- s.authors = ["kematzy"]
+ Jeweler::Tasks.new do |gem|
+ gem.name = "sinatra-cache"
+ gem.summary = %Q{Simple Page Caching for Sinatra [www.sinatrarb.com]}
+ gem.description = %Q{Simple Page Caching for Sinatra [www.sinatrarb.com]}
+ gem.email = "kematzy@gmail.com"
+ gem.homepage = "http://github.com/kematzy/sinatra-cache"
+ gem.authors = ["kematzy"]
+ # gem.add_dependency('dependency', '>=x.x.x')
+ gem.add_development_dependency("rspec")
+ # 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
+
+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/"
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
+
+
+namespace :cache do
+
+ desc "Create the cache directories. path=public/system/cache"
+ task :dirs, [:path] do |t, args|
+ unless args.path
+ msg = %Q[\nERROR:\n\n You must define the :path variable like this:\n]
+ msg << %Q[ rake cache:dirs path=public/system/cache \n\n]
+ puts msg
+ else
+ puts "mkdir -p #{args.path}"
+ # sh "mkdir -p #{args.path}"
+ # sh "mkdir -p #{args.path}/fragments"
+ end
+ end
+
+end #/ namespace cache

0 comments on commit da5f556

Please sign in to comment.