merb 0.4.1 → 0.4.2

data/lib/merb/mixins/erubis_capture.rb

@@ -6,7 +6,7 @@ module Merb
     
     # Provides direct acccess to the buffer for this view context
     def _buffer( the_binding )
-      @_buffer ||= eval( "_buf", the_binding )
+      @_buffer = eval( "_buf", the_binding )
     end
     
     # Capture allows you to extract a part of the template into an 

data/lib/merb/mixins/general_controller.rb

@@ -0,0 +1,258 @@
+# This module provides helper style functionality to all controllers.
+module Merb 
+  module GeneralControllerMixin
+    include Merb::ControllerExceptions
+    
+    # Returns a URL according to the defined route.  Accepts the path and
+    # an options hash.  The path specifies the route requested.  The options 
+    # hash fills in the dynamic parts of the route.
+    #
+    # Merb routes can often be one-way; if they use a regex to define
+    # the route, then knowing the controller & action won't be enough
+    # to reverse-generate the route.  However, if you use the default
+    # /controller/action/id?query route, +default_route+ can generate
+    # it for you.
+    #
+    # For easy reverse-routes that use a Regex, be sure to also add
+    # a name to the route, so +url+ can find it.
+    # 
+    # Nested resources such as:
+    #
+    #  r.resources :blogposts do |post|
+    #    post.resources :comments
+    #  end
+    #
+    # Provide the following routes:
+    #
+    #   [:blogposts, "/blogposts"]
+    #   [:blogpost, "/blogposts/:id"]
+    #   [:edit_blogpost, "/blogposts/:id/edit"]
+    #   [:new_blogpost, "/blogposts/new"]
+    #   [:custom_new_blogpost, "/blogposts/new/:action"]
+    #   [:comments, "/blogposts/:blogpost_id/comments"]
+    #   [:comment, "/blogposts/:blogpost_id/comments/:id"]
+    #   [:edit_comment, "/blogposts/:blogpost_id/comments/:id/edit"]
+    #   [:new_comment, "/blogposts/:blogpost_id/comments/new"]
+    #   [:custom_new_comment, "/blogposts/:blogpost_id/comments/new/:action"]
+    #
+    #
+    # ==== Parameters
+    #
+    # :route_name: - Symbol that represents a named route that you want to use, such as +:edit_post+.
+    # :new_params: - Parameters to be passed to the generated URL, such as the +id+ for a record to edit.
+    #
+    # ==== Examples
+    #
+    #  @post = Post.find(1)
+    #  @comment = @post.comments.find(1)
+    #
+    #  url(:blogposts)                                    # => /blogposts
+    #  url(:new_post)                                     # => /blogposts/new
+    #  url(:blogpost, @post)                              # => /blogposts/1
+    #  url(:edit_blogpost, @post)                         # => /blogposts/1/edit
+    #  url(:custom_new_blogpost, :action => 'alternate')  # => /blogposts/new/alternate
+    #   
+    #  url(:comments, :blogpost => @post)         # => /blogposts/1/comments
+    #  url(:new_comment, :blogpost => @post)      # => /blogposts/1/comments/new
+    #  url(:comment, @comment)                    # => /blogposts/1/comments/1
+    #  url(:edit_comment, @comment)               # => /blogposts/1/comments/1/edit
+    #  url(:custom_new_comment, :blogpost => @post)
+    #
+    #  url(:page => 2)                            # => /posts/show/1?page=2
+    #  url(:new_post, :page => 3)                 # => /posts/new?page=3
+    #  url('/go/here', :page => 3)                # => /go/here?page=3
+    #
+    #  url(:controller => "welcome")              # => /welcome
+    #  url(:controller => "welcome", :action => "greet")
+    #                                             # => /welcome/greet
+    #
+    def url(route_name = nil, new_params = {})
+      if route_name.is_a?(Hash)
+        new_params = route_name
+        route_name = nil
+      end
+      
+      url = if new_params.respond_to?(:keys) && route_name.nil? &&
+        !(new_params.keys & [:controller, :action, :id]).empty?
+          url_from_default_route(new_params)
+        elsif route_name.nil? && !route.regexp?
+          url_from_route(route, new_params)
+        elsif route_name.nil?
+          request.path + (new_params.empty? ? "" : "?" + params_to_query_string(new_params))
+        elsif route_name.is_a?(Symbol)
+          url_from_route(route_name, new_params)
+        elsif route_name.is_a?(String)
+          route_name + (new_params.empty? ? "" : "?" + params_to_query_string(new_params))
+        else
+          raise "URL not generated: #{route_name.inspect}, #{new_params.inspect}"
+        end
+      url = Merb::Server.config[:path_prefix] + url if Merb::Server.config[:path_prefix]
+      url
+    end
+
+    def url_from_route(symbol, new_params = {})
+      if new_params.respond_to?(:new_record?) && new_params.new_record?
+        symbol = "#{symbol}".singularize.to_sym
+        new_params = {}
+      end
+      route = symbol.is_a?(Symbol) ? Merb::Router.named_routes[symbol] : symbol
+      unless route
+        raise InternalServerError, "URL could not be constructed. Route symbol not found: #{symbol.inspect}" 
+      end
+      path = route.generate(new_params, params)
+      keys = route.symbol_segments
+      if new_params.is_a? Hash
+        if ext = format_extension(new_params)
+          new_params.delete(:format)
+          path += "." + ext
+        end
+        extras = new_params.reject{ |k, v| keys.include?(k) }
+        path += "?" + params_to_query_string(extras) unless extras.empty?
+      end
+      path
+    end
+    
+    # this is pretty ugly, but it works.  TODO: make this cleaner
+    def url_from_default_route(new_params)
+      query_params = new_params.reject do |k,v|
+        [:controller, :action, :id, :format].include?(k)
+      end
+      controller = get_controller_for_url_generation(new_params)
+      url = "/#{controller}"
+      if new_params[:action] || new_params[:id] ||
+                new_params[:format] || !query_params.empty?
+        action = new_params[:action] || params[:action]
+        url += "/#{action}"
+      end
+      if new_params[:id]
+        url += "/#{new_params[:id]}"
+      end
+      if format = new_params[:format]
+        format = params[:format] if format == :current
+        url += ".#{format}"
+      end
+      unless query_params.empty?
+        url += "?" + params_to_query_string(query_params)
+      end
+      url
+    end
+
+    protected
+
+    # Creates query string from params, supporting nested arrays and hashes.
+    # ==== Example
+    #   params_to_query_string(:user => {:filter => {:name => "quux*"}, :order => ["name"]})
+    #   # => user[filter][name]=quux%2A&user[order][]=name
+    def params_to_query_string(value, prefix = nil)
+      case value
+      when Array
+        value.map { |v|
+          params_to_query_string(v, "#{prefix}[]")
+        } * "&"
+      when Hash
+        value.map { |k, v|
+          params_to_query_string(v, prefix ? "#{prefix}[#{escape(k)}]" : escape(k))
+        } * "&"
+      else
+        "#{prefix}=#{escape(value)}"
+      end
+    end
+    
+    # +format_extension+ dictates when named route URLs generated by the url
+    # method will have a file extension. It will return either false or the format 
+    # extension to append.
+    #
+    # ==== Configuration Options
+    #
+    # By default, non-HTML URLs will be given an extension. It is posible 
+    # to override this behaviour by setting +:use_format_in_urls+ in your 
+    # Merb config (merb.yml) to either true/false.
+    #
+    # +true+  Results in all URLs (even HTML) being given extensions.
+    #         This effect is often desirable when you have many formats and dont
+    #         wish to treat .html any differently than any other format. 
+    # +false+ Results in no URLs being given extensions and +format+
+    #         gets treated just like any other param (default).
+    #
+    # ==== Method parameters
+    # 
+    # +new_params+ - New parameters to be appended to the URL
+    #
+    # ==== Examples
+    #
+    #   url(:post, :id => post, :format => 'xml')
+    #   # => /posts/34.xml
+    #
+    #   url(:accounts, :format => 'yml')
+    #   # => /accounts.yml
+    #
+    #   url(:edit_product, :id => 3, :format => 'html')
+    #   # => /products/3
+    #
+    def format_extension(new_params={})
+      use_format = Merb::Server.config[:use_format_in_urls]
+      if use_format.nil?
+        prms = params.merge(new_params)
+        use_format = prms[:format] != 'html' && prms[:format]
+      end
+      use_format
+    end
+    
+        
+    # Creates an MD5 hashed token based on the current time.
+    #
+    # ==== Example
+    #   make_token
+    #   # => "b9a82e011694cc13a4249731b9e83cea" 
+    #
+    def make_token
+      require 'digest/md5'
+      Digest::MD5.hexdigest("#{inspect}#{Time.now}#{rand}")
+    end
+
+    # Escapes the string representation of +obj+ and escapes
+    # it for use in XML.
+    #
+    # ==== Parameter
+    #
+    # +obj+ - The object to escape for use in XML.
+    #
+    def escape_xml(obj)
+      obj.to_s.gsub(/[&<>"']/) { |s| Merb::Const::ESCAPE_TABLE[s] }
+    end
+    alias h escape_xml
+    alias html_escape escape_xml
+  
+    # Escapes +s+ for use in a URL.
+    #
+    # ==== Parameter
+    #
+    # +s+ - String to URL escape.
+    #
+    def escape(s)
+      s.to_s.gsub(/([^ a-zA-Z0-9_.-]+)/n) {
+        '%'+$1.unpack('H2'*$1.size).join('%').upcase
+      }.tr(' ', '+')
+    end
+  
+    # Unescapes a string (i.e., reverse URL escaping).
+    #
+    # ==== Parameter 
+    #
+    # +s+ - String to unescape.
+    #
+    def unescape(s)
+      s.tr('+', ' ').gsub(/((?:%[0-9a-fA-F]{2})+)/n){
+        [$1.delete('%')].pack('H*')
+      }
+    end
+    
+    private
+    # Used for sepccing
+    def get_controller_for_url_generation(options)
+      raise "Controller Not Specified" unless options[:controller]
+      options[:controller]
+    end
+      
+  end
+end

data/lib/merb/mixins/render.rb

@@ -5,7 +5,7 @@ module Merb
     include Merb::ControllerExceptions
     
     def self.included(base)
-      base.class_eval {        
+      base.class_eval {
         class_inheritable_accessor :_template_root,
                                    :_layout,
                                    :_templates,
@@ -16,7 +16,7 @@ module Merb
         self._templates = {}
         self._cached_partials = {}
         
-        attr_accessor :template        
+        attr_accessor :template
       }
     end
 
@@ -131,7 +131,7 @@ module Merb
     # This will ensure that all instance variable are up to date in your views.
     #
     def render(*args,&blk)
-      opts = Hash === args.last ? args.pop : {}
+      opts = (Hash === args.last) ? args.pop : {}
     
       action = opts[:action] || params[:action]
       opts[:layout] ||= _layout 
@@ -145,7 +145,19 @@ module Merb
           fmt = content_type
           if transform_method = Merb.mime_transform_method(fmt)
             set_response_headers fmt
-            return obj.send(transform_method)
+            transform_args = provided_format_arguments_for(fmt)
+            return case transform_args
+              when Hash   then obj.send(transform_method, transform_args)
+              when Array  then obj.send(transform_method, *transform_args)
+              when Proc   then
+                case transform_args.arity
+                  when 3 then transform_args.call(obj, self, transform_method)
+                  when 2 then transform_args.call(obj, self)
+                  when 1 then transform_args.call(obj)
+                  else transform_args.call
+                end
+              else obj.send(transform_method)
+            end
           end  
         end
       end 
@@ -255,9 +267,13 @@ module Merb
       return " "
     end
 
+  	# Sets the response's status to the specified value.  Use either an 
+   	# integer (200, 201, 302, etc.), or a Symbol as defined in  
+   	# Merb::ControllerExceptions::RESPONSE_CODES, such as :not_found, 
+   	# :created or :see_other.
     def set_status(status)
       if status.kind_of?(Symbol)
-        status  = Merb::ControllerExceptions::RESPONSE_CODES(status)
+        status  = Merb::ControllerExceptions::STATUS_CODES[status]
         status || raise("Can't find a response code with that name")
       end
       @_status = status
@@ -286,7 +302,7 @@ module Merb
       opts[:as] ||= template[(template.rindex('/_') + 2)..-1].split('.').first
 
       if opts[:with] # Render a collection or an object
-       partial_for_collection(template, opts[:with], opts)
+       partial_for_collection(template, opts.delete(:with), opts)
       else # Just render a partial
        engine = Template.engine_for(template)
        render_partial(template, engine, opts || {})
@@ -303,29 +319,34 @@ module Merb
     private
 
       def render_partial(template, engine, locals={})
-       @_merb_partial_locals = locals
-       options = {
-         :file => template,
-         :view_context => clean_view_context(engine),
-         :opts => { :locals => locals }
-       }
-       engine.transform(options)
+        @_merb_partial_locals = locals
+        options = {
+          :file => template,
+          :view_context => clean_view_context(engine),
+          :opts => { :locals => locals }
+        }
+        engine.transform(options)
       end
 
       def partial_for_collection(template, collection, opts={})
-       # Delete the internal keys, so that everything else is considered
-       # a local declaration in the partial
-       local_name = opts.delete(:as)
-       opts.delete(:with)
+        # Delete the internal keys, so that everything else is considered
+        # a local declaration in the partial
+        local_name = opts.delete(:as)
 
-       engine = Template.engine_for(template)
+        engine = Template.engine_for(template)
+
+        buffer = []
+
+        collection = [collection].flatten
+        collection.each_with_index do |object, count|
+          opts.merge!({
+              local_name.to_sym => object,
+              :count            => count
+          })
+          buffer << render_partial(template, engine, opts)
+        end
 
-       ret = ''
-       [ collection ].flatten.each do |object|
-         opts.merge!({local_name.to_sym => object})
-         ret << render_partial(template, engine, opts)
-       end
-       ret
+        buffer.join
       end
     
       # this returns a ViewContext object populated with all

data/lib/merb/mixins/responder.rb

@@ -18,17 +18,29 @@ module Merb
       raise ArgumentError unless key.is_a?(Symbol) && values.is_a?(Array)
       ResponderMixin::Rest::TYPES.update(key => values)
       add_response_headers!(key, new_response_headers)   
-      ResponderMixin::Rest::TRANSFORM_METHODS.merge!(key => transform_method) 
+      ResponderMixin::Rest::TRANSFORM_METHODS.merge!(key => transform_method)
     end    
     
     def remove_mime_type(key)
       key == :all ? false : ResponderMixin::Rest::TYPES.delete(key)
     end
     
+    # Return the method name (if any) for the mimetype
     def mime_transform_method(key)
       ResponderMixin::Rest::TRANSFORM_METHODS[key]
     end
     
+    # Return default arguments for transform method (if any)
+    def mime_transform_method_defaults(key)
+      ResponderMixin::Rest::TRANSFORM_METHOD_DEFAULTS[key]
+    end
+    
+    # Set default arguments/proc for a format transform method
+    def set_mime_transform_method_defaults(key, *args, &block)
+      raise "Unknown mimetype #{key}" unless ResponderMixin::Rest::TRANSFORM_METHODS[key]
+      args = block if block_given?
+      ResponderMixin::Rest::TRANSFORM_METHOD_DEFAULTS[key] = args unless args.empty?
+    end
     
     # Adds outgoing headers to a mime type.  This can be done with the Merb.add_mime_type method
     # or directly here.  
@@ -165,8 +177,11 @@ module Merb
     
     def self.included(base) # :nodoc:
       base.extend(ClassMethods)
-      base.class_eval { class_inheritable_accessor :class_provided_formats }
-      base.class_provided_formats = [:html]
+      base.class_eval do
+        class_inheritable_accessor :class_provided_formats
+        class_inheritable_accessor :class_provided_format_arguments
+      end
+      base.reset_provides
     end
 
     module ClassMethods
@@ -174,56 +189,103 @@ module Merb
       # Adds symbols representing formats to the controller's
       # default list of provided_formats.  These will apply to
       # every action in the controller, unless modified in the action.
-      def provides(*formats)
-        formats.each {|fmt|
+      # If the last argument is a Hash or an Array, these are regarded
+      # as arguments to pass to the to_<mime_type> method as needed.
+      def provides(*formats, &block)
+        options = extract_provides_options(formats, &block)
+        formats.each do |fmt|
           self.class_provided_formats << fmt unless class_provided_formats.include?(fmt)
-        }
+          self.class_provided_format_arguments[fmt] = options unless options.nil?
+        end
       end
       
       # Overwrites the controller's list of provided_formats. These
       # will apply to every action in the controller, unless modified
       # in the action.
       def only_provides(*formats)
-        self.class_provided_formats = formats
+        clear_provides
+        provides(*formats)
       end
       
       # Removes formats from the controller's
-      # default list of provided_formats.  These will apply to
+      # default list of provided_formats. These will apply to
       # every action in the controller, unless modified in the action.
       def does_not_provide(*formats)
         self.class_provided_formats -= formats
+        formats.each { |fmt| self.class_provided_format_arguments.delete(fmt) }
       end
+      
+      # Clear any formats and their options
+      def clear_provides
+        self.class_provided_formats = []
+        self.class_provided_format_arguments = {}
+      end
+      
+      # Reset to the default list of formats
+      def reset_provides
+        only_provides(:html)
+      end
+      
+      # Extract arguments for provided format methods
+      def extract_provides_options(args, &block)
+        return block if block_given?
+        case args.last
+          when Hash   then [args.pop]
+          when Array  then args.pop
+          when Proc   then args.pop
+          else nil
+        end
+      end
+            
     end
     
     # Returns the current list of formats provided for this instance
     # of the controller.  It starts with what has been set in the controller
     # (or :html by default) but can be modifed on a per-action basis.
     def provided_formats
-      @_provided_formats ||= class_provided_formats
+      @_provided_formats ||= class_provided_formats.dup
     end
     
     # Sets the provided formats for this action.  Usually, you would
     # use a combination of +provides+, +only_provides+ and +does_not_provide+
     # to manage this, but you can set it directly.
-    def provided_formats=(*formats)
-      raise "Cannot modify provided_formats because content_type has already been set" if content_type_set?
-      @_provided_formats = formats.flatten
+    # If the last argument is a Hash or an Array, these are regarded
+    # as arguments to pass to the to_<mime_type> method as needed. 
+    def set_provided_formats(*formats, &block)
+      raise_if_content_type_already_set!
+      @_provided_formats = []
+      @_provided_format_arguments = {}
+      provides(*formats.flatten, &block)
+    end
+    alias :provided_formats= :set_provided_formats
+    
+    # Returns a Hash of arguments for format methods
+    def provided_format_arguments
+      @_provided_format_arguments ||= Hash.new.replace(class_provided_format_arguments)
+    end
+    
+    # Returns the arguments (if any) for the mime_transform_method call
+    def provided_format_arguments_for(fmt)
+      self.provided_format_arguments[fmt] || Merb.mime_transform_method_defaults(fmt)
     end
     
     # Adds formats to the list of provided formats for this particular 
     # request.  Usually used to add formats to a single action.  See also
     # the controller-level provides that affects all actions in a controller.
-    def provides(*formats)
-      formats.each {|fmt|
-        self.provided_formats += [fmt] unless provided_formats.include?(fmt)
-      }
+    def provides(*formats, &block)
+      raise_if_content_type_already_set!
+      options = self.class.extract_provides_options(formats, &block)
+      formats.each do |fmt|
+        self.provided_formats << fmt unless provided_formats.include?(fmt)
+        self.provided_format_arguments[fmt] = options unless options.nil?
+      end
     end
     
     # Sets list of provided formats for this particular 
     # request.  Usually used to limit formats to a single action.  See also
     # the controller-level provides that affects all actions in a controller.
     def only_provides(*formats)
-      self.provided_formats = formats.flatten
+      self.set_provided_formats(*formats)
     end
     
     # Removes formats from the list of provided formats for this particular 
@@ -231,7 +293,9 @@ module Merb
     # also the controller-level provides that affects all actions in a
     # controller.
     def does_not_provide(*formats)
-      self.provided_formats -= formats.flatten
+      formats.flatten!
+      self.provided_formats -= formats
+      formats.each { |fmt| self.provided_format_arguments.delete(fmt) }
     end
     
     # Do the content negotiation:
@@ -297,11 +361,18 @@ module Merb
       @_content_type = new_type
     end
 
+    private
+    
+    def raise_if_content_type_already_set!
+      raise "Cannot modify provided_formats because content_type has already been set" if content_type_set?
+    end
+
     module Rest
       
       TYPES = {}
       RESPONSE_HEADERS = {}
       TRANSFORM_METHODS = {}
+      TRANSFORM_METHOD_DEFAULTS = {}
 
       class Responder