joe-merb-core 0.9.8

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

@@ -0,0 +1,302 @@
+class Exception
+  def action_name() self.class.action_name end
+  
+  def same?(other)
+    self.class == other.class &&
+    self.message == other.message &&
+    self.backtrace == other.backtrace
+  end
+  
+  def self.action_name
+    if self == Exception
+      return nil unless Object.const_defined?(:Exceptions) && 
+        Exceptions.method_defined?(:exception)
+    end
+    name = self.to_s.split('::').last.snake_case
+    Object.const_defined?(:Exceptions) && 
+      Exceptions.method_defined?(name) ? name : superclass.action_name
+  end
+  
+  def self.status
+    500
+  end
+end
+
+module Merb
+  # ControllerExceptions are a way of simplifying controller code by placing
+  # exception logic back into the MVC pattern.
+  #
+  # When a ControllerException is raised within your application merb will
+  # attempt to re-route the request to your Exceptions controller to render
+  # the error in a friendly manor.
+  #
+  # For example you might have an action in your app that raises NotFound
+  # if a resource was not available
+  #
+
+  #   def show
+  #     product = Product.find(params[:id])
+  #     raise NotFound if product.nil?
+  #     [...]
+  #   end
+  #
+  # This would halt execution of your action and re-route it over to your
+  # Exceptions controller which might look something like:
+  #
+  # class Exceptions < Application
+
+  #   def not_found
+  #     render :layout => :none
+  #   end
+  # end
+  #
+  # As usual, the not_found action will look for a template in
+  #   app/views/exceptions/not_found.html.erb
+  #
+  # Note: All standard ControllerExceptions have an HTTP status code associated 
+  # with them which is sent to the browser when the action is rendered.
+  #
+  # Note: If you do not specifiy how to handle raised ControllerExceptions 
+  # or an unhandlable exception occurs within your customised exception action
+  # then they will be rendered using the built-in error template.
+  # In development mode this "built in" template will show stack-traces for
+  # any of the ServerError family of exceptions (you can force the stack-trace
+  # to display in production mode using the :exception_details config option in 
+  # merb.yml)
+  #
+  #
+  # ==== Internal Exceptions 
+  #
+  # Any other rogue errors (not ControllerExceptions) that occur during the 
+  # execution of your app will be converted into the ControllerException 
+  # InternalServerError. And like all other exceptions, the ControllerExceptions  
+  # can be caught on your Exceptions controller.
+  #
+  # InternalServerErrors return status 500, a common use for customizing this
+  # action might be to send emails to the development team, warning that their
+  # application has exploded. Mock example:
+  #
+
+  #   def internal_server_error
+  #     MySpecialMailer.deliver(
+  #       "team@cowboys.com", 
+  #       "Exception occured at #{Time.now}", 
+  #       params[:exception])
+  #     render 'Something is wrong, but the team is on it!'
+  #   end
+  #
+  # Note: The special param[:exception] is available in all Exception actions 
+  # and contains the ControllerException that was raised (this is handy if
+  # you want to display the associated message or display more detailed info)
+  #
+  #
+  # ==== Extending ControllerExceptions
+  #
+  # To extend the use of the ControllerExceptions one may extend any of the 
+  # HTTPError classes.
+  #
+  # As an example we can create an exception called AdminAccessRequired.
+  #
+  #   class AdminAccessRequired < Merb::ControllerExceptions::Unauthorized; end
+  #
+  # Add the required action to our Exceptions controller
+  #
+  #   class Exceptions < Application
+
+  #     def admin_access_required
+  #       render
+  #     end
+  #   end
+  #
+  # In app/views/exceptions/admin_access_required.rhtml
+  # 
+  #   <h1>You're not an administrator!</h1>
+  #   <p>You tried to access <%= @tried_to_access %> but that URL is 
+  #   restricted to administrators.</p>
+  #
+  module ControllerExceptions
+    
+    # Mapping of status code names to their numeric value.
+    STATUS_CODES = {}
+
+    class Base < StandardError #:doc:
+
+      # === Returns
+      # Integer:: The status-code of the error.
+      def status; self.class.status; end
+      alias :to_i :status
+
+      class << self
+
+        # Get the actual status-code for an Exception class.
+        #
+        # As usual, this can come from a constant upwards in
+        # the inheritance chain.
+        #
+        # ==== Returns
+        # Fixnum:: The status code of this exception.
+        def status
+          const_get(:STATUS) rescue 0
+        end
+        alias :to_i :status
+        
+        # Set the actual status-code for an Exception class.
+        #
+        # If possible, set the STATUS constant, and update
+        # any previously registered (inherited) status-code.
+        #
+        # ==== Parameters
+        # num<~to_i>:: The status code
+        def status=(num)
+          unless self.status?
+            register_status_code(self, num)
+            self.const_set(:STATUS, num.to_i)
+          end
+        end
+      
+        # See if a status-code has been defined (on self explicitly).
+        #
+        # ==== Returns
+        # Boolean:: Whether the a status code has been set
+        def status?
+          self.const_defined?(:STATUS)
+        end
+      
+        # Registers any subclasses with status codes for easy lookup by
+        # set_status in Merb::Controller.
+        #
+        # Inheritance ensures this method gets inherited by any subclasses, so
+        # it goes all the way down the chain of inheritance.
+        #
+        # ==== Parameters
+        # 
+        # subclass<Merb::ControllerExceptions::Base>::
+        #   The Exception class that is inheriting from Merb::ControllerExceptions::Base
+        def inherited(subclass)
+          # don't set the constant yet - any class methods will be called after self.inherited
+          # unless self.status = ... is set explicitly, the status code will be inherited
+          register_status_code(subclass, self.status) if self.status?
+        end
+        
+        private
+        
+        # Register the status-code for an Exception class.
+        #
+        # ==== Parameters
+        # num<~to_i>:: The status code
+        def register_status_code(klass, code)
+          name = self.to_s.split('::').last.snake_case
+          STATUS_CODES[name.to_sym] = code.to_i
+        end
+        
+      end
+    end
+
+    class Informational                 < Merb::ControllerExceptions::Base; end
+
+      class Continue                    < Merb::ControllerExceptions::Informational; self.status = 100; end
+
+      class SwitchingProtocols          < Merb::ControllerExceptions::Informational; self.status = 101; end
+
+    class Successful                    < Merb::ControllerExceptions::Base; end
+
+      class OK                          < Merb::ControllerExceptions::Successful; self.status = 200; end
+
+      class Created                     < Merb::ControllerExceptions::Successful; self.status = 201; end
+
+      class Accepted                    < Merb::ControllerExceptions::Successful; self.status = 202; end
+
+      class NonAuthoritativeInformation < Merb::ControllerExceptions::Successful; self.status = 203; end
+
+      class NoContent                   < Merb::ControllerExceptions::Successful; self.status = 204; end
+
+      class ResetContent                < Merb::ControllerExceptions::Successful; self.status = 205; end
+
+      class PartialContent              < Merb::ControllerExceptions::Successful; self.status = 206; end
+
+    class Redirection                   < Merb::ControllerExceptions::Base; end
+
+      class MultipleChoices             < Merb::ControllerExceptions::Redirection; self.status = 300; end
+
+      class MovedPermanently            < Merb::ControllerExceptions::Redirection; self.status = 301; end
+
+      class MovedTemporarily            < Merb::ControllerExceptions::Redirection; self.status = 302; end
+
+      class SeeOther                    < Merb::ControllerExceptions::Redirection; self.status = 303; end
+
+      class NotModified                 < Merb::ControllerExceptions::Redirection; self.status = 304; end
+
+      class UseProxy                    < Merb::ControllerExceptions::Redirection; self.status = 305; end
+
+      class TemporaryRedirect           < Merb::ControllerExceptions::Redirection; self.status = 307; end
+
+    class ClientError                   < Merb::ControllerExceptions::Base; end
+
+      class BadRequest                  < Merb::ControllerExceptions::ClientError; self.status = 400; end
+
+      class MultiPartParseError         < Merb::ControllerExceptions::BadRequest; end
+
+      class Unauthorized                < Merb::ControllerExceptions::ClientError; self.status = 401; end
+
+      class PaymentRequired             < Merb::ControllerExceptions::ClientError; self.status = 402; end
+
+      class Forbidden                   < Merb::ControllerExceptions::ClientError; self.status = 403; end
+
+      class NotFound                    < Merb::ControllerExceptions::ClientError; self.status = 404; end
+
+      class ActionNotFound              < Merb::ControllerExceptions::NotFound; end
+
+      class TemplateNotFound            < Merb::ControllerExceptions::NotFound; end
+
+      class LayoutNotFound              < Merb::ControllerExceptions::NotFound; end
+
+      class MethodNotAllowed            < Merb::ControllerExceptions::ClientError; self.status = 405; end
+
+      class NotAcceptable               < Merb::ControllerExceptions::ClientError; self.status = 406; end
+
+      class ProxyAuthenticationRequired < Merb::ControllerExceptions::ClientError; self.status = 407; end
+
+      class RequestTimeout              < Merb::ControllerExceptions::ClientError; self.status = 408; end
+
+      class Conflict                    < Merb::ControllerExceptions::ClientError; self.status = 409; end
+
+      class Gone                        < Merb::ControllerExceptions::ClientError; self.status = 410; end
+
+      class LengthRequired              < Merb::ControllerExceptions::ClientError; self.status = 411; end
+
+      class PreconditionFailed          < Merb::ControllerExceptions::ClientError; self.status = 412; end
+
+      class RequestEntityTooLarge       < Merb::ControllerExceptions::ClientError; self.status = 413; end
+
+      class RequestURITooLarge          < Merb::ControllerExceptions::ClientError; self.status = 414; end
+
+      class UnsupportedMediaType        < Merb::ControllerExceptions::ClientError; self.status = 415; end
+
+      class RequestRangeNotSatisfiable  < Merb::ControllerExceptions::ClientError; self.status = 416; end
+
+      class ExpectationFailed           < Merb::ControllerExceptions::ClientError; self.status = 417; end
+
+    class ServerError                   < Merb::ControllerExceptions::Base; end
+
+      class InternalServerError         < Merb::ControllerExceptions::ServerError; self.status = 500; end
+
+      class NotImplemented              < Merb::ControllerExceptions::ServerError; self.status = 501; end
+
+      class BadGateway                  < Merb::ControllerExceptions::ServerError; self.status = 502; end
+
+      class ServiceUnavailable          < Merb::ControllerExceptions::ServerError; self.status = 503; end
+
+      class GatewayTimeout              < Merb::ControllerExceptions::ServerError; self.status = 504; end
+
+      class HTTPVersionNotSupported     < Merb::ControllerExceptions::ServerError; self.status = 505; end
+  end
+  
+  # Required to show exceptions in the log file
+  #
+  # e<Exception>:: The exception that a message is being generated for
+  def self.exception(e)
+    "#{ e.message } - (#{ e.class })\n" <<  
+    "#{(e.backtrace or []).join("\n")}" 
+  end
+
+end

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

@@ -0,0 +1,283 @@
+class Merb::Controller < Merb::AbstractController
+
+  class_inheritable_accessor :_hidden_actions, :_shown_actions
+
+  self._hidden_actions ||= []
+  self._shown_actions  ||= []
+
+  cattr_accessor :_subclasses
+  self._subclasses = Set.new
+
+  def self.subclasses_list() _subclasses end
+
+  include Merb::ResponderMixin
+  include Merb::ControllerMixin
+  include Merb::AuthenticationMixin
+  include Merb::ConditionalGetMixin
+
+  class << self
+
+    # ==== Parameters
+    # klass<Merb::Controller>::
+    #   The Merb::Controller inheriting from the base class.
+    def inherited(klass)
+      _subclasses << klass.to_s
+      super
+      klass._template_root = Merb.dir_for(:view) unless self._template_root
+    end
+
+    # Hide each of the given methods from being callable as actions.
+    #
+    # ==== Parameters
+    # *names<~to-s>:: Actions that should be added to the list.
+    #
+    # ==== Returns
+    # Array[String]::
+    #   An array of actions that should not be possible to dispatch to.
+    #
+    #---
+    # @public
+    def hide_action(*names)
+      self._hidden_actions = self._hidden_actions | names.map { |n| n.to_s }
+    end
+
+    # Makes each of the given methods being callable as actions. You can use
+    # this to make methods included from modules callable as actions.
+    #
+    # ==== Parameters
+    # *names<~to-s>:: Actions that should be added to the list.
+    #
+    # ==== Returns
+    # Array[String]::
+    #   An array of actions that should be dispatched to even if they would not
+    #   otherwise be.
+    #
+    # ==== Example
+    #   module Foo
+    #     def self.included(base)
+    #       base.show_action(:foo)
+    #     end
+    #
+    #     def foo
+    #       # some actiony stuff
+    #     end
+    #
+    #     def foo_helper
+    #       # this should not be an action
+    #     end
+    #   end
+    #
+    #---
+    # @public
+    def show_action(*names)
+      self._shown_actions = self._shown_actions | names.map {|n| n.to_s}
+    end
+
+    # The list of actions that are callable, after taking defaults,
+    # _hidden_actions and _shown_actions into consideration. It is calculated
+    # once, the first time an action is dispatched for this controller.
+    #
+    # ==== Returns
+    # SimpleSet[String]:: A set of actions that should be callable.
+    def callable_actions
+      @callable_actions ||= Extlib::SimpleSet.new(_callable_methods)
+    end
+
+    # This is a stub method so plugins can implement param filtering if they want.
+    #
+    # ==== Parameters
+    # params<Hash{Symbol => String}>:: A list of params
+    #
+    # ==== Returns
+    # Hash{Symbol => String}:: A new list of params, filtered as desired
+    #---
+    # @semipublic
+    def _filter_params(params)
+      params
+    end
+
+    private
+
+    # All methods that are callable as actions.
+    #
+    # ==== Returns
+    # Array:: A list of method names that are also actions
+    def _callable_methods
+      callables = []
+      klass = self
+      begin
+        callables << (klass.public_instance_methods(false) + klass._shown_actions) - klass._hidden_actions
+        klass = klass.superclass
+      end until klass == Merb::AbstractController || klass == Object
+      callables.flatten.reject{|action| action =~ /^_.*/}
+    end
+
+  end # class << self
+
+  # The location to look for a template for a particular controller, context,
+  # and mime-type. This is overridden from AbstractController, which defines a
+  # version of this that does not involve mime-types.
+  #
+  # ==== Parameters
+  # context<~to_s>:: The name of the action or template basename that will be rendered.
+  # type<~to_s>::
+  #    The mime-type of the template that will be rendered. Defaults to nil.
+  # controller<~to_s>::
+  #   The name of the controller that will be rendered. Defaults to
+  #   controller_name.
+  #
+  # ==== Notes
+  # By default, this renders ":controller/:action.:type". To change this,
+  # override it in your application class or in individual controllers.
+  #
+  #---
+  # @public
+  def _template_location(context, type, controller)
+    _conditionally_append_extension(controller ? "#{controller}/#{context}" : "#{context}", type)
+  end
+
+  # The location to look for a template and mime-type. This is overridden
+  # from AbstractController, which defines a version of this that does not
+  # involve mime-types.
+  #
+  # ==== Parameters
+  # template<String>::
+  #    The absolute path to a template - without mime and template extension.
+  #    The mime-type extension is optional - it will be appended from the
+  #    current content type if it hasn't been added already.
+  # type<~to_s>::
+  #    The mime-type of the template that will be rendered. Defaults to nil.
+  #
+  # @public
+  def _absolute_template_location(template, type)
+    _conditionally_append_extension(template, type)
+  end
+
+  # Build a new controller.
+  #
+  # Sets the variables that came in through the dispatch as available to
+  # the controller.
+  #
+  # ==== Parameters
+  # request<Merb::Request>:: The Merb::Request that came in from Rack.
+  # status<Integer>:: An integer code for the status. Defaults to 200.
+  # headers<Hash{header => value}>::
+  #   A hash of headers to start the controller with. These headers can be
+  #   overridden later by the #headers method.
+  #---
+  # @semipublic
+  def initialize(request, status=200, headers={'Content-Type' => 'text/html; charset=utf-8'})
+    super()
+    @request, @_status, @headers = request, status, headers
+  end
+
+  # Dispatch the action.
+  #
+  # ==== Parameters
+  # action<~to_s>:: An action to dispatch to. Defaults to :index.
+  #
+  # ==== Returns
+  # String:: The string sent to the logger for time spent.
+  #
+  # ==== Raises
+  # ActionNotFound:: The requested action was not found in class.
+  #---
+  # @semipublic
+  def _dispatch(action=:index)
+    Merb.logger.info("Params: #{self.class._filter_params(request.params).inspect}")
+    start = Time.now
+    if self.class.callable_actions.include?(action.to_s)
+      super(action)
+    else
+      raise ActionNotFound, "Action '#{action}' was not found in #{self.class}"
+    end
+    @_benchmarks[:action_time] = Time.now - start
+    self
+  end
+
+  attr_reader :request, :headers
+
+  def status
+    @_status
+  end
+
+  # Set the response status code.
+  #
+  # ==== Parameters
+  # s<Fixnum, Symbol>:: A status-code or named http-status
+  def status=(s)
+    if s.is_a?(Symbol) && STATUS_CODES.key?(s)
+      @_status = STATUS_CODES[s]
+    elsif s.is_a?(Fixnum)
+      @_status = s
+    else
+      raise ArgumentError, "Status should be of type Fixnum or Symbol, was #{s.class}"
+    end
+  end
+
+  # ==== Returns
+  # Hash:: The parameters from the request object
+  def params()  request.params  end
+    
+  # ==== Parameters
+  # name<~to_sym, Hash>:: The name of the URL to generate.
+  # rparams<Hash>:: Parameters for the route generation.
+  #
+  # ==== Returns
+  # String:: The generated URL.
+  #
+  # ==== Alternatives
+  # If a hash is used as the first argument, a default route will be
+  # generated based on it and rparams.
+  # ====
+  # TODO: Update this documentation
+  def url(name, *args)
+    args << params
+    Merb::Router.url(name, *args)
+  end
+
+  alias_method :relative_url, :url
+  
+  def absolute_url(*args)
+    options  = extract_options_from_args!(args) || {}
+    options[:protocol] ||= request.protocol
+    options[:host] ||= request.host
+    args << options
+    super(args.first, *args[1..-1])
+  end
+
+  # The results of the controller's render, to be returned to Rack.
+  #
+  # ==== Returns
+  # Array[Integer, Hash, String]::
+  #   The controller's status code, headers, and body
+  def rack_response
+    [status, headers, Merb::Rack::StreamWrapper.new(body)]
+  end
+
+  # Sets a controller to be "abstract" 
+  # This controller will not be able to be routed to
+  # and is used for super classing only
+  def self.abstract!
+    @_abstract = true
+  end
+  
+  # Asks a controller if it is abstract
+  #
+  # === Returns
+  # Boolean
+  #  true if the controller has been set as abstract
+  def self.abstract?
+    !!@_abstract 
+  end
+
+  # Hide any methods that may have been exposed as actions before.
+  hide_action(*_callable_methods)
+
+  private
+
+  # If not already added, add the proper mime extension to the template path.
+  def _conditionally_append_extension(template, type)
+    type && !template.match(/\.#{type.to_s.escape_regexp}$/) ? "#{template}.#{type}" : template
+  end
+end