configuration.rb

require 'lotus/utils/string'
require 'lotus/utils/class'

module Lotus
  module Controller
    # Configuration for the framework, controllers and actions.
    #
    # Lotus::Controller has its own global configuration that can be manipulated
    # via `Lotus::Controller.configure`.
    #
    # Every time that `Lotus::Controller` and `Lotus::Action` are included, that
    # global configuration is being copied to the recipient. The copy will
    # inherit all the settings from the original, but all the subsequent changes
    # aren't reflected from the parent to the children, and viceversa.
    #
    # This architecture allows to have a global configuration that capture the
    # most common cases for an application, and let controllers and single
    # actions to specify exceptions.
    #
    # @since 0.2.0
    class Configuration
      # Default HTTP code for server side errors
      #
      # @since 0.2.0
      # @api private
      DEFAULT_ERROR_CODE = 500

      # Default Mime type to format mapping
      #
      # @since 0.2.0
      # @api private
      DEFAULT_FORMATS = {
        '*/*'                      => :all,
        'application/octet-stream' => :all,
        'text/html'                => :html
      }.freeze

      # Return a copy of the configuration of the framework instance associated
      # with the given class.
      #
      # When multiple instances of Lotus::Controller are used in the same
      # application, we want to make sure that a controller or an action will
      # receive the expected configuration.
      #
      # @param base [Class, Module] a controller or an action
      #
      # @return [Lotus::Controller::Configuration] the configuration associated
      #   to the given class.
      #
      # @since 0.2.0
      # @api private
      #
      # @example Direct usage of the framework
      #   require 'lotus/controller'
      #
      #   class Show
      #     include Lotus::Action
      #   end
      #
      #   Lotus::Controller::Configuration.for(Show)
      #     # => will duplicate from Lotus::Controller
      #
      # @example Multiple instances of the framework
      #   require 'lotus/controller'
      #
      #   module MyApp
      #     Controller = Lotus::Controller.duplicate(self)
      #
      #     module Controllers::Dashboard
      #       include MyApp::Controller
      #
      #       action 'Index' do
      #         def call(params)
      #           # ...
      #         end
      #       end
      #     end
      #   end
      #
      #   class Show
      #     include Lotus::Action
      #   end
      #
      #   Lotus::Controller::Configuration.for(Show)
      #     # => will duplicate from Lotus::Controller
      #
      #   Lotus::Controller::Configuration.for(MyApp::Controllers::Dashboard)
      #     # => will duplicate from MyApp::Controller
      def self.for(base)
        namespace = Utils::String.new(base).namespace
        framework = Utils::Class.load!("(#{namespace}|Lotus)::Controller")
        framework.configuration.duplicate
      end

      # Initialize a configuration instance
      #
      # @return [Lotus::Controller::Configuration] a new configuration's
      #   instance
      #
      # @since 0.2.0
      def initialize
        reset!
      end

      # @attr_writer handle_exceptions [TrueClass,FalseClass] Decide if handle
      #   exceptions with an HTTP status or not
      #
      # @since 0.2.0
      #
      # @see Lotus::Controller::Configuration#handle_exceptions
      attr_writer :handle_exceptions

      # Decide if handle exceptions with an HTTP status or let them uncaught
      #
      # If this value is set to `true`, the configured exceptions will return
      # the specified HTTP status, the rest of them with `500`.
      #
      # If this value is set to `false`, the exceptions won't be caught.
      #
      # This is part of a DSL, for this reason when this method is called with
      # an argument, it will set the corresponding instance variable. When
      # called without, it will return the already set value, or the default.
      #
      # @overload handle_exceptions(value)
      #   Sets the given value
      #   @param value [TrueClass, FalseClass] true or false, default to true
      #
      # @overload handle_exceptions
      #   Gets the value
      #   @return [TrueClass, FalseClass]
      #
      # @since 0.2.0
      #
      # @see Lotus::Controller::Configuration#handle_exception
      # @see Lotus::Controller#configure
      # @see Lotus::Action::Throwable
      # @see http://httpstatus.es/500
      #
      # @example Getting the value
      #   require 'lotus/controller'
      #
      #   Lotus::Controller.configuration.handle_exceptions # => true
      #
      # @example Setting the value
      #   require 'lotus/controller'
      #
      #   Lotus::Controller.configure do
      #     handle_exceptions false
      #   end
      def handle_exceptions(value = nil)
        if value.nil?
          @handle_exceptions
        else
          @handle_exceptions = value
        end
      end

      # Specify how to handle an exception with an HTTP status
      #
      # Raised exceptions will return the configured HTTP status, only if
      #   `handled_exceptions` is set on `true`.
      #
      # @param exception [Hash] the exception class must be the key and the HTTP
      #   status the value
      #
      # @since 0.2.0
      #
      # @see Lotus::Controller::Configuration#handle_exceptions
      # @see Lotus::Controller#configure
      # @see Lotus::Action::Throwable
      #
      # @example
      #   require 'lotus/controller'
      #
      #   Lotus::Controller.configure do
      #     handle_exception ArgumentError => 400
      #   end
      def handle_exception(exception)
        @handled_exceptions.merge!(exception)
      end

      # Return the HTTP status for the given exception
      #
      # Raised exceptions will return the configured HTTP status, only if
      #   `handled_exceptions` is set on `true`.
      #
      # @param exception [Hash] the exception class must be the key and the HTTP
      #   status the value of the hash
      #
      # @since 0.2.0
      # @api private
      #
      # @see Lotus::Controller::Configuration#handle_exception
      def exception_code(exception)
        @handled_exceptions.fetch(exception) { DEFAULT_ERROR_CODE }
      end

      # Specify which is the default action module to be included when we use
      # the `Lotus::Controller.action` method.
      #
      # This setting is useful when we use multiple instances of the framework
      # in the same process, so we want to ensure that the actions will include
      # `MyApp::Action`, rather than `AnotherApp::Action`.
      #
      # If not set, the default value is `Lotus::Action`
      #
      # This is part of a DSL, for this reason when this method is called with
      # an argument, it will set the corresponding instance variable. When
      # called without, it will return the already set value, or the default.
      #
      # @overload action_module(value)
      #   Sets the given value
      #   @param value [Module] the module to be included in all the actions
      #
      # @overload action_module
      #   Gets the value
      #   @return [Module]
      #
      # @since 0.2.0
      #
      # @see Lotus::Controller::Dsl#action
      # @see Lotus::Controller#duplicate
      #
      # @example Getting the value
      #   require 'lotus/controller'
      #
      #   Lotus::Controller.configuration.action_module # => Lotus::Action
      #
      # @example Setting the value
      #   require 'lotus/controller'
      #
      #   module MyAction
      #   end
      #
      #   Lotus::Controller.configure do
      #     action_module MyAction
      #   end
      #
      #   class DashboardController
      #     include Lotus::Controller
      #
      #     # It includes MyAction, instead of Lotus::Action
      #     action 'Index' do
      #       def call(params)
      #         # ...
      #       end
      #     end
      #   end
      #
      # @example Duplicated framework
      #   require 'lotus/controller'
      #
      #   module MyApp
      #     Controller = Lotus::Controller.duplicate(self)
      #
      #     module Controllers::Dashboard
      #       include MyApp::Controller
      #
      #       # It includes MyApp::Action, instead of Lotus::Action
      #       action 'Index' do
      #         def call(params)
      #           # ...
      #         end
      #       end
      #     end
      #   end
      def action_module(value = nil)
        if value.nil?
          @action_module
        else
          @action_module = value
        end
      end

      # Specify the default modules to be included when `Lotus::Action` (or the
      # `action_module`) is included. This also works with
      # `Lotus::Controller.action`.
      #
      # If not set, this option will be ignored.
      #
      # This is part of a DSL, for this reason when this method is called with
      # an argument, it will set the corresponding instance variable. When
      # called without, it will return the already set value, or the default.
      #
      # @overload modules(blk)
      #   Adds the given block
      #   @param value [Proc] specify the modules to be included
      #
      # @overload modules
      #   Gets the value
      #   @return [Array] the list of the specified procs
      #
      # @since 0.2.0
      #
      # @see Lotus::Controller::Dsl#action
      # @see Lotus::Controller#duplicate
      #
      # @example Getting the value
      #   require 'lotus/controller'
      #
      #   Lotus::Controller.configuration.modules # => []
      #
      # @example Setting the value
      #   require 'lotus/controller'
      #   require 'lotus/action/cookies'
      #   require 'lotus/action/session'
      #
      #   Lotus::Controller.configure do
      #     modules do
      #       include Lotus::Action::Cookies
      #       include Lotus::Action::Session
      #     end
      #   end
      #
      #   class DashboardController
      #     include Lotus::Controller
      #
      #     # It includes:
      #     #   * Lotus::Action
      #     #   * Lotus::Action::Cookies
      #     #   * Lotus::Action::Session
      #     action 'Index' do
      #       def call(params)
      #         # ...
      #       end
      #     end
      #   end
      def modules(&blk)
        if block_given?
          @modules.push(blk)
        else
          @modules
        end
      end

      def format(symbol, mime_type)
        @formats.merge! mime_type => symbol
      end

      def format_for(mime_type)
        @formats[mime_type]
      end

      # Duplicate by copying the settings in a new instance.
      #
      # @return [Lotus::Controller::Configuration] a copy of the configuration
      #
      # @since 0.2.0
      # @api private
      def duplicate
        Configuration.new.tap do |c|
          c.handle_exceptions  = handle_exceptions
          c.handled_exceptions = handled_exceptions.dup
          c.action_module      = action_module
          c.modules            = modules.dup
          c.formats            = formats.dup
        end
      end

      # Reset all the values to the defaults
      #
      # @since 0.2.0
      # @api private
      def reset!
        @handle_exceptions  = true
        @handled_exceptions = {}
        @modules            = []
        @formats            = DEFAULT_FORMATS.dup
        @action_module      = ::Lotus::Action
      end

      # Load the configuration for the given action
      #
      # @since 0.2.0
      # @api private
      def load!(base)
        modules.each do |mod|
          base.class_eval(&mod)
        end
      end

      protected
      attr_accessor :handled_exceptions
      attr_accessor :formats
      attr_writer :action_module
      attr_writer :modules
    end
  end
end