merb 0.5.2 → 0.5.3

data/SVN_REVISION

@@ -1 +1 @@
-1297
+1334

data/app_generators/merb/templates/app/views/exceptions/internal_server_error.html.erb

@@ -131,7 +131,7 @@
 		<div class="header">
 			<h1><%= @exception.name.humanize %> <sup class="error_<%= @exception.class::STATUS %>"><%= @exception.class::STATUS %></sup></h1>
 			<% if show_details = ::Merb::Config[:exception_details] -%>
-				<h2><%= ERB::Util.html_escape @exception.message %></h2>
+				<h2><%== @exception.message %></h2>
 			<% else -%>
 				<h2>Sorry about that...</h2>
 			<% end -%>

data/app_generators/merb/templates/script/destroy

@@ -1,6 +1,7 @@
 #!/usr/bin/env ruby
 APP_ROOT = File.join(File.dirname(__FILE__), '..')
 
+# required to overcome a callback in rspec
 def at_exit
 end
 

data/app_generators/merb/templates/script/generate

@@ -1,6 +1,10 @@
 #!/usr/bin/env ruby
 APP_ROOT = File.join(File.dirname(__FILE__), '..')
 
+# required to overcome a callback in rspec
+def at_exit
+end
+
 begin
   require 'rubigen'
 rescue LoadError

data/lib/merb.rb

@@ -45,6 +45,7 @@ module Merb
   autoload :Controller,             'merb/controller'
   autoload :ControllerExceptions,   'merb/exceptions'
   autoload :ControllerMixin,        'merb/mixins/controller'
+  autoload :Cookies,                'merb/cookies'
   autoload :Dispatcher,             'merb/dispatcher'
   autoload :DrbServiceProvider,     'drb_server'
   autoload :ErubisCaptureMixin,     'merb/mixins/erubis_capture'

data/lib/merb/abstract_controller.rb

@@ -58,20 +58,27 @@ module Merb
     end
     
     
-    # Adds a path to the template path cache.  This is requried for 
+    # Adds the a template path to the template path cache. This is required for
     # any view templates or layouts to be found during renering.
     #
-    # Example
-    # 
-    # Merb::AbstractController.add_path_to_template_cache('/full/path/to/template.html.erb')
-    def self.add_path_to_template_cache(template)
-      arry = template.split("/").last.split(".")
-      return false if template == "" || arry.size != 3
-      key = template.split(".")[0..-2].join(".")
-      self._template_path_cache[key] = template
+    # ==== Parameters
+    # template_path<String>:: Full path to the template file.
+    #
+    # ==== Returns
+    # Boolean:: true unless the template path is less than three levels deep.
+    #
+    # ==== Examples
+    #   Merb::AbstractController.add_path_to_template_cache('/full/path/to/template.html.erb')
+    #
+    def self.add_path_to_template_cache(template_path)
+      arry = template_path.split("/").last.split(".")
+      return false if template_path == "" || arry.size != 3
+      key = template_path.split(".")[0..-2].join(".")
+      self._template_path_cache[key] = template_path
     end
     
     # Resets the template_path_cache to an empty hash
+    #
     def self.reset_template_path_cache!
       self._template_path_cache = {}
     end
@@ -88,7 +95,14 @@ module Merb
       send(action, *args)
     end
     
-    # calls a filter chain according to rules.
+    # Calls a filter chain according to rules.
+    #
+    # ==== Parameters
+    # filter_set<Array>:: Array of filter-rule pairs as two piece arrays.
+    #
+    # ==== Returns
+    # Symbol:: :filter_chain_completed to signify execution is completed.
+    #
     def call_filters(filter_set)
       (filter_set || []).each do |(filter, rule)|
         ok = false
@@ -115,45 +129,38 @@ module Merb
       return :filter_chain_completed
     end 
     
-    # +finalize_session+ is called at the end of a request to finalize/store any data placed in the session.
-    # Mixins/Classes wishing to define a new session store must implement this method.
-    # See merb/lib/sessions/* for examples of built in session stores.
-    
+    # +finalize_session+ is called at the end of a request to finalize/store
+    # any data placed in the session. Mixins/Classes wishing to define a new
+    # session store must implement this method. See merb/lib/sessions/*
+    # for examples of built in session stores.
     def finalize_session #:nodoc:
       # noop
     end  
 
-    # +setup_session+ is called at the beginning of a request to load the current session data.
-    # Mixins/Classes wishing to define a new session store must implement this method.
-    # See merb/lib/sessions/* for examples of built in session stores.
-    
+    # +setup_session+ is called at the beginning of a request to load the
+    # current session data. Mixins/Classes wishing to define a new session
+    # store must implement this method. See merb/lib/sessions/* for examples
+    # of built in session stores.
     def setup_session #:nodoc:
       # noop
     end
     
-    # override this method on your controller classes to specialize
+    # Override this method on your controller classes to specialize
     # the output when the filter chain is halted.
+    #
+    # ==== Returns
+    # String:: A message explaining what happened.
+    #
     def filters_halted
       "<html><body><h1>Filter Chain Halted!</h1></body></html>"  
     end
     
     
-    # #before is a class method that allows you to specify before filters in
-    # your controllers. Filters can either be a symbol or string that
-    # corresponds to a method name to call, or a proc object. if it is a method
-    # name that method will be called and if it is a proc it will be called
+    # Specify before filters in your controllers. If a method name is given
+    # that method will be called and if a proc is given it will be called
     # with an argument of self where self is the current controller object.
     # When you use a proc as a filter it needs to take one parameter.
     # 
-    # examples:
-    #   before :some_filter
-    #   before :authenticate, :exclude => [:login, :signup]
-    #   before Proc.new {|c| c.some_method }, :only => :foo
-    #
-    # You can use either :only => :actionname or :exclude => [:this, :that]
-    # but not both at once. :only will only run before the listed actions
-    # and :exclude will run for every action that is not listed.
-    #
     # Merb's before filter chain is very flexible. To halt the filter chain you
     # use throw :halt. If throw is called with only one argument of :halt the
     # return of the method filters_halted will be what is rendered to the view.
@@ -183,40 +190,86 @@ module Merb
     #
     #     throw :halt, Proc.new {|c| c.access_denied }
     #     throw :halt, Proc.new {|c| Tidy.new(c.index) }
-    # 
+    #
+    # ==== Parameters
+    # filter<Symbol, String, Proc>:: The filter to be added.
+    # opts<Hash>::
+    #   The options for the filter to be added (see below). Defaults to an
+    #   empty Hash.
+    #
+    # ==== Options (opts)
+    # :only<Array, Symbol>:: The actions that the filter should be applied to.
+    # :exclude<Array, Symbol>:: The actions that should ignore this filter.
+    #
+    # Note: :only and :exluce cannot be used simultaneously.
+    #
+    # ==== Examples
+    #   before :some_filter
+    #   before :authenticate, :exclude => [:login, :signup]
+    #   before Proc.new {|c| c.some_method }, :only => :foo
+    #
     def self.before(filter, opts={})
       add_filter((self.before_filters ||= []), filter, opts)
     end
     
-    # #after is a class method that allows you to specify after filters in your
-    # controllers. Filters can either be a symbol or string that corresponds to
-    # a method name or a proc object. If it is a method name that method will
-    # be called and if it is a proc it will be called with an argument of self.
-    # When you use a proc as a filter it needs to take one parameter. You can
-    # gain access to the response body like so: after Proc.new {|c|
-    # Tidy.new(c.body) }, :only => :index
-    
+    # Specify after filters in your controllers. If a method name is given
+    # that method will be called and if a proc is given it will be called
+    # with an argument of self where self is the current controller object.
+    # When you use a proc as a filter it needs to take one parameter.
+    #
+    # ==== Parameters
+    # filter<Symbol, String, Proc>:: The filter to be added.
+    # opts<Hash>::
+    #   The options for the filter to be added (see below). Defaults to an
+    #   empty Hash.
+    #
+    # ==== Options (opts)
+    # :only<Array, Symbol>:: The actions that the filter should be applied to.
+    # :exclude<Array, Symbol>:: The actions that should ignore this filter.
+    #
+    # Note: :only and :exluce cannot be used simultaneously.
+    #
+    # ==== Examples
+    #   after :some_filter
+    #   after :tidy, :exclude => [:stats]
+    #   before Proc.new {|c| c.some_method }, :only => :foo
+    #
     def self.after(filter, opts={})
       add_filter((self.after_filters ||= []), filter, opts)
     end
     
-    # Call #skip_before to remove an already declared (before) filter from your controller.
-    # 
-    # Example:
+    # Remove an already declared before filter from your controller.
+    #
+    # ==== Parameters
+    # filter<String, Symbol>:: The filter to be removed.
+    #
+    # ==== Examples
     #   class Application < Merb::Controller
     #     before :require_login
     #   end
     #
-    #   class Login < Merb::Controller
-    #     skip_before :require_login  # Users shouldn't have to be logged in to log in
+    #   class Login < Application
+    #     skip_before :require_login  # Login should be accessible by everyone
     #   end
-    
+    #
     def self.skip_before(filter)
       skip_filter((self.before_filters || []), filter)
     end
     
-    # Exactly like #skip_before, but for after filters
-    
+    # Remove an already declared after filter from your controller.
+    #
+    # ==== Parameters
+    # filter<String, Symbol>:: The filter to be removed.
+    #
+    # ==== Examples
+    #   class Application < Merb::Controller
+    #     after :log_activitiy
+    #   end
+    #
+    #   class Stats < Application
+    #     skip_after :log_activitiy
+    #   end
+    #
     def self.skip_after(filter)
       skip_filter((self.after_filters || []), filter)
     end
@@ -225,17 +278,51 @@ module Merb
       Hash.new{ |hash, key| hash[key] = "" }
     end
     
-    # Set here to respond when rendering to cover the provides syntax of setting the content_type
+    # Set here to respond when rendering to cover the provides syntax of
+    # setting the content_type
+    # 
+    # ==== Returns
+    # Boolean:: True if the content type was set.
+    #
     def content_type_set?
       false
     end
 
+    # Returns the content type.
+    #
+    # ==== Returns
+    # Symbol:: The content type.
+    #
     def content_type
       params[:format] || :html
     end
-    
+
   private
 
+    # Adds a filter to a list of filters.
+    #
+    # ==== Parameters
+    # filters<Array>::
+    #   The array of filters to which the filter should be added.
+    # filter<Symbol, String, Proc>:: The filter to be added.
+    # opts<Hash>::
+    #   The options for the filter to be added (see below). Defaults to an
+    #   empty Hash.
+    #
+    # ==== Options (opts)
+    # :only<Array, Symbol>:: The actions that the filter should be applied to.
+    # :exclude<Array, Symbol>:: The actions that should ignore this filter.
+    #
+    # ==== Raises
+    # ArgumentError::
+    #   The options include both the :only and the :exclude key or the filter
+    #   is not a Symbol, String or Proc.
+    #
+    # ==== Examples
+    #   add_filter([ :log_activity ], :login_required)
+    #
+    #   add_filter([ :log_activity ], :login_required, { :exclude => :login })
+    #
     def self.add_filter(filters, filter, opts={})
       raise(ArgumentError,
         "You can specify either :only or :exclude but 
@@ -257,7 +344,20 @@ module Merb
         )        
       end
     end
-    
+
+    # Removes a filter from a list of filters.
+    #
+    # ==== Parameters
+    # filters<Array>::
+    #   The array of filters from which the filter should be removed.
+    # filter<Symbol, String>:: The filter to be removed.
+    #
+    # ==== Raises
+    # ArgumentError:: The filter argument is not a String or a Symbol.
+    #
+    # ==== Examples
+    #   skip_filter([ :login_required, :log_activity ], :login_required)
+    #
     def self.skip_filter(filters, filter)
       raise(ArgumentError, 
         'You can only skip filters that have a String or Symbol name.'
@@ -267,10 +367,23 @@ module Merb
       ) unless filters.reject! {|f| f.first.to_s[filter.to_s] }
     end
 
-    # Ensures that the passed in hash values are always arrays.
+    # Changes filter options hash values for the only and exclude keys to
+    # arrays, if they are not arrays already.
+    #
+    # ==== Parameters
+    # opts<Hash>:: The filter options hash. Will default to an empty Hash.
+    #
+    # ==== Options (opts)
+    # :only<Array, Symbol>:: The actions that the filter should be applied to.
+    # :exclude<Array, Symbol>:: The actions that should ignore this filter.
+    #
+    # ==== Returns
+    # Hash:: The original options with the only and exclude values as arrays.
+    #
+    # ==== Examples
+    #   shuffle_filters!(:only => :new)
+    #   # => { :only => [:new] }
     #
-    #   shuffle_filters!(:only => :new) #=> {:only => [:new]}   
-
     def self.shuffle_filters!(opts={})
       if opts[:only] && opts[:only].is_a?(Symbol)
         opts[:only] = [opts[:only]]

data/lib/merb/assets.rb

@@ -1,10 +1,15 @@
 module Merb
   module Assets
     
-    # Returns true if assets should be bundled (e.g., production mode or
-    # :bundle_assets is explicitly enabled), false if not.
+    # Check whether the assets should be bundled.
+    #
+    # ==== Returns
+    # Boolean::
+    #   True if the assets should be bundled (e.g., production mode or
+    #   :bundle_assets is explicitly enabled).
+    #
     def self.bundle?
-      (Merb::Config[:environment] == :production) ||
+      (Merb::Config[:environment].to_s == 'production') ||
       (!!Merb::Config[:bundle_assets])
     end
     
@@ -20,8 +25,24 @@ module Merb
       # true, returns the path relative to the Merb.root, not the public
       # directory. Uses the path_prefix, if any is configured.
       # 
-      #   asset_path(:javascript, :dingo)       #=> "/javascripts/dingo.js"
-      #   asset_path(:javascript, :dingo, true) #=> "public/javascripts/dingo.js"
+      # ==== Parameters
+      # asset_type<Symbol>:: Type of the asset (e.g. :javascript).
+      # filename<~to_s>:: The path to the file.
+      #
+      # local_path<Boolean>::
+      #   If true, the returned path will be relative to the Merb.root,
+      #   otherwise it will be the public URI path. Defaults to false.
+      #
+      # ==== Returns
+      # String:: The path to the asset.
+      #
+      # ==== Examples
+      #   asset_path(:javascript, :dingo)
+      #   # => "/javascripts/dingo.js"
+      #
+      #   asset_path(:javascript, :dingo, true)
+      #   # => "public/javascripts/dingo.js"
+      #
       def asset_path(asset_type, filename, local_path = false)
         filename = filename.to_s
         if filename !~ /#{'\\' + ASSET_FILE_EXTENSIONS[asset_type]}\Z/
@@ -40,24 +61,36 @@ module Merb
     class AbstractAssetBundler
       class << self
         
-        # Add a post-bundle callback, for example to run a Javascript or CSS
-        # compressor on the bundled file:
-        # 
-        #   Merb::Assets::JavascriptAssetBundler.add_callback do |filename|
-        #     `yuicompressor #{filename}`
-        #   end
+        # Add a post-bundle callback.
+        #
+        # ==== Examples
+        #   add_callback { |filename| `yuicompressor #{filename}` }
+        #
         def add_callback(&block)
           callbacks << block
         end
         alias_method :after_bundling, :add_callback
         
-        # An array of any existing callbacks.
+        # Retrieve existing callbacks.
+        #
+        # ==== Returns
+        # Array:: An array of existing callbacks.
+        #
         def callbacks
           @callbacks ||= []
           return @callbacks
         end
         
-        # The type of asset for which the bundler is responsible.
+        # The type of asset for which the bundler is responsible. Override
+        # this method in your bundler code.
+        #
+        # ==== Raises
+        # NotImplementedError::
+        #   If this method has not been implemented by the bundler.
+        #
+        # ==== Returns
+        # Symbol:: The type of the asset
+        #
         def asset_type
           raise NotImplementedError, "should return a symbol for the first argument to be passed to asset_path"
         end
@@ -73,8 +106,11 @@ module Merb
         @files = files.map { |f| asset_path(self.class.asset_type, f, true) }
       end
       
-      # Creates the new bundled file, executes all the callbacks, and returns
-      # the name of the bundled file.
+      # Creates the new bundled file, executing all the callbacks.
+      #
+      # ==== Returns
+      # Symbol:: Name of the bundle.
+      #
       def bundle!
         # TODO: Move this file check out into an in-memory cache. Also, push it out to the helper level so we don't have to create the helper object.
         unless File.exist?(@bundle_filename)
@@ -88,7 +124,12 @@ module Merb
       
       include Merb::Assets::AssetHelpers # for asset_path
       
-      # Bundle all the filenames in +files+ into +filename+.
+      # Bundle all the files into one.
+      #
+      # ==== Parameters
+      # filename<String>:: Name of the bundle file.
+      # files<Array>:: An array of filenames to be bundled.
+      #
       def bundle_files(filename, *files)
         File.open(filename, "w") do |f|
           files.each { |file| f.puts(File.read(file)) }