Padrino Cache Doc [Thanks to Onethirtyfive]

CHANGES.rdoc

@@ -8,6 +8,8 @@
 * Allow grouped options in a select_tag [Thanks activestylus]
 * Use MongoMapper official gem
 * Fixes ERBHandler type detection
+* Routes with globs does not work if something is after the glob i.e. get :show, :map => '/pictures/*path.html'
+* Padrino Cache Doc [Thanks to Onethirtyfive]
 
 == 0.9.23
 

Gemfile

@@ -21,7 +21,7 @@ group :development do
   gem "mocha", ">= 0.9.8"
   gem "rack-test", ">= 0.5.0"
   gem "fakeweb",  ">=1.2.8"
-  gem "webrat", ">= 0.5.1"
+  gem "webrat", "= 0.5.1"
   gem "haml", ">= 2.2.22"
   gem "phocus"
   gem "shoulda", ">= 2.10.3"
@@ -45,4 +45,4 @@ gem "padrino-cache",   :path => "/#{base_path}/padrino-cache"
 gem "padrino-core",    :path => "/#{base_path}/padrino-core"
 gem "padrino-gen",     :path => "/#{base_path}/padrino-gen"
 gem "padrino-helpers", :path => "/#{base_path}/padrino-helpers"
-gem "padrino-mailer",  :path => "/#{base_path}/padrino-mailer"
+gem "padrino-mailer",  :path => "/#{base_path}/padrino-mailer"

Rakefile

@@ -119,7 +119,7 @@ desc "Generate documentation for the Padrino framework"
 Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'doc'
   rdoc.options << '--fmt' << 'shtml' # explictly set shtml generator
-  rdoc.title    = "Padrino Framework Documentation"
+  rdoc.title    = "Padrino Framework Documentation - v. #{Padrino.version}"
   rdoc.main = 'padrino-core/README.rdoc'
   rdoc.rdoc_files.include('padrino-core/lib/{*.rb,padrino-core}/*.rb')
   rdoc.rdoc_files.include('padrino-core/lib/padrino-core/application/**/*.rb')
@@ -134,9 +134,11 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('padrino-helpers/README.rdoc')
   rdoc.rdoc_files.include('padrino-mailer/lib/**/*.rb')
   rdoc.rdoc_files.include('padrino-mailer/README.rdoc')
+  rdoc.rdoc_files.include('padrino-cache/lib/**/*.rb')
+  rdoc.rdoc_files.include('padrino-cache/README.rdoc')
 end
 
-desc "Publish doc on padrino.github.com"
+desc "Publish doc on padrinorb.com/api"
 task :pdoc => :rdoc do
   puts "Publishing doc on padrinorb.com ..."
   Rake::SshDirPublisher.new("[email protected]", "/mnt/www/apps/padrino/public/api", "doc").upload

padrino-cache/lib/padrino-cache.rb

@@ -4,19 +4,25 @@
 FileSet.glob_require('padrino-cache/{helpers}/*.rb', __FILE__)
 
 module Padrino
+  ##
+  # This component enables caching of an application's response contents on
+  # both page- and fragment-levels. Output cached in this manner is
+  # persisted, until it expires or is actively expired, in a configurable store
+  # of your choosing. Several common caching stores are supported out of the box.
+  #
   module Cache
-    ##
-    # Register these helpers:
-    #
-    #   Padrino::Cache::FragmentHelpers
-    #   Padrino::Cache::PageHelpers
-    #
-    # for Padrino::Application
-    #
-
     autoload :Store, 'padrino-cache/store'
 
     class << self
+      ##
+      # Register these helpers:
+      #
+      #   Padrino::Cache::Helpers::CacheStore
+      #   Padrino::Cache::FragmentHelpers
+      #   Padrino::Cache::PageHelpers
+      #
+      # for Padrino::Application
+      #
       def registered(app)
         app.helpers Padrino::Cache::Helpers::CacheStore
         app.helpers Padrino::Cache::Helpers::Fragment
@@ -26,9 +32,9 @@ def registered(app)
       end
       alias :included :registered
 
-      def padrino_route_added(route, verb, path, args, options, block)
+      def padrino_route_added(route, verb, path, args, options, block) #:nodoc
         Padrino::Cache::Helpers::Page.padrino_route_added(route, verb, path, args, options, block)
       end
     end
-  end # Helpers
+  end # Cache
 end # Padrino

padrino-cache/lib/padrino-cache/helpers/cache_store.rb

@@ -1,7 +1,7 @@
 module Padrino
   module Cache
     module Helpers
-      module CacheStore
+      module CacheStore #:nodoc:
         def expire(*key)
           if key.size == 1 and key.first.is_a?(String)
             self.class.cache_store.delete(key)

padrino-cache/lib/padrino-cache/helpers/fragment.rb

@@ -1,9 +1,46 @@
 module Padrino
   module Cache
     module Helpers
+      ##
+      # Whereas page-level caching, described in the first section of this document, works by
+      # grabbing the entire output of a route, fragment caching gives the developer fine-grained
+      # control of what gets cached. This type of caching occurs at whatever level you choose.
+      #
+      # Possible uses for fragment caching might include:
+      #
+      # * a 'feed' of some items on a page
+      # * output fetched (by proxy) from an API on a third-party site
+      # * parts of your page which are largely static/do not need re-rendering every request
+      # * any output which is expensive to render
+      #
       module Fragment
         include Padrino::Helpers::OutputHelpers
 
+        ##
+        # This helper is used anywhere in your application you would like to associate a fragment
+        # to be cached. It can be used in within a route:
+        #
+        # ==== Examples
+        #   # Caching a fragment
+        #   class MyTweets < Padrino::Application
+        #     register Padrino::Cache  # includes helpers
+        #     enable :caching          # turns on caching mechanism
+        #
+        #     controller '/tweets' do
+        #       get :feed, :map => '/:username' do
+        #         username = params[:username]
+        #
+        #         @feed = cache( "feed_for_#{username}", :expires_in => 3 ) do
+        #           @tweets = Tweet.all( :username => username )
+        #           render 'partials/feedcontent'
+        #         end
+        #
+        #         # Below outputs @feed somewhere in its markup
+        #         render 'feeds/show'
+        #       end
+        #     end
+        #   end
+        #
         def cache(key, opts = nil, &block)
           if self.class.caching?
             if value = self.class.cache_store.get(key.to_s)
@@ -18,4 +55,4 @@ def cache(key, opts = nil, &block)
       end # Fragment
     end # Helpers
   end # Cache
-end # Padrino
+end # Padrino

padrino-cache/lib/padrino-cache/helpers/page.rb

@@ -1,12 +1,46 @@
 module Padrino
   module Cache
     module Helpers
+      ##
+      # Page caching is very easy to integrate into your application. To turn it on, simply provide the
+      # <tt>:cache => true</tt> option on either a controller or one of its routes.
+      # By default, cached content is persisted with a "file store"--that is, in a
+      # subdirectory of your application root.
+      #
+      # ==== Examples
+      #   # Setting content expiry time
+      #   class CachedApp < Padrino::Application
+      #     register Padrino::Cache  # includes helpers
+      #     enable :caching          # turns on caching mechanism
+      #
+      #     controller '/blog', :cache => true do
+      #       expires_in 15
+      #
+      #       get '/entries' do
+      #         'just broke up eating twinkies lol'
+      #       end
+      #     end
+      #   end
+      #
+      # Note that the "latest" method call to <tt>expires_in</tt> determines its value: if
+      # called within a route, as opposed to a controller definition, the route's
+      # value will be assumed.
+      #
       module Page
+        ##
+        # This helper is used within a controller or route to indicate how often content
+        # should persist in the cache.
+        #
+        # After <tt>seconds</tt> seconds have passed, content previously cached will
+        # be discarded and re-rendered. Code associated with that route will <em>not</em>
+        # be executed; rather, its previous output will be sent to the client with a
+        # 200 OK status code.
+        #
         def expires_in(time)
           @_last_expires_in = time
         end
 
-        def self.padrino_route_added(route, verb, path, args, options, block)
+        def self.padrino_route_added(route, verb, path, args, options, block) #:nodoc:
           if route.cache and %w(GET HEAD).include?(verb)
             route.add_before_filter(Proc.new {
               if self.class.caching?

padrino-cache/lib/padrino-cache/store.rb

@@ -9,4 +9,4 @@ module Store
       autoload :Redis,    'padrino-cache/store/redis'
     end # Store
   end # Cache
-end # Padrino
+end # Padrino

padrino-cache/lib/padrino-cache/store/file.rb

@@ -1,9 +1,15 @@
 module Padrino
   module Cache
     module Store
+      ##
+      # File based Cache Store
+      #
       class File
+        ##
         # Initialize File store with File root
-        # Padrino::Cache::Store::File.new "path/to"
+        #
+        # ==== Examples
+        #   Padrino::Cache::Store::File.new "path/to"
         #
         def initialize(root)
           @root = root
@@ -47,18 +53,18 @@ def flush
         end
 
         private
-        def path_for_key(key)
-          ::File.join(@root, Rack::Utils.escape(key.to_s))
-        end
+          def path_for_key(key)
+            ::File.join(@root, Rack::Utils.escape(key.to_s))
+          end
 
-        def init
-          unless @init
-            FileUtils.rm_rf(@root)
-            FileUtils.mkdir_p(@root)
-            @init = true
+          def init
+            unless @init
+              FileUtils.rm_rf(@root)
+              FileUtils.mkdir_p(@root)
+              @init = true
+            end
           end
-        end
       end # File
     end # Store
   end # Cache
-end # Padrino
+end # Padrino

padrino-cache/lib/padrino-cache/store/memcache.rb

@@ -1,9 +1,16 @@
 module Padrino
   module Cache
     module Store
+      ##
+      # Memcache Cache Store
+      #
       class Memcache
+        ##
         # Initialize Memcache store with client connection.
-        # Padrino::Cache::Store::Memcache.new ::Memcached.new('127.0.0.1:11211')
+        #
+        # ==== Examples
+        #   Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211'))
+        #   Padrino::Cache::Store::Memcache.new(::Memcached.new('127.0.0.1:11211', :exception_retry_limit => 1))
         #
         def initialize(client)
           @backend = client
@@ -37,4 +44,4 @@ def flush
       end # Memcached
     end # Store
   end # Cache
-end # Padrino
+end # Padrino

padrino-cache/lib/padrino-cache/store/memory.rb

@@ -1,9 +1,15 @@
 module Padrino
   module Cache
     module Store
+      ##
+      # Memory Cache Store
+      #
       class Memory
+        ##
         # Initialize Memory Store with memory size
-        # Padrino::Cache::Store::Memory.new 10000
+        #
+        # ==== Examples
+        #   Padrino::Cache::Store::Memory.new(10000)
         #
         def initialize(size = 5000)
           @size, @entries, @index = size, [], {}
@@ -50,4 +56,4 @@ def flush
       end # Memory
     end # Store
   end # Cache
-end # Padrino
+end # Padrino

padrino-cache/lib/padrino-cache/store/redis.rb

@@ -1,9 +1,15 @@
 module Padrino
   module Cache
     module Store
+      ##
+      # Redis Cache Store
+      #
       class Redis
+        ##
         # Initialize Redis store with client connection.
-        # Padrino::Cache::Store::Redis.new ::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0)
+        #
+        # ==== Examples
+        #   Padrino::Cache::Store::Redis.new ::Redis.new(:host => '127.0.0.1', :port => 6379, :db => 0)
         #
         def initialize(client)
           @backend = client
@@ -32,4 +38,4 @@ def flush
       end # Redis
     end # Store
   end # Cache
-end # Padrino
+end # Padrino

padrino-cache/test/test_stores.rb

@@ -116,4 +116,4 @@ def teardown
     assert_equal nil, @cache.get('0')
     assert_equal '1', @cache.get('1')
   end
-end
+end