merb-core 0.9.8 → 0.9.9

data/lib/merb-core/core_ext/hash.rb

@@ -1,4 +1,13 @@
 class Hash
+  # Returns the value of self for each argument and deletes those entries.
+  #
+  # ==== Parameters
+  # *args:: the keys whose values should be extracted and deleted.
+  #
+  # ==== Returns
+  # Array[Object]:: The values of the provided arguments in corresponding order.
+  #
+  # @api public
   def extract!(*args)
     args.map do |arg|
       self.delete(arg)

data/lib/merb-core/core_ext/kernel.rb

@@ -1,5 +1,11 @@
 require 'rubygems/dependency'
 
+module Gem
+  class Dependency
+    attr_accessor :require_block
+  end
+end
+
 module Kernel
   
   # Keep track of all required dependencies. 
@@ -11,8 +17,10 @@ module Kernel
   # @return <Gem::Dependency> Dependency information
   #
   # @api private
-  def track_dependency(name, *ver)
-    dep = Gem::Dependency.new(name, ver)
+  def track_dependency(name, *ver, &blk)
+    dep = Gem::Dependency.new(name, ver.empty? ? nil : ver)
+    dep.require_block = blk
+    
     existing = Merb::BootLoader::Dependencies.dependencies.find { |d| d.name == dep.name }
     if existing
       index = Merb::BootLoader::Dependencies.dependencies.index(existing)
@@ -31,19 +39,23 @@ module Kernel
   # If that has already happened, the gem will be activated
   # immediately, but it will still be registered.
   # 
-  # @param name<String> The name of the gem to load.
-  # @param *ver<Gem::Requirement, Gem::Version, Array, #to_str>
+  # ==== Parameters
+  # name<String> The name of the gem to load.
+  # *ver<Gem::Requirement, Gem::Version, Array, #to_str>
   #   Version requirements to be passed to Gem::Dependency.new.
   #   If the last argument is a Hash, extract the :immediate option,
   #   forcing a dependency to load immediately.
   #
-  # @return <Gem::Dependency> The dependency information.
-  def dependency(name, *ver)
+  # ==== Returns
+  # Gem::Dependency:: The dependency information.
+  #
+  # @api public
+  def dependency(name, *ver, &blk)
     immediate = ver.last.is_a?(Hash) && ver.pop[:immediate]
     if immediate || Merb::BootLoader.finished?(Merb::BootLoader::Dependencies)
-      load_dependency(name, *ver)
+      load_dependency(name, *ver, &blk)
     else
-      track_dependency(name, *ver)
+      track_dependency(name, *ver, &blk)
     end
   end
 
@@ -63,20 +75,38 @@ module Kernel
   #   as a library.
   #
   # @return <Gem::Dependency> The dependency information.
-  def load_dependency(name, *ver)
+  #
+  # @api private
+  def load_dependency(name, *ver, &blk)
     dep = name.is_a?(Gem::Dependency) ? name : track_dependency(name, *ver)
     gem(dep)
-  rescue Gem::LoadError
+  rescue Gem::LoadError => e
+    Merb.fatal! "The gem #{name}, #{ver.inspect} was not found", e
   ensure
-    require dep.name
-    Merb.logger.info!("loading gem '#{dep.name}' ...")
+    if block = blk || dep.require_block
+      block.call
+    else
+      begin
+        require dep.name
+      rescue LoadError => e
+        Merb.fatal! "The file #{dep.name} was not found", e
+      end
+    end
+    Merb.logger.verbose!("loading gem '#{dep.name}' ...")
     return dep # ensure needs explicit return
   end
 
   # Loads both gem and library dependencies that are passed in as arguments.
   # Execution is deferred to the Merb::BootLoader::Dependencies.run during bootup.
   #
-  # @param *args<String, Hash, Array> The dependencies to load.
+  # ==== Parameters
+  # *args<String, Hash, Array> The dependencies to load.
+  #
+  # ==== Returns
+  # Array[(Gem::Dependency, Array[Gem::Dependency])]:: Gem::Dependencies for the
+  #   dependencies specified in args.
+  #
+  # @api public
   def dependencies(*args)
     args.map do |arg|
       case arg
@@ -101,6 +131,8 @@ module Kernel
   # @example dependencies "RedCloth"                 # Loads the the RedCloth gem
   # @example dependencies "RedCloth", "merb_helpers" # Loads RedCloth and merb_helpers
   # @example dependencies "RedCloth" => "3.0"        # Loads RedCloth 3.0
+  #
+  # @api private
   def load_dependencies(*args)
     args.map do |arg|
       case arg
@@ -115,7 +147,12 @@ module Kernel
   #
   # @param library<to_s> The library to attempt to include.
   # @param message<String> The error to add to the log upon failure. Defaults to nil.
+  #
+  # @api private
+  # @deprecated
   def rescue_require(library, message = nil)
+    Merb.logger.warn("Deprecation warning: rescue_require is deprecated")
+    sleep 2.0
     require library
   rescue LoadError, RuntimeError
     Merb.logger.error!(message) if message
@@ -125,17 +162,22 @@ module Kernel
   # Mapper) you wish to use. Currently Merb has plugins to support
   # ActiveRecord, DataMapper, and Sequel.
   #
-  # @param orm<Symbol> The ORM to use.
+  # ==== Parameters
+  # orm<Symbol>:: The ORM to use.
   #
-  # @example
+  # ==== Returns
+  # nil
+  #
+  # ==== Example
   #   use_orm :datamapper
   #
   #   # This will use the DataMapper generator for your ORM
   #   $ merb-gen model ActivityEvent
   #
-  # @note
+  # ==== Notes
   #   If for some reason this is called more than once, latter
   #   call takes over other.
+  #
   # @api public
   def use_orm(orm)
     begin
@@ -146,37 +188,53 @@ module Kernel
       Merb.logger.warn!("The #{orm_plugin} gem was not found.  You may need to install it.")
       raise e
     end
+    nil
   end
 
   # Used in Merb.root/config/init.rb to tell Merb which testing framework to
   # use. Currently Merb has plugins to support RSpec and Test::Unit.
   #
-  # @param test_framework<Symbol>
+  # ==== Parameters
+  # test_framework<Symbol>::
   #   The test framework to use. Currently only supports :rspec and :test_unit.
   #
-  # @example
+  # ==== Returns
+  # nil
+  #
+  # ==== Example
   #   use_test :rspec
   #
   #   # This will now use the RSpec generator for tests
   #   $ merb-gen model ActivityEvent
+  #
   # @api public
-  def use_test(test_framework, *test_dependencies)
+  def use_testing_framework(test_framework, *test_dependencies)
     Merb.test_framework = test_framework
     
     Kernel.dependencies test_dependencies if Merb.env == "test" || Merb.env.nil?
+    nil
+  end
+
+  def use_test(*args)
+    use_testing_framework(*args)
   end
   
   # Used in Merb.root/config/init.rb to tell Merb which template engine to
   # prefer.
   #
-  # @param template_engine<Symbol>
+  # ==== Parameters
+  # template_engine<Symbol>
   #   The template engine to use.
   #
-  # @example
+  # ==== Returns
+  # nil
+  #
+  # ==== Example
   #   use_template_engine :haml
   #
   #   # This will now use haml templates in generators where available.
   #   $ merb-gen resource_controller Project 
+  #
   # @api public
   def use_template_engine(template_engine)
     Merb.template_engine = template_engine
@@ -189,11 +247,14 @@ module Kernel
       end
       Kernel.dependency(template_engine_plugin)
     end
+    
+    nil
   rescue LoadError => e
     Merb.logger.warn!("The #{template_engine_plugin} gem was not found.  You may need to install it.")
     raise e
   end
 
+
   # @param i<Fixnum> The caller number. Defaults to 1.
   #
   # @return <Array[Array]> The file, line and method of the caller.
@@ -201,6 +262,8 @@ module Kernel
   # @example
   #   __caller_info__(1)
   #     # => ['/usr/lib/ruby/1.8/irb/workspace.rb', '52', 'irb_binding']
+  #
+  # @api private
   def __caller_info__(i = 1)
     file, line, meth = caller[i].scan(/(.*?):(\d+):in `(.*?)'/).first
   end
@@ -224,6 +287,8 @@ module Kernel
   #       [ 123, "      DEBUGGER__.waiting.push Thread.current",      false ],
   #       [ 124, "      @suspend_next = false",                       false ]
   #     ]
+  #
+  # @api private
   def __caller_lines__(file, line, size = 4)
     line = line.to_i
     if file =~ /\(erubis\)/
@@ -241,26 +306,6 @@ module Kernel
         yield index + line - size, str.chomp
       end
     end
-    # 
-    # lines = File.readlines(file)
-    # current = line.to_i - 1
-    # 
-    # first = current - size
-    # first = first < 0 ? 0 : first
-    # 
-    # last = current + size
-    # last = last > lines.size ? lines.size : last
-    # 
-    # log = lines[first..last]
-    # 
-    # area = []
-    # 
-    # log.each_with_index do |line, index|
-    #   index = index + first + 1
-    #   area << [index, line.chomp, index == current + 1]
-    # end
-    # 
-    # area
   end
 
   # Takes a block, profiles the results of running the block
@@ -288,6 +333,8 @@ module Kernel
   #   Assuming that the total time taken for #puts calls was less than 5% of the
   #   total time to run, #puts won't appear in the profile report.
   #   The code block will be run 30 times in the example above.
+  #
+  # @api private
   def __profile__(name, min=1, iter=100)
     require 'ruby-prof' unless defined?(RubyProf)
     return_result = ''
@@ -313,6 +360,8 @@ module Kernel
   #     opts = extract_options_from_args!(args) || {}
   #     # [...]
   #   end
+  #
+  # @api public
   def extract_options_from_args!(args)
     args.pop if Hash === args.last
   end
@@ -325,6 +374,8 @@ module Kernel
   #
   # @raise <ArgumentError>
   #   An object failed to quack like a condition.
+  #
+  # @api public
   def enforce!(opts = {})
     opts.each do |k,v|
       raise ArgumentError, "#{k.inspect} doesn't quack like #{v.inspect}" unless k.quacks_like?(v)

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

@@ -4,15 +4,19 @@ module Merb
   class Dispatcher
     class << self
       include Merb::ControllerExceptions
-    
+      
       attr_accessor :use_mutex
       
       @@work_queue = Queue.new
-    
+      
+      # ==== Returns
+      # Queue:: the current queue of dispatch jobs.
+      # 
+      # @api private
       def work_queue 
         @@work_queue
       end  
-    
+      
       Merb::Dispatcher.use_mutex = ::Merb::Config[:use_mutex]
       
       # Dispatch the rack environment. ControllerExceptions are rescued here
@@ -25,9 +29,11 @@ module Merb
       # ==== Returns
       # Merb::Controller::
       #   The Merb::Controller that was dispatched to
+      # 
+      # @api private
       def handle(request)
         request.handle
-      end      
+      end
     end
   end
   
@@ -36,12 +42,18 @@ module Merb
     
     @@mutex = Mutex.new
     
+    # Handles request routing and action dispatch.
+    # 
+    # ==== Returns
+    # Merb::Controller:: the controller that handled the action dispatch.
+    # 
+    # @api private
     def handle
       start = Time.now
       Merb.logger.info "Started request handling: #{start.to_s}"
-  
+      
       find_route!
-      return redirect if redirects?
+      return rack_response if handled?
       
       klass = controller
       Merb.logger.debug("Routed to: #{params.inspect}")
@@ -57,42 +69,14 @@ module Merb
       if klass.abstract?
         raise NotFound, "The '#{klass}' controller has no public actions"
       end
-    
+      
       controller = dispatch_action(klass, params[:action])
       controller._benchmarks[:dispatch_time] = Time.now - start
       Merb.logger.info controller._benchmarks.inspect
       Merb.logger.flush
-      controller
+      controller.rack_response
     rescue Object => exception
-      dispatch_exception(exception)
-    end
-    
-    # Set up a faux controller to do redirection from the router 
-    #
-    # ==== Parameters
-    # request<Merb::Request>::
-    #   The Merb::Request object that was created in #handle
-    # status<Integer>::
-    #   The status code to return with the controller
-    # url<String>::
-    #   The URL to return
-    #
-    # ==== Example
-    # r.match("/my/old/crusty/url").redirect("http://example.com/index.html")
-    #
-    # ==== Returns
-    # Merb::Controller::
-    #   Merb::Controller set with redirect headers and a 301/302 status
-    def redirect
-      status, url = redirect_status, redirect_url
-      controller = Merb::Controller.new(self, status)
-    
-      Merb.logger.info("Dispatcher redirecting to: #{url} (#{status})")
-      Merb.logger.flush
-      
-      controller.headers['Location'] = url
-      controller.body = "<html><body>You are being <a href=\"#{url}\">redirected</a>.</body></html>"
-      controller
+      dispatch_exception(exception).rack_response
     end
     
     private
@@ -101,13 +85,13 @@ module Merb
     # ==== Parameters
     # klass<Merb::Controller>:: The controller class to dispatch to.
     # action<Symbol>:: The action to dispatch.
-    # request<Merb::Request>::
-    #   The Merb::Request object that was created in #handle
     # status<Integer>:: The status code to respond with.
     #
     # ==== Returns
     # Merb::Controller::
     #   The Merb::Controller that was dispatched to.
+    # 
+    # @api private
     def dispatch_action(klass, action, status=200)
       # build controller
       controller = klass.new(self, status)
@@ -129,8 +113,6 @@ module Merb
     # StandardError is caught in standard_error).
     #
     # ==== Parameters
-    # request<Merb::Request>:: 
-    #   The request object associated with the failed request.
     # exception<Object>::
     #   The exception object that was created when trying to dispatch the
     #   original controller.
@@ -138,6 +120,8 @@ module Merb
     # ==== Returns
     # Exceptions::
     #   The Merb::Controller that was dispatched to. 
+    # 
+    # @api private
     def dispatch_exception(exception)
       if(exception.is_a?(Merb::ControllerExceptions::Base) &&
          !exception.is_a?(Merb::ControllerExceptions::ServerError))
@@ -145,12 +129,12 @@ module Merb
       else
         Merb.logger.error(Merb.exception(exception))
       end
-
+      
       self.exceptions = [exception]
-
+      
       begin
         e = exceptions.first
-
+        
         if action_name = e.action_name
           dispatch_action(Exceptions, action_name, e.class.status)
         else
@@ -162,7 +146,7 @@ module Merb
         else
           Merb.logger.error("Dispatching #{e.class} raised another error.")
           Merb.logger.error(Merb.exception(dispatch_issue))
-
+          
           exceptions.unshift dispatch_issue
           retry
         end