merb-core 0.9.2

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

@@ -0,0 +1,88 @@
+module Merb
+  class << self
+
+    # ==== Returns
+    # Hash:: The available mime types.
+    def available_mime_types
+      ResponderMixin::TYPES
+    end
+
+    # Any specific outgoing headers should be included here.  These are not
+    # the content-type header but anything in addition to it.
+    # +transform_method+ should be set to a symbol of the method used to
+    # transform a resource into this mime type.
+    # For example for the :xml mime type an object might be transformed by
+    # calling :to_xml, or for the :js mime type, :to_json.
+    # If there is no transform method, use nil.
+    #
+    # ==== Autogenerated Methods
+    # Adding a mime-type adds a render_type method that sets the content
+    # type and calls render.
+    # 
+    # By default this does: def render_all, def render_yaml, def render_text,
+    # def render_html, def render_xml, def render_js, and def render_yaml
+    #
+    # ==== Parameters
+    # key<Symbol>:: The name of the mime-type. This is used by the provides API
+    # transform_method<~to_s>:: 
+    #   The associated method to call on objects to convert them to the
+    #   appropriate mime-type. For instance, :json would use :to_json as its
+    #   transform_method.
+    # values<Array[String]>::
+    #   A list of possible values sent in the Accept header, such as text/html,
+    #   that should be associated with this content-type.
+    # new_response_headers<Hash>::
+    #   The response headers to set for the the mime type.
+    def add_mime_type(key, transform_method, values, new_response_headers = {}) 
+      enforce!(key => Symbol, values => Array)
+      ResponderMixin::TYPES.update(key => 
+        {:request_headers   => values, 
+         :transform_method  => transform_method,
+         :response_headers  => new_response_headers })
+
+      Merb::RenderMixin.class_eval <<-EOS, __FILE__, __LINE__
+        def render_#{key}(thing = nil, opts = {})
+          self.content_type = :#{key}
+          render thing, opts
+        end
+      EOS
+    end
+
+    # Removes a MIME-type from the mime-type list.
+    #
+    # ==== Parameters
+    # key<Symbol>:: The key that represents the mime-type to remove.
+    #
+    # ==== Note
+    # :all is the key for */*; It can't be removed.
+    def remove_mime_type(key)
+      return false if key == :all
+      ResponderMixin::TYPES.delete(key)
+    end
+
+    # ==== Parameters
+    # key<Symbol>:: The key that represents the mime-type.
+    #
+    # ==== Returns
+    # Symbol:: The transform method for the mime type, e.g. :to_json.
+    #
+    # ==== Raises
+    # ArgumentError:: The requested mime type is not valid.
+    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[request_headers].include?(header)}.first
+    end
+    
+  end
+end

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

@@ -0,0 +1,262 @@
+module Merb
+  # Module that is mixed in to all implemented controllers.
+  module ControllerMixin
+    # Renders the block given as a parameter using chunked encoding.
+    #
+    # ==== Parameters
+    # &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>'
+    #     suffix = "</p>\r\n"
+    #     render_chunked do
+    #       IO.popen("cat /tmp/test.log") do |io|
+    #         done = false
+    #         until done
+    #           sleep 0.3
+    #           line = io.gets.chomp
+    #           
+    #           if line == 'EOF'
+    #             done = true
+    #           else
+    #             send_chunk(prefix + line + suffix)
+    #           end
+    #         end
+    #       end
+    #     end
+    #   end
+    def render_chunked(&blk)
+      must_support_streaming!
+      headers['Transfer-Encoding'] = 'chunked'
+      Proc.new { |response|
+        @response = response
+        response.send_status_no_connection_close('')
+        response.send_header
+        blk.call
+        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.
+    def send_chunk(data)
+      @response.write('%x' % data.size + "\r\n")
+      @response.write(data + "\r\n")
+    end
+    
+    # ==== Parameters
+    # &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
+    #   thread lock and render another request.
+    def render_deferred(&blk)
+      must_support_streaming!
+      Proc.new {|response|
+        result = blk.call
+        response.send_status(result.length)
+        response.send_header
+        response.write(result)
+      }
+    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.
+    def render_then_call(str, &blk)
+      must_support_streaming!
+      Proc.new {|response|
+        response.send_status(str.length)
+        response.send_header
+        response.write(str)
+        blk.call        
+      }      
+    end
+        
+    # ==== Parameters
+    # url<String>::
+    #   URL to redirect to. It can be either a relative or fully-qualified URL.
+    #
+    # ==== Returns
+    # String:: Explanation of redirect.
+    #
+    # ==== Examples
+    #   redirect("/posts/34")
+    #   redirect("http://www.merbivore.com/")
+    def redirect(url)
+      Merb.logger.info("Redirecting to: #{url}")
+      self.status = 302
+      headers['Location'] = url
+      "<html><body>You are being <a href=\"#{url}\">redirected</a>.</body></html>"
+    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".
+    # :filename<String>::
+    #   The name to use for the file. Defaults to the filename of file.
+    # :type<String>:: The content type.
+    #
+    # ==== Returns
+    # IO:: An I/O stream for the file.
+    def send_file(file, opts={})
+      opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
+      disposition = opts[:disposition].dup || 'attachment'
+      disposition << %(; filename="#{opts[:filename] ? opts[:filename] : File.basename(file)}")
+      headers.update(
+        'Content-Type'              => opts[:type].strip,  # fixes a problem with extra '\r' with some browsers
+        'Content-Disposition'       => disposition,
+        'Content-Transfer-Encoding' => 'binary'
+      )
+      File.open(file)
+    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.
+    def send_data(data, opts={})
+      opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
+      disposition = opts[:disposition].dup || 'attachment'
+      disposition << %(; filename="#{opts[:filename]}") if opts[:filename]
+      headers.update(
+        'Content-Type'              => opts[:type].strip,  # fixes a problem with extra '\r' with some browsers
+        'Content-Disposition'       => disposition,
+        'Content-Transfer-Encoding' => 'binary'
+      )
+      data
+    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".
+    # :type<String>:: The content type.
+    # :content_length<Numeric>:: The length of the content to send.
+    # :filename<String>:: The name to use for the streamed file.
+    #
+    # ==== Examples
+    #   stream_file({ :filename => file_name, :type => content_type,
+    #     :content_length => content_length }) do |response|
+    #     AWS::S3::S3Object.stream(user.folder_name + "-" + user_file.unique_id, bucket_name) do |chunk|
+    #       response.write chunk
+    #     end
+    #   end
+    def stream_file(opts={}, &stream)
+      must_support_streaming!
+      opts.update(Merb::Const::DEFAULT_SEND_FILE_OPTIONS.merge(opts))
+      disposition = opts[:disposition].dup || 'attachment'
+      disposition << %(; filename="#{opts[:filename]}")
+      response.headers.update(
+        'Content-Type'              => opts[:type].strip,  # fixes a problem with extra '\r' with some browsers
+        'Content-Disposition'       => disposition,
+        'Content-Transfer-Encoding' => 'binary',
+        'CONTENT-LENGTH'            => opts[:content_length]
+      )
+      response.send_status(opts[:content_length])
+      response.send_header
+      stream
+    end
+
+    # Uses the nginx specific +X-Accel-Redirect+ header to send a file directly
+    # from nginx. For more information, see the nginx wiki:
+    # http://wiki.codemongers.com/NginxXSendfile
+    #
+    # ==== Parameters
+    # file<String>:: Path to file to send to the client.
+    def nginx_send_file(file)
+      headers['X-Accel-Redirect'] = File.expand_path(file)
+      return
+    end  
+  
+    # Sets a cookie to be included in the response. This method is used
+    # primarily internally in Merb.
+    #
+    # 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>:: An expiration time for the cookie.
+    def set_cookie(name, value, expires)
+      (headers['Set-Cookie'] ||=[]) << (Merb::Const::SET_COOKIE % [
+        name.to_s, 
+        ::Merb::Request.escape(value.to_s), 
+        # Cookie expiration time must be GMT. See RFC 2109
+        expires.gmtime.strftime(Merb::Const::COOKIE_EXPIRATION_FORMAT)
+      ])
+    end
+    
+    # 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.
+    def delete_cookie(name)
+      set_cookie(name, nil, Merb::Const::COOKIE_EXPIRED_TIME)
+    end
+    
+    # Escapes the string representation of +obj+ and escapes it for use in XML.
+    #
+    # ==== Parameter
+    # obj<~to_s>:: The object to escape for use in XML.
+    #
+    # ==== Returns
+    # String:: The escaped object.
+    def escape_xml(obj)
+      Erubis::XmlHelper.escape_xml(obj.to_s)
+    end
+    alias h escape_xml
+    alias html_escape escape_xml
+    
+    private
+      # Checks whether streaming is supported by the current Rack adapter.
+      #
+      # ==== Raises
+      # NotImplemented:: The Rack adapter doens't support streaming.
+      def must_support_streaming!
+        raise(NotImplemented, "Current Rack adapter does not support streaming") unless request.env['rack.streaming']
+      end
+  end
+end

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

@@ -0,0 +1,324 @@
+module Merb::RenderMixin
+  # So we can do raise TemplateNotFound
+  include Merb::ControllerExceptions
+  
+  # ==== Parameters
+  # base<Module>:: Module that is including RenderMixin (probably a controller)
+  def self.included(base)
+    base.class_eval do
+      class_inheritable_accessor :_layout, :_cached_templates
+    end
+  end
+  
+  # Render the specified item, with the specified options.
+  #
+  # ==== Parameters
+  # thing<String, Symbol, nil>:: 
+  #   The thing to render. This will default to the current action
+  # opts<Hash>:: An options hash (see below)
+  #
+  # ==== Options (opts)
+  # :format<Symbol>:: A registered mime-type format
+  # :template<String>:: 
+  #   The path to the template relative to the template root
+  # :status<~to_i>:: 
+  #   The status to send to the client. Typically, this would be an integer
+  #   (200), or a Merb status code (Accepted)
+  # :layout<~to_s>::
+  #   A layout to use instead of the default. This should be relative to the
+  #   layout root. By default, the layout will be either the controller_name or
+  #   application. If you want to use an alternative content-type than the one
+  #   that the base template was rendered as, you will need to do :layout =>
+  #   "foo.#{content_type}" (i.e. "foo.json")
+  #
+  # ==== Returns
+  # String:: The rendered template, including layout, if appropriate.
+  #
+  # ==== Raises
+  # TemplateNotFound:: There is no template for the specified location.
+  # 
+  # ==== Alternatives
+  # If you pass a Hash as the first parameter, it will be moved to opts and
+  # "thing" will be the current action
+  #---
+  # @public
+  def render(thing = nil, opts = {})
+    # render :format => :xml means render nil, :format => :xml
+    opts, thing = thing, nil if thing.is_a?(Hash)
+    
+    # If you don't specify a thing to render, assume they want to render the current action
+    thing ||= action_name.to_sym
+
+    # Content negotiation
+    opts[:format] ? (self.content_type = opts[:format]) : content_type 
+    
+    # Handle options (:status)
+    _handle_options!(opts)    
+    
+    # Do we have a template to try to render?
+    if thing.is_a?(Symbol) || opts[:template]
+
+      template_method, template_location = _template_for(thing, content_type, controller_name, opts)
+  
+      # Raise an error if there's no template
+      raise TemplateNotFound, "No template found at #{template_location}.*"  \
+        unless template_method && self.respond_to?(template_method)
+
+      # Call the method in question and throw the content for later consumption by the layout
+      throw_content(:for_layout, self.send(template_method))
+      
+    # Do we have a string to render?
+    elsif thing.is_a?(String)
+      
+      # Throw it for later consumption by the layout
+      throw_content(:for_layout, thing)
+    end
+    
+    # If we find a layout, use it. Otherwise, just render the content thrown for layout.
+    layout = opts[:layout] != false && _get_layout(opts[:layout])
+    layout ? send(layout) : catch_content(:for_layout)
+  end
+    
+  # Renders an object using to registered transform method based on the
+  # negotiated content-type, if a template does not exist. For instance, if the
+  # content-type is :json, Merb will first look for current_action.json.*.
+  # Failing that, it will run object.to_json.
+  #
+  # ==== Parameter
+  # object<Object>:: 
+  #   An object that responds_to? the transform method registered for the
+  #   negotiated mime-type.
+  # thing<String, Symbol>::
+  #   The thing to attempt to render via #render before calling the transform
+  #   method on the object. Defaults to nil.
+  # opts<Hash>:: An options hash that will be passed on to #render
+  # 
+  # ==== Returns
+  # String::
+  #   The rendered template or if no template is found, the transformed object.
+  #
+  # ==== Raises
+  # NotAcceptable::
+  #   If there is no transform method for the specified mime-type or the object
+  #   does not respond to the transform method.
+  # 
+  # ==== Alternatives
+  # A string in the second parameter will be interpreted as a template:
+  #   display @object, "path/to/foo" 
+  #   #=> display @object, nil, :template => "path/to/foo"
+  #
+  # A hash in the second parameters will be interpreted as opts:
+  #   display @object, :layout => "zoo"
+  #   #=> display @object, nil, :layout => "zoo"
+  #
+  # ==== Note
+  # The transformed object will not be used in a layout unless a :layout is
+  # explicitly passed in the opts.
+  def display(object, thing = nil, opts = {})
+    # display @object, "path/to/foo" means display @object, nil, :template => "path/to/foo"
+    # display @object, :template => "path/to/foo" means display @object, nil, :template => "path/to/foo"
+    opts[:template], thing = thing, nil if thing.is_a?(String) || thing.is_a?(Hash)
+    
+    # Try to render without the object
+    render(thing || action_name.to_sym, opts)
+  
+  # If the render fails (i.e. a template was not found)
+  rescue TemplateNotFound
+    
+    # Figure out what to transform and raise NotAcceptable unless there's a transform method assigned
+    transform = Merb.mime_transform_method(content_type)
+    raise NotAcceptable unless transform && object.respond_to?(transform)
+    
+    # Throw the transformed object for later consumption by the layout
+    throw_content(:for_layout, object.send(transform))
+  
+    # Only use a layout if one was specified
+    if opts[:layout]
+      # Look for the layout under the default layout directly. If it's not found, reraise
+      # the TemplateNotFound error
+      template = _template_location(opts[:layout], layout.index(".") ? content_type : nil, "layout")      
+      layout = _template_for(_template_root / template) ||
+        (raise TemplateNotFound, "No layout found at #{_template_root / template}.*")      
+              
+      # If the layout was found, call it
+      send(layout)
+    
+    # Otherwise, just render the transformed object
+    else
+      catch_content(:for_layout)
+    end
+  end
+
+  # Render a partial template.
+  #
+  # ==== Parameters
+  # template<~to_s>::
+  #   The path to the template, relative to the current controller or the 
+  #   template root. If the template contains a "/", Merb will search for it
+  #   relative to the template root; otherwise, Merb will search for it
+  #   relative to the current controller.
+  # opts<Hash>:: A hash of options (see below)
+  #
+  # ==== Options (opts)
+  # :with<Object, Array>::
+  #   An object or an array of objects that will be passed into the partial.
+  # :as<~to_sym>:: The local name of the :with Object inside of the partial.
+  # :format<Symbol>:: The mime format that you want the partial to be in (:js, :html, etc.)
+  # others::
+  #   A Hash object names and values that will be the local names and values
+  #   inside the partial.
+  #
+  # ==== Example
+  #   partial :foo, :hello => @object
+  #
+  # The "_foo" partial will be called, relative to the current controller,
+  # with a local variable of +hello+ inside of it, assigned to @object.
+  def partial(template, opts={})
+
+    # partial :foo becomes "#{controller_name}/_foo"
+    # partial "foo/bar" becomes "foo/_bar"
+    template = template.to_s
+    kontroller = (m = template.match(/.*(?=\/)/)) ? m[0] : controller_name
+    template = "_#{File.basename(template)}"
+    
+    template_method, template_location = _template_for(template, opts.delete(:format) || content_type, kontroller)
+
+    (@_old_partial_locals ||= []).push @_merb_partial_locals
+
+    if opts.key?(:with)
+      with = opts.delete(:with)
+      as = opts.delete(:as) || template_location.match(%r[.*/_([^\.]*)])[1]
+      @_merb_partial_locals = opts
+      sent_template = [with].flatten.map do |temp|
+        @_merb_partial_locals[as.to_sym] = temp
+        send(template_method)
+      end.join
+    else
+      @_merb_partial_locals = opts
+      sent_template = send(template_method)
+    end
+    @_merb_partial_locals = @_old_partial_locals.pop
+    sent_template
+  end      
+  
+  # Take the options hash and handle it as appropriate.
+  # 
+  # ==== Parameters
+  # opts<Hash>:: The options hash that was passed into render.
+  # 
+  # ==== Options
+  # :status<~to_i>::
+  #   The status of the response will be set to opts[:status].to_i
+  # 
+  # ==== Returns
+  # Hash:: The options hash that was passed in.
+  def _handle_options!(opts)
+    self.status = opts[:status].to_i if opts[:status]
+    opts
+  end
+
+  # Get the layout that should be used. The content-type will be appended to
+  # the layout unless the layout already contains a "." in it.
+  #
+  # If no layout was passed in, this method will look for one with the same
+  # name as the controller, and finally one in "application.#{content_type}".
+  #
+  # ==== Parameters
+  # layout<~to_s>:: A layout, relative to the layout root. Defaults to nil.
+  # 
+  # ==== Returns
+  # String:: The method name that corresponds to the found layout.
+  # 
+  # ==== Raises
+  # TemplateNotFound::
+  #   If a layout was specified (either via layout in the class or by passing
+  #   one in to this method), and not found. No error will be raised if no
+  #   layout was specified, and the default layouts were not found.
+  def _get_layout(layout = nil)
+    if _layout && !layout
+      layout = _layout.instance_of?(Symbol) && self.respond_to?(_layout, true) ? send(_layout) : _layout
+    end
+    layout = layout.to_s if layout
+    
+    # If a layout was provided, throw an error if it's not found
+    if layout
+      template_method, template_location = _template_for(layout, layout.index(".") ? nil : content_type, "layout")
+      raise TemplateNotFound, "No layout found at #{template_location}" unless template_method
+      template_method
+
+    # If a layout was not provided, try the default locations
+    else
+      template, location = _template_for(controller_name, content_type, "layout")
+      template, location = _template_for("application", content_type, "layout") unless template
+      template
+    end
+  end
+  
+  # Iterate over the template roots in reverse order, and return the template 
+  # and template location of the first match.
+  #
+  # ==== Parameters
+  # thing<Object>:: The controller action.
+  # content_type<~to_s>:: The content type. Defaults to nil.
+  # controller<~to_s>:: The name of the controller. Defaults to nil.
+  #
+  # ==== Options (opts)
+  # :template<String>::
+  #   The location of the template to use. Defaults to whatever matches this
+  #   thing, content_type and controller.
+  #
+  # ==== Returns
+  # Array[Symbol, String]::
+  #   A pair consisting of the template method and location.
+  def _template_for(thing, content_type, controller=nil, opts={})
+    template_method = nil
+    template_location = nil
+    
+    self.class._template_roots.reverse_each do |root, template_location| 
+      template_location = root / (opts[:template] || self.send(template_location, thing, content_type, controller))
+      template_method = Merb::Template.template_for(template_location)
+      break if template_method && self.respond_to?(template_method)
+    end
+
+    [template_method, template_location]
+  end
+    
+  # Called in templates to get at content thrown in another template. The
+  # results of rendering a template are automatically thrown into :for_layout,
+  # so catch_content or catch_content(:for_layout) can be used inside layouts
+  # to get the content rendered by the action template.
+  #
+  # ==== Parameters
+  # obj<Object>:: The key in the thrown_content hash. Defaults to :for_layout.
+  #---
+  # @public
+  def catch_content(obj = :for_layout)
+    @_caught_content[obj]
+  end
+  
+  # Called in templates to store up content for later use. Takes a string
+  # and/or a block. First, the string is evaluated, and then the block is
+  # captured using the capture() helper provided by the template languages. The
+  # two are concatenated together.
+  #
+  # ==== Parameters
+  # obj<Object>:: The key in the thrown_content hash.
+  # string<String>:: Textual content. Defaults to nil.
+  # &block:: A block to be evaluated and concatenated to string.
+  #
+  # ==== Raises
+  # ArgumentError:: Neither string nor block given.
+  #
+  # ==== Example
+  #   throw_content(:foo, "Foo")
+  #   catch_content(:foo) #=> "Foo"
+  #---
+  # @public
+  def throw_content(obj, string = nil, &block)
+    unless string || block_given?
+      raise ArgumentError, "You must pass a block or a string into throw_content"
+    end
+    @_caught_content[obj] = string.to_s << (block_given? ? capture(&block) : "")
+  end
+  
+end