merb-core 0.9.8 → 0.9.9

data/lib/merb-core/dispatch/router/resources.rb

@@ -20,6 +20,8 @@ module Merb
       # :member<Hash>:
       #   Special settings and resources related to a specific member of this
       #   resource.
+      # :identify<Symbol|Array>: The method(s) that should be called on the object
+      #   before inserting it into an URL.
       # :keys<Array>:
       #   A list of the keys to be used instead of :id with the resource in the order of the url.
       # :singular<Symbol>
@@ -63,24 +65,40 @@ module Merb
       #  r.resources :posts do |posts|
       #    posts.resources :comments
       #  end
-      #---
-      # @public
+      #
+      # @api public
       def resources(name, *args, &block)
         name       = name.to_s
         options    = extract_options_from_args!(args) || {}
+        match_opts = options.except(*resource_options)
+        options    = options.only(*resource_options)
         singular   = options[:singular] ? options[:singular].to_s : Extlib::Inflection.singularize(name)
-        klass      = args.first ? args.first.to_s : Extlib::Inflection.classify(singular)
-        keys       = [ options.delete(:keys) || options.delete(:key) || :id ].flatten
+        klass_name = args.first ? args.first.to_s : Extlib::Inflection.classify(singular)
+        klass      = Object.full_const_get(klass_name) rescue nil
+        keys       = options.delete(:keys) || options.delete(:key)
         params     = { :controller => options.delete(:controller) || name }
         collection = options.delete(:collection) || {}
         member     = { :edit => :get, :delete => :get }.merge(options.delete(:member) || {})
+        
+        # Use the identifier for the class as a default
+        if klass
+          keys ||= options[:identify]
+          keys ||= @identifiers[klass]
+        elsif options[:identify]
+          raise Error, "The constant #{klass_name} does not exist, please specify the constant for this resource"
+        end
+        
+        keys = [ keys || :id ].flatten
+        
 
         # Try pulling :namespace out of options for backwards compatibility
         options[:name_prefix]       ||= nil # Don't use a name_prefix if not needed
         options[:resource_prefix]   ||= nil # Don't use a resource_prefix if not needed
         options[:controller_prefix] ||= options.delete(:namespace)
 
-        self.namespace(name, options).to(params) do |resource|
+        context = options[:identify]
+        context = klass && options[:identify] ? identify(klass => options.delete(:identify)) : self
+        context.namespace(name, options).to(params) do |resource|
           root_keys = keys.map { |k| ":#{k}" }.join("/")
           
           # => index
@@ -102,45 +120,48 @@ module Merb
           end
 
           # => show
-          resource.match("/#{root_keys}(.:format)", :method => :get).to(:action => "show").
-            name(singular).register_resource(klass)
+          resource.match("/#{root_keys}(.:format)", match_opts.merge(:method => :get)).to(:action => "show").
+            name(singular).register_resource(klass_name)
 
           # => user defined member routes
           member.each_pair do |action, method|
             action = action.to_s
-            resource.match("/#{root_keys}/#{action}(.:format)", :method => method).
-              to(:action => "#{action}").name(action, singular).register_resource(klass, action)
+            resource.match("/#{root_keys}/#{action}(.:format)", match_opts.merge(:method => method)).
+              to(:action => "#{action}").name(action, singular).register_resource(klass_name, action)
           end
 
           # => update
-          resource.match("/#{root_keys}(.:format)", :method => :put).
+          resource.match("/#{root_keys}(.:format)", match_opts.merge(:method => :put)).
             to(:action => "update")
             
           # => destroy
-          resource.match("/#{root_keys}(.:format)", :method => :delete).
+          resource.match("/#{root_keys}(.:format)", match_opts.merge(:method => :delete)).
             to(:action => "destroy")
 
           if block_given?
             nested_keys = keys.map do |k|
               k.to_s == "id" ? ":#{singular}_id" : ":#{k}"
             end.join("/")
+
+            nested_match_opts = match_opts.except(:id)
+            nested_match_opts["#{singular}_id".to_sym] = match_opts[:id] if match_opts[:id]
             
             # Procs for building the extra collection/member resource routes
-            placeholder = Router.resource_routes[ [@options[:resource_prefix], klass].flatten.compact ]
+            placeholder = Router.resource_routes[ [@options[:resource_prefix], klass_name].flatten.compact ]
             builders    = {}
             
             builders[:collection] = lambda do |action, to, method|
-              resource.before(placeholder).match("/#{action}(.:format)", :method => method).
+              resource.before(placeholder).match("/#{action}(.:format)", match_opts.merge(:method => method)).
                 to(:action => to).name(action, name).register_resource(name, action)
             end
             
             builders[:member] = lambda do |action, to, method|
-              resource.match("/#{root_keys}/#{action}(.:format)", :method => method).
-                to(:action => to).name(action, singular).register_resource(klass, action)
+              resource.match("/#{root_keys}/#{action}(.:format)", match_opts.merge(:method => method)).
+                to(:action => to).name(action, singular).register_resource(klass_name, action)
             end
             
-            resource.options(:name_prefix => singular, :resource_prefix => klass).
-              match("/#{nested_keys}").resource_block(builders, &block)
+            resource.options(:name_prefix => singular, :resource_prefix => klass_name).
+              match("/#{nested_keys}", nested_match_opts).resource_block(builders, &block)
           end
         end # namespace
       end # resources
@@ -196,8 +217,8 @@ module Merb
       #   r.resource :account, :namespace => "admin" do |account|
       #     account.resources :preferences, :controller => "settings"
       #   end
-      # ---
-      # @public
+      #
+      # @api public
       def resource(name, *args, &block)
         name    = name.to_s
         options = extract_options_from_args!(args) || {}
@@ -210,6 +231,7 @@ module Merb
 
         self.namespace(name, options).to(params) do |resource|
           # => show
+          
           resource.match("(.:format)", :method => :get).to(:action => "show").
             name(name).register_resource(name)
             
@@ -244,16 +266,23 @@ module Merb
       
     protected
     
+      #api private
       def register_resource(*key)
         key = [@options[:resource_prefix], key].flatten.compact
         @route.resource = key
         self
       end
 
+      #api private
       def resource_block(builders, &block)
         behavior = ResourceBehavior.new(builders, @proxy, @conditions, @params, @defaults, @identifiers, @options, @blocks)
         with_behavior_context(behavior, &block)
       end
+      
+      def resource_options
+        [:singular, :keys, :key, :controller, :member, :collection, :identify,
+          :name_prefix, :resource_prefix, :controller_prefix, :namespace, :path]
+      end
 
     end # Resources
     
@@ -264,12 +293,14 @@ module Merb
     # Adding the collection and member methods to behavior
     class ResourceBehavior < Behavior #:nodoc:
       
+      #api private
       def initialize(builders, *args)
         super(*args)
         @collection = builders[:collection]
         @member     = builders[:member]
       end
       
+      #api private
       def collection(action, options = {})
         action = action.to_s
         method = options[:method]
@@ -277,6 +308,7 @@ module Merb
         @collection[action, to, method]
       end
       
+      # @api private
       def member(action, options = {})
         action = action.to_s
         method = options[:method]

data/lib/merb-core/dispatch/router/route.rb

@@ -79,21 +79,48 @@ module Merb
         @name
       end
       
-      # === Compiled method ===
+      # Generates the URL for the route given the passed arguments. The
+      # method will first match the anonymous parameters to route params
+      # and will convert all the parameters according to the specifed
+      # object identifiers.
+      #
+      # Then the named parameters are passed to a compiled generation proc.
+      #
+      # ==== Parameters
+      # args<Array>::
+      #   The arguments passed to the public #url method with the name
+      #   of the route removed. This is an array of the anonymous parameters
+      #   followed by a hash containing the named parameters.
+      #
+      # defaults<Hash>::
+      #   A hash of parameters to use to generate the route if there are
+      #   any missing required parameters. This is usually the parameters
+      #   for the current request
+      #
+      # ==== Returns
+      # String:: The generated URL.
       def generate(args = [], defaults = {})
         raise GenerationError, "Cannot generate regexp Routes" if regexp?
         
         params = extract_options_from_args!(args) || { }
         
+        params.each do |k, v|
+          params[k] = identify(v, k)
+        end
+        
         # Support for anonymous params
         unless args.empty?
           # First, let's determine which variables are missing
           variables = @variables - params.keys
           
-          raise GenerationError, "The route has #{@variables.length} variables: #{@variables.inspect}" if args.length > variables.length
-          
-          args.each_with_index do |param, i|
-            params[variables[i]] ||= param
+          args.each do |param|
+            raise GenerationError, "The route has #{@variables.length} variables: #{@variables.inspect}" if variables.empty?
+            
+            if identifier = identifier_for(param) and identifier.is_a?(Array)
+              identifier.each { |ident| params[variables.shift] = param.send(ident) }
+            else
+              params[variables.shift] ||= identify(param)
+            end
           end
         end
         
@@ -101,7 +128,47 @@ module Merb
         uri = Merb::Config[:path_prefix] + uri if Merb::Config[:path_prefix]
         uri
       end
+      
+      # Identifies the object according to the identifiers set while building
+      # the routes. Identifying an object means picking an instance method to
+      # call on the object that will return a string representation of the
+      # object for the route being generated. If the identifier is an array,
+      # then a param_key must be present and match one of the elements of the
+      # identifier array.
+      #
+      # param_keys that end in _id are treated slightly differently in order
+      # to get nested resources to work correctly.
+      def identify(obj, param_key = nil)
+        identifier = identifier_for(obj)
+        if identifier.is_a?(Array)
+          # First check if the param_key exists as an identifier
+          return obj.send(param_key) if identifier.include?(param_key)
+          # If the param_key ends in _id, just return the object id
+          return obj.id if "#{param_key}" =~ /_id$/
+          # Otherwise, raise an error
+          raise GenerationError, "The object #{obj.inspect} cannot be identified with #{identifier.inspect} for #{param_key}"
+        else
+          identifier ? obj.send(identifier) : obj
+        end
+      end
+      
+      # Returns the identifier for the passed object. Built in core ruby classes are
+      # always identified with to_s. The method will return nil in that case (since
+      # to_s is the default for objects that do not have identifiers.)
+      def identifier_for(obj)
+        return if obj.is_a?(String)    || obj.is_a?(Symbol)     || obj.is_a?(Numeric)  ||
+                  obj.is_a?(TrueClass) || obj.is_a?(FalseClass) || obj.is_a?(NilClass) ||
+                  obj.is_a?(Array)     || obj.is_a?(Hash)
+        
+        @identifiers.each do |klass, identifier|
+          return identifier if obj.is_a?(klass)
+        end
+        
+        return nil
+      end
 
+      # Returns the if statement and return value for for the main
+      # Router.match compiled method.
       def compiled_statement(first)
         els_if = first ? '  if ' : '  elsif '
 
@@ -110,13 +177,9 @@ module Merb
         
         # First, we need to always return the value of the
         # deferred block if it explicitly matched the route
-        if @redirects && @deferred_procs.any?
-          code << "    return [#{@index.inspect}, block_result] if request.matched?" << "\n" 
-          code << "    request.redirects!" << "\n"
-          code << "    [#{@index.inspect}, { :url => #{@redirect_url.inspect}, :status => #{@redirect_status.inspect} }]" << "\n"
-        elsif @redirects
-          code << "    request.redirects!" << "\n"
-          code << "    [#{@index.inspect}, { :url => #{@redirect_url.inspect}, :status => #{@redirect_status.inspect} }]" << "\n"
+        if @redirects
+          code << "    return [#{@index.inspect}, block_result] if request.matched?" << "\n" if @deferred_procs.any?
+          code << "    [#{@index.inspect}, Merb::Rack::Helpers.redirect(#{@redirect_url.inspect}, :status => #{@redirect_status.inspect})]" << "\n"
         elsif @deferred_procs.any?
           code << "    [#{@index.inspect}, block_result]" << "\n"
         else
@@ -258,7 +321,7 @@ module Merb
           segments.each_with_index do |segment, i|
             bits << case
               when segment.is_a?(String) then segment
-              when segment.is_a?(Symbol) then '#{param_for_route(cached_' + segment.to_s + ')}'
+              when segment.is_a?(Symbol) then '#{cached_' + segment.to_s + '}'
               when segment.is_a?(Array) && segment.any? { |s| !s.is_a?(String) } then "\#{#{@opt_segment_stack.last.shift}}"
               else ""
             end
@@ -267,16 +330,6 @@ module Merb
           bits
         end
         
-        def param_for_route(param)
-          case param
-            when String, Symbol, Numeric, TrueClass, FalseClass, NilClass
-              param
-            else
-              _, identifier = @identifiers.find { |klass, _| param.is_a?(klass) }
-              identifier ? param.send(identifier) : param
-          end
-        end
-        
       end
 
     # === Conditions ===

data/lib/merb-core/dispatch/session.rb

@@ -6,6 +6,8 @@ module Merb
     # Returns stores list constructed from
     # configured session stores (:session_stores config option)
     # or default one (:session_store config option).
+    # 
+    # @api private
     def self.session_stores
       @session_stores ||= begin
         config_stores = Array(
@@ -15,7 +17,7 @@ module Merb
       end
     end
   end # Config
-
+  
   # The Merb::Session module gets mixed into Merb::SessionContainer to allow
   # app-level functionality (usually found in app/models/merb/session.rb) for
   # session.
@@ -23,35 +25,37 @@ module Merb
   # You can use this module to implement additional methods to simplify
   # building wizard-like application components,
   # authentication frameworks, etc.
+  # 
+  # Session configuration options:
+  #
+  # :session_id_key           The key by which a session value/id is
+  #                           retrieved; defaults to _session_id
+  #
+  # :session_expiry           When to expire the session cookie;
+  #                           by defaults session expires when browser quits.
+  #
+  # :session_secret_key       A secret string which is used to sign/validate
+  #                           session data; min. 16 chars
+  #
+  # :default_cookie_domain    The default domain to write cookies for.
   module Session
   end
-
+  
   # This is mixed into Merb::Controller on framework boot.
   module SessionMixin
     # Raised when no suitable session store has been setup.
     class NoSessionContainer < StandardError; end
-
+    
     # Raised when storing more data than the available space reserved.
     class SessionOverflow < StandardError; end
-
-    # Session configuration options:
-    #
-    # :session_id_key           The key by which a session value/id is
-    #                           retrieved; defaults to _session_id
-    #
-    # :session_expiry           When to expire the session cookie;
-    #                           defaults to 2 weeks
-    #
-    # :session_secret_key       A secret string which is used to sign/validate
-    #                           session data; min. 16 chars
-    #
-    # :default_cookie_domain    The default domain to write cookies for.
+    
+    # @api private
     def self.included(base)
       # Register a callback to finalize sessions - needs to run before the cookie
       # callback extracts Set-Cookie headers from request.cookies.
       base._after_dispatch_callbacks.unshift lambda { |c| c.request.finalize_session }
     end
-
+    
     # ==== Parameters
     # session_store<String>:: The type of session store to access.
     #
@@ -60,9 +64,9 @@ module Merb
     def session(session_store = nil)
       request.session(session_store)
     end
-
+    
     # Module methods
-
+    
     # ==== Returns
     # String:: A random 32 character string for use as a unique session ID.
     def rand_uuid
@@ -77,59 +81,76 @@ module Merb
       ]
       "%04x%04x%04x%04x%04x%06x%06x" % values
     end
-
+    
     # Marks this session as needing a new cookie.
+    # 
+    # @api private
     def needs_new_cookie!
       @_new_cookie = true
     end
-
+    
+    # Does session need new cookie?
+    # 
+    # ==== Returns
+    # Boolean:: true if a new cookie is needed, false otherwise.
+    # 
+    # @api private
     def needs_new_cookie?
       @_new_cookie
     end
-
+    
     module_function :rand_uuid, :needs_new_cookie!, :needs_new_cookie?
-
+    
     module RequestMixin
-
+      
+      # Adds class methods to Merb::Request object.
+      # Sets up repository of session store types.
+      # Sets the session ID key and expiry values.
       def self.included(base)
         base.extend ClassMethods
-
+        
         # Keep track of all known session store types.
         base.cattr_accessor :registered_session_types
         base.registered_session_types = Dictionary.new
         base.class_inheritable_accessor :_session_id_key, :_session_secret_key,
                                         :_session_expiry
-
+        
         base._session_id_key        = Merb::Config[:session_id_key] || '_session_id'
         base._session_expiry        = Merb::Config[:session_expiry] || 0
         base._session_secret_key    = Merb::Config[:session_secret_key]
       end
-
+      
       module ClassMethods
-
+        
         # ==== Parameters
         # name<~to_sym>:: Name of the session type to register.
         # class_name<String>:: The corresponding class name.
         #
         # === Notres
         # This is automatically called when Merb::SessionContainer is subclassed.
+        # 
+        # @api private
         def register_session_type(name, class_name)
           self.registered_session_types[name.to_sym] = class_name
         end
-
+        
       end
-
+      
       # The default session store type.
+      # 
+      # @api private
       def default_session_store
         Merb::Config[:session_store] && Merb::Config[:session_store].to_sym
       end
-
+      
       # ==== Returns
       # Hash:: All active session stores by type.
+      # 
+      # @api private
       def session_stores
         @session_stores ||= {}
       end
-
+      
       # Returns session container. Merb is able to handle multiple session
       # stores, hence a parameter to pick it.
       #
@@ -140,6 +161,12 @@ module Merb
       # === Notes
       # If no suitable session store type is given, it defaults to
       # cookie-based sessions.
+      # 
+      # ==== Returns
+      # SessionContainer::
+      #   an instance of a session store extending Merb::SessionContainer.
+      # 
+      # @api public
       def session(session_store = nil)
         session_store ||= default_session_store
         if class_name = self.class.registered_session_types[session_store]
@@ -154,12 +181,14 @@ module Merb
           raise NoSessionContainer, msg            
         end
       end
-
+      
       # ==== Parameters
       # new_session<Merb::SessionContainer>:: A session store instance.
       #
       # === Notes
       # The session is assigned internally by its session_store_type key.
+      # 
+      # @api private
       def session=(new_session)
         if self.session?(new_session.class.session_store_type)
           original_session_id = self.session(new_session.class.session_store_type).session_id
@@ -169,21 +198,30 @@ module Merb
         end
         session_stores[new_session.class.session_store_type] = new_session
       end
-
+      
       # Whether a session has been setup
+      # 
+      # ==== Returns
+      # Boolean:: true if the session is part of the session stores configured.
+      # 
+      # @api private
       def session?(session_store = nil)
         (session_store ? [session_store] : session_stores).any? do |type, store|
           store.is_a?(Merb::SessionContainer)
         end
       end
-
+      
       # Teardown and/or persist the current sessions.
+      # 
+      # @api private
       def finalize_session
         session_stores.each { |name, store| store.finalize(self) }
       end
       alias :finalize_sessions :finalize_session
-
+      
       # Assign default cookie values
+      # 
+      # @api private
       def default_cookies
         defaults = {}
         if route && route.allow_fixation? && params.key?(_session_id_key)
@@ -198,6 +236,8 @@ module Merb
       # ==== Parameters
       # value<String>:: The value of the session cookie; either the session id or the actual encoded data.
       # options<Hash>:: Cookie options like domain, path and expired.
+      # 
+      # @api private
       def set_session_cookie_value(value, options = {})
         defaults = {}
         defaults[:expires] = Time.now + _session_expiry if _session_expiry > 0
@@ -207,12 +247,16 @@ module Merb
 
       # ==== Returns
       # String:: The value of the session cookie; either the session id or the actual encoded data.
+      # 
+      # @api private
       def session_cookie_value
         cookies[_session_id_key]
       end
       alias :session_id :session_cookie_value
       
       # Destroy the session cookie.
+      # 
+      # @api private
       def destroy_session_cookie
         cookies.delete(_session_id_key)
       end