merb-core 0.9.8 → 0.9.9

data/lib/merb-core/controller/mime.rb

@@ -1,12 +1,32 @@
 module Merb
   class << self
 
+    
+    # Returns a hash of the available mime types. 
+    #
     # ==== Returns
-    # Hash:: The available mime types.
+    # Hash{Symbol => Hash{Symbol => Object}}:: The available mime types.
+    #
+    # ==== Notes
+    # Each entry corresponds to a call to add_mime_type, having the mime type key (:html, :xml, :json, etc.)
+    # as the key and a hash containing the following entries:
+    #   :accepts           # the mime types that will be recognized by this entry
+    #   :transform_method  # the method called on an object to convert it to content of this type (such as to_json)
+    #   :content_type      # the value set to the "Content-Type" HTTP header when this mime is sent in a response
+    #   :response_headers  # sent in a response using this content type
+    #   :default_quality   # the scale factor used in describing content type preference
+    #   :response_block    # the block to be called with the controller when a request responds to this mime type
+    #
+    # @api public
     def available_mime_types
       ResponderMixin::TYPES
     end
 
+    # ==== Returns
+    # Hash{String => Symbol}:: 
+    #   A hash mapping Content-Type values to the mime type key of the appropriate entry in #available_mime_types
+    #
+    # @api public
     def available_accepts
       ResponderMixin::MIMES
     end
@@ -42,6 +62,11 @@ module Merb
     #   correctly appended to the mimetype itself.
     # &block:: a block which recieves the current controller when the format
     #   is set (in the controller's #content_type method)
+    #
+    # ==== Returns
+    # nil
+    #
+    # @api public
     def add_mime_type(key, transform_method, mimes, new_response_headers = {}, default_quality = 1, &block) 
       enforce!(key => Symbol, mimes => Array)
       
@@ -69,6 +94,8 @@ module Merb
           render thing, opts
         end
       EOS
+      
+      nil
     end
 
     # Removes a MIME-type from the mime-type list.
@@ -76,8 +103,14 @@ module Merb
     # ==== Parameters
     # key<Symbol>:: The key that represents the mime-type to remove.
     #
+    # ==== Returns
+    # (Boolean, Hash{Symbol => Object}):: If it was present, the old specification of the MIME-type. Same structure
+    #   as a value in Merb.available_mime_types. False if the key was not present.
+    #
     # ==== Notes
     # :all is the key for */*; It can't be removed.
+    #
+    # @api public
     def remove_mime_type(key)
       return false if key == :all
       ResponderMixin::TYPES.delete(key)
@@ -91,21 +124,12 @@ module Merb
     #
     # ==== Raises
     # ArgumentError:: The requested mime type is not valid.
+    #
+    # @api private
     def mime_transform_method(key)
       raise ArgumentError, ":#{key} is not a valid MIME-type" unless ResponderMixin::TYPES.key?(key)
       ResponderMixin::TYPES[key][:transform_method]
     end
 
-    # The mime-type for a particular inbound Accepts header.
-    #
-    # ==== Parameters
-    # header<String>:: The name of the header to find the mime-type for.
-    #
-    # ==== Returns
-    # Hash:: The mime type information.
-    def mime_by_request_header(header)
-      available_mime_types.find {|key,info| info[:accepts].include?(header)}.first
-    end
-    
   end
 end

data/lib/merb-core/controller/mixins/authentication.rb

@@ -12,6 +12,9 @@ module Merb::AuthenticationMixin
   # realm<~to_s>:: The realm to authenticate against. Defaults to 'Application'.
   # &authenticator:: A block to check if the authentication is valid.
   #
+  # ==== Returns
+  # Merb::AuthenticationMixin::BasicAuthentication
+  #
   # ==== Examples
   #     class Application < Merb::Controller
   #     
@@ -47,7 +50,7 @@ module Merb::AuthenticationMixin
   #
   # If you need to request basic authentication inside an action you need to use the request! method.
   #
-  # ====Example
+  # ==== Example
   #
   #    class Sessions < Application
   #  
@@ -55,15 +58,24 @@ module Merb::AuthenticationMixin
   #        case content_type
   #        when :html
   #          render
+  #
   #        else
-  #          basic_authentication.request!
+  #         user = basic_authentication.authenticate do |username, password|
+  #           User.authenticate(username, password)
+  #         end
+  #
+  #         if user
+  #           display(user)
+  #         else
+  #           basic_authentication.request
+  #         end
   #        end
   #      end
   # 
   #    end 
   #
-  #---
-  # @public
+  #
+  # @api public
   def basic_authentication(realm = "Application", &authenticator)
     @_basic_authentication ||= BasicAuthentication.new(self, realm, &authenticator)
   end
@@ -72,6 +84,7 @@ module Merb::AuthenticationMixin
     # So we can have access to the status codes
     include Merb::ControllerExceptions
 
+    # @api private
     def initialize(controller, realm = "Application", &authenticator)
       @controller = controller
       @realm = realm
@@ -79,6 +92,15 @@ module Merb::AuthenticationMixin
       authenticate_or_request(&authenticator) if authenticator
     end
 
+    # Determines whether or not the user is authenticated using the criteria
+    # in the provided authenticator block.
+    #
+    # ==== Parameters
+    # &authenticator:: A block that decides whether the provided username and password
+    #   are valid.
+    #
+    # ==== Returns
+    # Object:: False if basic auth is not provided, otherwise the return value of the authenticator block.
     def authenticate(&authenticator)
       if @auth.provided? and @auth.basic?
         authenticator.call(*@auth.credentials)
@@ -87,33 +109,56 @@ module Merb::AuthenticationMixin
       end
     end
 
+    # Request basic authentication and halt the filter chain. This is for use in a before filter.
+    #
+    # ==== Throws
+    # :halt with an "HTTP Basic: Access denied." message with no layout, and sets the status to Unauthorized.
+    #
+    # @api public
     def request
       request!
       throw :halt, @controller.render("HTTP Basic: Access denied.\n", :status => Unauthorized.status, :layout => false)
     end
     
-    # This is a special case for use outside a before filter.  Use this if you need to 
-    # request basic authenticaiton as part of an action
+    # Sets headers to request basic auth.
+    #
+    # ==== Returns
+    # String:: Returns the empty string to provide a response body.
+    #
+    # @api public
     def request!
       @controller.status = Unauthorized.status
       @controller.headers['WWW-Authenticate'] = 'Basic realm="%s"' % @realm
+      ""
     end
     
-    # Checks to see if there has been any basic authentication credentials provided
+    # ==== Returns
+    # Boolean:: Whether there has been any basic authentication credentials provided
+    #
+    # @api public
     def provided?
       @auth.provided?
     end
     
+    # ==== Returns
+    # String:: The username provided in the request.
+    #
+    # @api public
     def username
       provided? ? @auth.credentials.first : nil
     end
     
+    # ==== Returns
+    # String:: The password provided in the request.
+    #
+    # @api public
     def password
       provided? ? @auth.credentials.last : nil
     end
     
     protected
     
+    # @api private
     def authenticate_or_request(&authenticator)
       authenticate(&authenticator) || request
     end

data/lib/merb-core/controller/mixins/conditional_get.rb

@@ -29,6 +29,8 @@ module Merb::ConditionalGetMixin
   # tag<~to_s>::
   #   value of ETag header enclosed in double quotes
   #   as required by the RFC
+  #
+  # @api public
   def etag=(tag)
     headers[Merb::Const::ETAG] = %("#{tag}")
   end
@@ -36,6 +38,8 @@ module Merb::ConditionalGetMixin
   # ==== Returns
   # <String>::
   #   Value of ETag response header or nil if it's not set.
+  #
+  # @api public
   def etag
     headers[Merb::Const::ETAG]
   end
@@ -44,6 +48,8 @@ module Merb::ConditionalGetMixin
   # <Boolean>::
   # true if ETag response header equals If-None-Match request header,
   # false otherwise
+  #
+  # @api public
   def etag_matches?(tag = self.etag)
     tag == self.request.if_none_match
   end
@@ -54,6 +60,8 @@ module Merb::ConditionalGetMixin
   # tag<Time>::
   # resource modification timestamp converted into format
   # required by the RFC
+  #
+  # @api public
   def last_modified=(time)
     headers[Merb::Const::LAST_MODIFIED] = time.httpdate
   end
@@ -61,6 +69,8 @@ module Merb::ConditionalGetMixin
   # ==== Returns
   # <String>::
   #   Value of Last-Modified response header or nil if it's not set.
+  #
+  # @api public
   def last_modified
     Time.rfc2822(headers[Merb::Const::LAST_MODIFIED])
   end
@@ -69,6 +79,8 @@ module Merb::ConditionalGetMixin
   # <Boolean>::
   # true if Last-Modified response header is < than
   # If-Modified-Since request header value, false otherwise.
+  #
+  # @api public
   def not_modified?(time = self.last_modified)
     request.if_modified_since && time && time <= request.if_modified_since
   end
@@ -77,6 +89,8 @@ module Merb::ConditionalGetMixin
   # <Boolean>::
   # true if either ETag matches or entity is not modified,
   # so request is fresh; false otherwise
+  #
+  # @api public
   def request_fresh?
     etag_matches?(self.etag) || not_modified?(self.last_modified)
   end

data/lib/merb-core/controller/mixins/controller.rb

@@ -4,26 +4,27 @@ module Merb
     
     # Enqueu a block to run in a background thread outside of the request
     # response dispatch
-    #
+    # 
     # ==== Parameters
-    # takes a block to run later
-    #
+    # &blk:: proc to run later
+    # 
     # ==== Example
     # run_later do
     #   SomeBackgroundTask.run
     # end
-    #
+    # 
+    # @api public
     def run_later(&blk)
       Merb::Dispatcher.work_queue << blk
     end
     
     # Renders the block given as a parameter using chunked encoding.
-    #
+    # 
     # ==== Parameters
-    # &blk:: 
+    # &blk::
     #   A block that, when called, will use send_chunks to send chunks of data
     #   down to the server. The chunking will terminate once the block returns.
-    #
+    # 
     # ==== Examples
     #   def stream
     #     prefix = '<p>'
@@ -44,6 +45,8 @@ module Merb
     #       end
     #     end
     #   end
+    # 
+    # @api public
     def render_chunked(&blk)
       must_support_streaming!
       headers['Transfer-Encoding'] = 'chunked'
@@ -55,12 +58,14 @@ module Merb
         response.write("0\r\n\r\n")
       }
     end
-
+    
     # Writes a chunk from +render_chunked+ to the response that is sent back to
     # the client. This should only be called within a +render_chunked+ block.
     #
     # ==== Parameters
     # data<String>:: a chunk of data to return.
+    # 
+    # @api public
     def send_chunk(data)
       only_runs_on_mongrel!
       @response.write('%x' % data.size + "\r\n")
@@ -71,53 +76,59 @@ module Merb
     # &blk::
     #   A proc that should get called outside the mutex, and which will return
     #   the value to render.
-    #
+    # 
     # ==== Returns
     # Proc::
-    #   A block that Mongrel can call later, allowing Merb to release the
+    #   A block that the server can call later, allowing Merb to release the
     #   thread lock and render another request.
+    # 
+    # @api public
     def render_deferred(&blk)
-      Proc.new {|response|
+      Proc.new do |response|
         response.write(blk.call)
-      }
+      end
     end
     
     # Renders the passed in string, then calls the block outside the mutex and
     # after the string has been returned to the client.
-    #
+    # 
     # ==== Parameters
     # str<String>:: A +String+ to return to the client.
     # &blk:: A block that should get called once the string has been returned.
-    #
+    # 
     # ==== Returns
     # Proc::
     #   A block that Mongrel can call after returning the string to the user.
+    # 
+    # @api public
     def render_then_call(str, &blk)
-      Proc.new {|response|
+      Proc.new do |response|
         response.write(str)
-        blk.call        
-      }      
+        blk.call
+      end
     end
-
+    
     # ==== Parameters
     # url<String>::
     #   URL to redirect to. It can be either a relative or fully-qualified URL.
     # opts<Hash>:: An options hash (see below)
-    #
+    # 
     # ==== Options (opts)
     # :message<Hash>::
     #   Messages to pass in url query string as value for "_message"
     # :permanent<Boolean>::
     #   When true, return status 301 Moved Permanently
-    #
+    # 
     # ==== Returns
     # String:: Explanation of redirect.
-    #
+    # 
     # ==== Examples
     #   redirect("/posts/34")
     #   redirect("/posts/34", :message => { :notice => 'Post updated successfully!' })
     #   redirect("http://www.merbivore.com/")
     #   redirect("http://www.merbivore.com/", :permanent => true)
+    # 
+    # @api public
     def redirect(url, opts = {})
       default_redirect_options = { :message => nil, :permanent => false }
       opts = default_redirect_options.merge(opts)
@@ -131,17 +142,20 @@ module Merb
       "<html><body>You are being <a href=\"#{url}\">redirected</a>.</body></html>"
     end
     
+    # Retreives the redirect message either locally or from the request.
+    # 
+    # @api public
     def message
       @_message = defined?(@_message) ? @_message : request.message
     end
     
     # Sends a file over HTTP.  When given a path to a file, it will set the
     # right headers so that the static file is served directly.
-    #
+    # 
     # ==== Parameters
     # file<String>:: Path to file to send to the client.
     # opts<Hash>:: Options for sending the file (see below).
-    #
+    # 
     # ==== Options (opts)
     # :disposition<String>::
     #   The disposition of the file send. Defaults to "attachment".
@@ -151,6 +165,8 @@ module Merb
     #
     # ==== Returns
     # IO:: An I/O stream for the file.
+    # 
+    # @api public
     def send_file(file, opts={})
       opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
       disposition = opts[:disposition].dup || 'attachment'
@@ -160,28 +176,30 @@ module Merb
         'Content-Disposition'       => disposition,
         'Content-Transfer-Encoding' => 'binary'
       )
-      Proc.new {|response|
+      Proc.new do |response|
         file = File.open(file, 'rb')
         while chunk = file.read(16384)
           response.write chunk
-        end  
+        end
         file.close
-      }
+      end
     end
     
     # Send binary data over HTTP to the user as a file download. May set content type,
     # apparent file name, and specify whether to show data inline or download as an attachment.
-    #
+    # 
     # ==== Parameters
     # data<String>:: Path to file to send to the client.
     # opts<Hash>:: Options for sending the data (see below).
-    #
+    # 
     # ==== Options (opts)
     # :disposition<String>::
     #   The disposition of the file send. Defaults to "attachment".
     # :filename<String>::
     #   The name to use for the file. Defaults to the filename of file.
     # :type<String>:: The content type.
+    # 
+    # @api public
     def send_data(data, opts={})
       opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
       disposition = opts[:disposition].dup || 'attachment'
@@ -195,13 +213,13 @@ module Merb
     end
     
     # Streams a file over HTTP.
-    #
+    # 
     # ==== Parameters
     # opts<Hash>:: Options for the file streaming (see below).
     # &stream::
     #   A block that, when called, will return an object that responds to
     #   +get_lines+ for streaming.
-    #
+    # 
     # ==== Options
     # :disposition<String>::
     #   The disposition of the file send. Defaults to "attachment".
@@ -216,6 +234,8 @@ module Merb
     #       response.write chunk
     #     end
     #   end
+    # 
+    # @api public
     def stream_file(opts={}, &stream)
       opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
       disposition = opts[:disposition].dup || 'attachment'
@@ -227,32 +247,37 @@ module Merb
         # Rack specification requires header values to respond to :each
         'CONTENT-LENGTH'            => opts[:content_length].to_s
       )
-      Proc.new{|response|
+      Proc.new do |response|
         stream.call(response)
-      }
+      end
     end
-
+    
     # Uses the nginx specific +X-Accel-Redirect+ header to send a file directly
-    # from nginx. For more information, see the nginx wiki:
+    # from nginx.
+    # 
+    # ==== Notes
+    # Unless Content-Disposition is set before calling this method,
+    # it is set to attachment with streamed file name.
+    # 
+    # For more information, see the nginx wiki:
     # http://wiki.codemongers.com/NginxXSendfile
-    #
+    # 
     # and the following sample gist:
     # http://gist.github.com/11225
-    #
+    # 
     # there's also example application up on GitHub:
-    #
+    # 
     # http://github.com/michaelklishin/nginx-x-accel-redirect-example-application/tree/master
-    #
-    # Unless Content-Disposition is set before calling this method,
-    # it is set to attachment with streamed file name.
-    #
+    # 
     # ==== Parameters
     # path<String>:: Path to file to send to the client.
     # content_type<String>:: content type header value. By default is set to empty string to let
     #                        Nginx detect it.
-    #
+    # 
     # ==== Return
-    # One space string.
+    # String:: precisely a single space.
+    # 
+    # @api public
     def nginx_send_file(path, content_type = "")
       # Let Nginx detect content type unless it is explicitly set
       headers['Content-Type']        = content_type
@@ -262,17 +287,17 @@ module Merb
       
       return ' '
     end  
-  
+    
     # Sets a cookie to be included in the response.
-    #
+    # 
     # If you need to set a cookie, then use the +cookies+ hash.
-    #
+    # 
     # ==== Parameters
     # name<~to_s>:: A name for the cookie.
     # value<~to_s>:: A value for the cookie.
     # expires<~gmtime:~strftime, Hash>:: An expiration time for the cookie, or a hash of cookie options.
-    # ---
-    # @public
+    # 
+    # @api public
     def set_cookie(name, value, expires)
       options = expires.is_a?(Hash) ? expires : {:expires => expires}
       cookies.set_cookie(name, value, options)
@@ -280,11 +305,13 @@ module Merb
     
     # Marks a cookie as deleted and gives it an expires stamp in the past. This
     # method is used primarily internally in Merb.
-    #
+    # 
     # Use the +cookies+ hash to manipulate cookies instead.
-    #
+    # 
     # ==== Parameters
     # name<~to_s>:: A name for the cookie to delete.
+    # 
+    # @api public
     def delete_cookie(name)
       set_cookie(name, nil, Merb::Const::COOKIE_EXPIRED_TIME)
     end
@@ -296,6 +323,8 @@ module Merb
     #
     # ==== Returns
     # String:: The escaped object.
+    # 
+    # @api public
     def escape_xml(obj)
       Erubis::XmlHelper.escape_xml(obj.to_s)
     end
@@ -303,14 +332,17 @@ module Merb
     alias escape_html escape_xml
     
     private
-      # Marks an output method that only runs on the mongrel webserver.
-      #
-      # ==== Raises
-      # NotImplemented:: The Rack adapter is not mongrel.
-      def only_runs_on_mongrel!
-        unless Merb::Config[:log_stream] == 'mongrel'
-          raise(Merb::ControllerExceptions::NotImplemented, "Current Rack adapter is not mongrel. cannot support this feature")
-        end
+    
+    # Marks an output method that only runs on the Mongrel webserver.
+    # 
+    # ==== Raises
+    # NotImplemented:: The Rack adapter is not mongrel.
+    # 
+    # @api private
+    def only_runs_on_mongrel!
+      unless Merb::Config[:log_stream] == 'mongrel'
+        raise(Merb::ControllerExceptions::NotImplemented, "Current Rack adapter is not mongrel. cannot support this feature")
       end
+    end
   end
 end