lotus-controller 0.1.0 → 0.2.0

data/lib/lotus/action.rb

@@ -1,3 +1,4 @@
+require 'lotus/action/configurable'
 require 'lotus/action/rack'
 require 'lotus/action/mime'
 require 'lotus/action/redirect'
@@ -22,8 +23,27 @@ module Lotus
   #     end
   #   end
   module Action
+    # Override Ruby's hook for modules.
+    # It includes basic Lotus::Action modules to the given class.
+    #
+    # @param base [Class] the target action
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included
+    #
+    # @see Lotus::Action::Configurable
+    # @see Lotus::Action::Rack
+    # @see Lotus::Action::Mime
+    # @see Lotus::Action::Redirect
+    # @see Lotus::Action::Exposable
+    # @see Lotus::Action::Throwable
+    # @see Lotus::Action::Callbacks
+    # @see Lotus::Action::Callable
     def self.included(base)
       base.class_eval do
+        include Configurable
         include Rack
         include Mime
         include Redirect

data/lib/lotus/action/callbacks.rb

@@ -9,6 +9,15 @@ module Lotus
     # @see Lotus::Action::ClassMethods#before
     # @see Lotus::Action::ClassMethods#after
     module Callbacks
+      # Override Ruby's hook for modules.
+      # It includes callbacks logic
+      #
+      # @param base [Class] the target action
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included
       def self.included(base)
         base.class_eval do
           extend  ClassMethods
@@ -17,6 +26,15 @@ module Lotus
       end
 
       module ClassMethods
+        # Override Ruby's hook for modules.
+        # It includes callbacks logic
+        #
+        # @param base [Class] the target action
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-extended
         def self.extended(base)
           base.class_eval do
             include Utils::ClassAttribute
@@ -90,7 +108,7 @@ module Lotus
         #   # 2. set the article
         #   # 3. #call
         def before(*callbacks, &blk)
-          before_callbacks.add *callbacks, &blk
+          before_callbacks.add(*callbacks, &blk)
         end
 
         # Define a callback for an Action.
@@ -109,7 +127,7 @@ module Lotus
         #
         # @see Lotus::Action::Callbacks::ClassMethods#before
         def after(*callbacks, &blk)
-          after_callbacks.add *callbacks, &blk
+          after_callbacks.add(*callbacks, &blk)
         end
       end
 

data/lib/lotus/action/configurable.rb

@@ -0,0 +1,48 @@
+require 'lotus/utils/class_attribute'
+
+module Lotus
+  module Action
+    # Configuration API
+    #
+    # @since 0.2.0
+    #
+    # @see Lotus::Controller::Configuration
+    module Configurable
+      # Override Ruby's hook for modules.
+      # It includes configuration logic
+      #
+      # @param base [Class] the target action
+      #
+      # @since 0.2.0
+      # @api private
+      #
+      # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included
+      #
+      # @example
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #   end
+      #
+      #   Show.configuration
+      def self.included(base)
+        config = Lotus::Controller::Configuration.for(base)
+
+        base.class_eval do
+          include Utils::ClassAttribute
+
+          class_attribute :configuration
+          self.configuration = config
+        end
+
+        config.load!(base)
+      end
+
+      protected
+      def configuration
+        self.class.configuration
+      end
+    end
+  end
+end

data/lib/lotus/action/cookie_jar.rb

@@ -9,20 +9,23 @@ module Lotus
     # @since 0.1.0
     #
     # @see Lotus::Action::Cookies#cookies
-    class CookieJar < Utils::Hash
+    class CookieJar
       # The key that returns raw cookies from the Rack env
       #
       # @since 0.1.0
+      # @api private
       HTTP_HEADER       = 'HTTP_COOKIE'.freeze
 
       # The key used by Rack to set the cookies as an Hash in the env
       #
       # @since 0.1.0
+      # @api private
       COOKIE_HASH_KEY   = 'rack.request.cookie_hash'.freeze
 
       # The key used by Rack to set the cookies as a String in the env
       #
       # @since 0.1.0
+      # @api private
       COOKIE_STRING_KEY = 'rack.request.cookie_string'.freeze
 
       # Initialize the CookieJar
@@ -35,9 +38,7 @@ module Lotus
       # @since 0.1.0
       def initialize(env, headers)
         @_headers = headers
-
-        super(extract(env))
-        symbolize!
+        @cookies  = Utils::Hash.new(extract(env)).symbolize!
       end
 
       # Finalize itself, by setting the proper headers to add and remove
@@ -49,7 +50,30 @@ module Lotus
       #
       # @see Lotus::Action::Cookies#finish
       def finish
-        each {|k,v| v.nil? ? delete_cookie(k) : set_cookie(k, v) }
+        @cookies.each {|k,v| v.nil? ? delete_cookie(k) : set_cookie(k, v) }
+      end
+
+      # Returns the object associated with the given key
+      #
+      # @param key [Symbol] the key
+      #
+      # @return [Object,nil] return the associated object, if found
+      #
+      # @since 0.2.0
+      def [](key)
+        @cookies[key]
+      end
+
+      # Associate the given value with the given key and store them
+      #
+      # @param key [Symbol] the key
+      # @param value [Object] the value
+      #
+      # @return [void]
+      #
+      # @since 0.2.0
+      def []=(key, value)
+        @cookies[key] = value
       end
 
       private

data/lib/lotus/action/exposable.rb

@@ -6,10 +6,17 @@ module Lotus
     #
     # @see Lotus::Action::Exposable::ClassMethods#expose
     module Exposable
+      # Override Ruby's hook for modules.
+      # It includes exposures logic
+      #
+      # @param base [Class] the target action
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included
       def self.included(base)
-        base.class_eval do
-          extend ClassMethods
-        end
+        base.extend ClassMethods
       end
 
       module ClassMethods
@@ -46,8 +53,8 @@ module Lotus
         #   action.exposures # => { :article => #<Article ...>, :tags => [ ... ] }
         def expose(*names)
           class_eval do
-            attr_reader    *names
-            exposures.push *names
+            attr_reader(   *names)
+            exposures.push(*names)
           end
         end
 

data/lib/lotus/action/mime.rb

@@ -1,3 +1,5 @@
+require 'lotus/utils/kernel'
+
 module Lotus
   module Action
     # Mime type API
@@ -26,21 +28,41 @@ module Lotus
       # @since 0.1.0
       DEFAULT_CONTENT_TYPE = 'application/octet-stream'.freeze
 
+      # Override Ruby's hook for modules.
+      # It includes Mime types logic
+      #
+      # @param base [Class] the target action
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @see http://www.ruby-doc.org/core-2.1.2/Module.html#method-i-included
       def self.included(base)
-        base.class_eval do
-          extend ClassMethods
-        end
+        base.extend ClassMethods
       end
 
       module ClassMethods
+        # @since 0.2.0
+        # @api private
+        def format_to_mime_type(format)
+          configuration.mime_type_for(format) ||
+            ::Rack::Mime.mime_type(".#{ format }", nil) or
+            raise Lotus::Controller::UnknownFormatError.new(format)
+        end
+
         protected
 
         # Restrict the access to the specified mime type symbols.
         #
         # @param mime_types[Array<Symbol>] one or more symbols representing mime type(s)
         #
+        # @raise [Lotus::Controller::UnknownFormatError] if the symbol cannot
+        #   be converted into a mime type
+        #
         # @since 0.1.0
         #
+        # @see Lotus::Controller::Configuration#format
+        #
         # @example
         #   require 'lotus/controller'
         #
@@ -57,19 +79,103 @@ module Lotus
         #   # When called with "text/html"        => 200
         #   # When called with "application/json" => 200
         #   # When called with "application/xml"  => 406
-        def accept(*mime_types)
-          mime_types = mime_types.map do |mt|
-            ::Rack::Mime.mime_type ".#{ mt }"
+        def accept(*formats)
+          mime_types = formats.map do |format|
+            format_to_mime_type(format)
           end
 
           before do
             unless mime_types.find {|mt| accept?(mt) }
-              throw 406
+              halt 406
             end
           end
         end
       end
 
+      # Returns a symbol representation of the content type.
+      #
+      # The framework automatically detects the request mime type, and returns
+      # the corresponding format.
+      #
+      # However, if this value was explicitely set by `#format=`, it will return
+      # that value
+      #
+      # @return [Symbol] a symbol that corresponds to the content type
+      #
+      # @since 0.2.0
+      #
+      # @see Lotus::Action::Mime#format=
+      # @see Lotus::Action::Mime#content_type
+      #
+      # @example Default scenario
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #     end
+      #   end
+      #
+      #   action = Show.new
+      #
+      #   _, headers, _ = action.call({ 'HTTP_ACCEPT' => 'text/html' })
+      #   headers['Content-Type'] # => 'text/html'
+      #   action.format           # => :html
+      #
+      # @example Set value
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #       self.format = :xml
+      #     end
+      #   end
+      #
+      #   action = Show.new
+      #
+      #   _, headers, _ = action.call({ 'HTTP_ACCEPT' => 'text/html' })
+      #   headers['Content-Type'] # => 'application/xml'
+      #   action.format           # => :xml
+      def format
+        @format ||= detect_format
+      end
+
+      # The content type that will be automatically set in the response.
+      #
+      # It prefers, in order:
+      #   * Explicit set value (see #format=)
+      #   * Weighted value from Accept
+      #   * Default content type
+      #
+      # To override the value, use <tt>#format=</tt>
+      #
+      # @return [String] the content type from the request.
+      #
+      # @since 0.1.0
+      #
+      # @see Lotus::Action::Mime#format=
+      # @see Lotus::Configuration#default_format
+      # @see Lotus::Action::Mime#default_content_type
+      # @see Lotus::Action::Mime#DEFAULT_CONTENT_TYPE
+      #
+      # @example
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #       # ...
+      #       content_type # => 'text/html'
+      #     end
+      #   end
+      def content_type
+        @content_type || accepts || default_content_type || DEFAULT_CONTENT_TYPE
+      end
+
       protected
       # Finalize the response by setting the current content type
       #
@@ -82,19 +188,64 @@ module Lotus
         headers.merge! CONTENT_TYPE => content_type
       end
 
-      # Sets the given content type
+      # Sets the given format and corresponding content type.
+      #
+      # The framework detects the `HTTP_ACCEPT` header of the request and sets
+      # the proper `Content-Type` header in the response.
+      # Within this default scenario, `#format` returns a symbol that
+      # corresponds to `#content_type`.
+      # For instance, if a client sends an `HTTP_ACCEPT` with `text/html`,
+      # `#content_type` will return `text/html` and `#format` `:html`.
       #
-      # Lotus::Action sets the proper content type automatically, this method
-      #   is designed to override that value.
+      # However, it's possible to override what the framework have detected.
+      # If a client asks for an `HTTP_ACCEPT` `*/*`, but we want to force the
+      # response to be a `text/html` we can use this method.
+      #
+      # When the format is set, the framework searchs for a corresponding mime
+      # type to be set as the `Content-Type` header of the response.
+      # This lookup is performed first in the configuration, and then in
+      # `Rack::Mime::MIME_TYPES`. If the lookup fails, it raises an error.
+      #
+      # PERFORMANCE: Because `Lotus::Controller::Configuration#formats` is
+      # smaller and looked up first than `Rack::Mime::MIME_TYPES`, we suggest to
+      # configure the most common mime types used by your application, **even
+      # if they are already present in that Rack constant**.
+      #
+      # @param format [#to_sym] the format
       #
-      # @param content_type [String] the content type
       # @return [void]
       #
-      # @since 0.1.0
+      # @raise [TypeError] if the format cannot be coerced into a Symbol
+      # @raise [Lotus::Controller::UnknownFormatError] if the format doesn't
+      #   have a corresponding mime type
       #
+      # @since 0.2.0
+      #
+      # @see Lotus::Action::Mime#format
       # @see Lotus::Action::Mime#content_type
+      # @see Lotus::Controller::Configuration#format
       #
-      # @example
+      # @example Default scenario
+      #   require 'lotus/controller'
+      #
+      #   class Show
+      #     include Lotus::Action
+      #
+      #     def call(params)
+      #     end
+      #   end
+      #
+      #   action = Show.new
+      #
+      #   _, headers, _ = action.call({ 'HTTP_ACCEPT' => '*/*' })
+      #   headers['Content-Type'] # => 'application/octet-stream'
+      #   action.format           # => :all
+      #
+      #   _, headers, _ = action.call({ 'HTTP_ACCEPT' => 'text/html' })
+      #   headers['Content-Type'] # => 'text/html'
+      #   action.format           # => :html
+      #
+      # @example Simple usage
       #   require 'lotus/controller'
       #
       #   class Show
@@ -102,42 +253,54 @@ module Lotus
       #
       #     def call(params)
       #       # ...
-      #       self.content_type = 'application/json'
+      #       self.format = :json
       #     end
       #   end
-      def content_type=(content_type)
-        @content_type = content_type
-      end
-
-      # The content type that will be automatically set in the response.
       #
-      # It prefers, in order:
-      #   * Explicit set value (see #content_type=)
-      #   * Weighted value from Accept
-      #   * Default content type
+      #   action = Show.new
       #
-      # To override the value, use <tt>#content_type=</tt>
+      #   _, headers, _ = action.call({ 'HTTP_ACCEPT' => '*/*' })
+      #   headers['Content-Type'] # => 'application/json'
+      #   action.format           # => :json
       #
-      # @return [String] the content type from the request.
+      # @example Unknown format
+      #   require 'lotus/controller'
       #
-      # @since 0.1.0
+      #   class Show
+      #     include Lotus::Action
       #
-      # @see Lotus::Action::Mime#content_type=
-      # @see Lotus::Action::Mime#DEFAULT_CONTENT_TYPE
+      #     def call(params)
+      #       # ...
+      #       self.format = :unknown
+      #     end
+      #   end
       #
-      # @example
+      #   action = Show.new
+      #   action.call({ 'HTTP_ACCEPT' => '*/*' })
+      #     # => raise Lotus::Controller::UnknownFormatError
+      #
+      # @example Custom mime type/format
       #   require 'lotus/controller'
       #
+      #   Lotus::Controller.configure do
+      #     format :custom, 'application/custom'
+      #   end
+      #
       #   class Show
       #     include Lotus::Action
       #
       #     def call(params)
       #       # ...
-      #       content_type # => 'text/html'
+      #       self.format = :custom
       #     end
       #   end
-      def content_type
-        @content_type || accepts || DEFAULT_CONTENT_TYPE
+      #
+      #   _, headers, _ = action.call({ 'HTTP_ACCEPT' => '*/*' })
+      #   headers['Content-Type'] # => 'application/custom'
+      #   action.format           # => :custom
+      def format=(format)
+        @format       = Utils::Kernel.Symbol(format)
+        @content_type = self.class.format_to_mime_type(@format)
       end
 
       # Match the given mime type with the Accept header
@@ -176,15 +339,35 @@ module Lotus
       end
 
       private
+
+      # @since 0.1.0
+      # @api private
       def accept
         @accept ||= @_env[HTTP_ACCEPT] || DEFAULT_ACCEPT
       end
 
+      # @since 0.1.0
+      # @api private
       def accepts
         unless accept == DEFAULT_ACCEPT
           ::Rack::Utils.best_q_match(accept, ::Rack::Mime::MIME_TYPES.values)
         end
       end
+
+      # @since 0.2.0
+      # @api private
+      def default_content_type
+        self.class.format_to_mime_type(
+          configuration.default_format
+        ) if configuration.default_format
+      end
+
+      # @since 0.2.0
+      # @api private
+      def detect_format
+        configuration.format_for(content_type) ||
+          ::Rack::Mime::MIME_TYPES.key(content_type).gsub(/\A\./, '').to_sym
+      end
     end
   end
 end