lita 3.3.1 → 4.0.0.rc1

data/lib/lita/errors.rb

@@ -0,0 +1,9 @@
+module Lita
+  # The root exception class that all Lita-specific exceptions inherit from.
+  # @since 4.0.0
+  class Error < StandardError; end
+
+  # An exception raised when a configuration attribute is invalid.
+  # @since 4.0.0
+  class ValidationError < Error; end
+end

data/lib/lita/handler.rb

@@ -1,268 +1,9 @@
 module Lita
-  # Base class for objects that add new behavior to Lita.
+  # Base class for objects that add new behavior to Lita. {Handler} is simply a class with all
+  # types of routers mixed in.
   class Handler
-    extend Forwardable
-
-    # A Redis::Namespace scoped to the handler.
-    # @return [Redis::Namespace]
-    attr_reader :redis
-
-    # The running {Lita::Robot} instance.
-    # @return [Lita::Robot]
-    attr_reader :robot
-
-    # A Struct representing a chat route defined by a handler.
-    class Route < Struct.new(
-      :pattern,
-      :method_name,
-      :command,
-      :required_groups,
-      :help,
-      :extensions
-    )
-      alias_method :command?, :command
-    end
-
-    class << self
-      # Creates a chat route.
-      # @param pattern [Regexp] A regular expression to match incoming messages
-      #   against.
-      # @param method [Symbol, String] The name of the method to trigger.
-      # @param command [Boolean] Whether or not the message must be directed at
-      #   the robot.
-      # @param restrict_to [Array<Symbol, String>, nil] A list of authorization
-      #   groups the user must be in to trigger the route.
-      # @param help [Hash] A map of example invocations to descriptions.
-      # @param extensions [Hash] Aribtrary additional data that can be used by Lita extensions.
-      # @return [void]
-      def route(pattern, method, **options)
-        options = default_route_options.merge(options)
-        options[:restrict_to] = options[:restrict_to].nil? ? nil : Array(options[:restrict_to])
-        routes << Route.new(
-          pattern,
-          method,
-          options.delete(:command),
-          options.delete(:restrict_to),
-          options.delete(:help),
-          options
-        )
-      end
-
-      # A list of chat routes defined by the handler.
-      # @return [Array<Lita::Handler::Route>]
-      def routes
-        @routes ||= []
-      end
-
-      # The main entry point for the handler at runtime. Checks if the message
-      # matches any of the routes and invokes the route's method if it does.
-      # Called by {Lita::Robot#receive}.
-      # @param robot [Lita::Robot] The currently running robot.
-      # @param message [Lita::Message] The incoming message.
-      # @return [void]
-      def dispatch(robot, message)
-        routes.each do |route|
-          next unless route_applies?(route, message, robot)
-          log_dispatch(route)
-          dispatch_to_route(route, robot, message)
-        end
-      end
-
-      # Dispatch directly to a {Route}, ignoring route conditions.
-      # @param route [Route] The route to invoke.
-      # @param robot [Lita::Robot] The currently running robot.
-      # @param message [Lita::Message] The incoming message.
-      # @return [void]
-      # @since 3.3.0
-      def dispatch_to_route(route, robot, message)
-        response = Response.new(message, route.pattern)
-        Lita.hooks[:trigger_route].each { |hook| hook.call(response: response, route: route) }
-        new(robot).public_send(route.method_name, response)
-      rescue Exception => e
-        log_dispatch_error(e)
-        raise e if rspec_loaded?
-      end
-
-      # Creates a new {Lita::HTTPRoute} which is used to define an HTTP route
-      # for the built-in web server.
-      # @see Lita::HTTPRoute
-      # @return [Lita::HTTPRoute] The new {Lita::HTTPRoute}.
-      def http
-        HTTPRoute.new(self)
-      end
-
-      # An array of all HTTP routes defined for the handler.
-      # @return [Array<Lita::HTTPRoute>] The array of routes.
-      def http_routes
-        @http_routes ||= []
-      end
-
-      # The namespace for the handler, used for its configuration object and
-      # Redis store. If the handler is an anonymous class, it must explicitly
-      # define +self.name+.
-      # @return [String] The handler's namespace.
-      # @raise [RuntimeError] If +self.name+ is not defined.
-      def namespace
-        if name
-          Util.underscore(name.split("::").last)
-        else
-          raise I18n.t("lita.handler.name_required")
-        end
-      end
-
-      # Registers an event subscription. When an event is triggered with
-      # {trigger}, a new instance of the handler will be created and the
-      # instance method name supplied to {on} will be invoked with a payload
-      # (a hash of arbitrary keys and values).
-      # @param event_name [String, Symbol] The name of the event to subscribe
-      #   to.
-      # @param method_name [String, Symbol] The name of the instance method on
-      #   the handler that should be invoked when the event is triggered.
-      # @return [void]
-      def on(event_name, method_name)
-        event_subscriptions[normalize_event(event_name)] << method_name
-      end
-
-      # Returns the translation for a key, automatically namespaced to the handler.
-      # @param key [String] The key of the translation.
-      # @param hash [Hash] An optional hash of values to be interpolated in the string.
-      # @return [String] The translated string.
-      # @since 3.0.0
-      def translate(key, hash = {})
-        I18n.translate("lita.handlers.#{namespace}.#{key}", hash)
-      end
-
-      alias_method :t, :translate
-
-      # Triggers an event, invoking methods previously registered with {on} and
-      # passing them a payload hash with any arbitrary data.
-      # @param robot [Lita::Robot] The currently running robot instance.
-      # @param event_name [String, Symbol], The name of the event to trigger.
-      # @param payload [Hash] An optional hash of arbitrary data.
-      # @return [void]
-      def trigger(robot, event_name, payload = {})
-        event_subscriptions[normalize_event(event_name)].each do |method_name|
-          new(robot).public_send(method_name, payload)
-        end
-      end
-
-      private
-
-      def default_route_options
-        {
-          command: false,
-          restrict_to: nil,
-          help: {}
-        }
-      end
-
-      # A hash of arrays used to store event subscriptions registered with {on}.
-      def event_subscriptions
-        @event_subscriptions ||= Hash.new { |h, k| h[k] = [] }
-      end
-
-      # Determines whether or not an incoming messages should trigger a route.
-      def route_applies?(route, message, robot)
-        RouteValidator.new(self, route, message, robot).call
-      end
-
-      # Checks if RSpec is loaded. If so, assume we are testing and let handler
-      # exceptions bubble up.
-      def rspec_loaded?
-        defined?(::RSpec)
-      end
-
-      # Logs the dispatch of message.
-      def log_dispatch(route)
-        Lita.logger.debug I18n.t(
-          "lita.handler.dispatch",
-          handler: name,
-          method: route.method_name
-        )
-      end
-
-      def log_dispatch_error(e)
-        Lita.logger.error I18n.t(
-          "lita.handler.exception",
-          handler: name,
-          message: e.message,
-          backtrace: e.backtrace.join("\n")
-        )
-      end
-
-      def normalize_event(event_name)
-        event_name.to_s.downcase.strip.to_sym
-      end
-    end
-
-    # @param robot [Lita::Robot] The currently running robot.
-    def initialize(robot)
-      @robot = robot
-      @redis = Redis::Namespace.new(redis_namespace, redis: Lita.redis)
-    end
-
-    # Invokes the given block after the given number of seconds.
-    # @param interval [Integer] The number of seconds to wait before invoking the block.
-    # @yieldparam timer [Lita::Timer] The current {Lita::Timer} instance.
-    # @return [void]
-    # @since 3.0.0
-    def after(interval, &block)
-      Thread.new { Timer.new(interval: interval, &block).start }
-    end
-
-    # The handler's config object.
-    # @return [Lita::Config] The handler's config object.
-    # @since 3.2.0
-    def config
-      Lita.config.handlers[self.class.namespace]
-    end
-
-    # Invokes the given block repeatedly, waiting the given number of seconds between each
-    # invocation.
-    # @param interval [Integer] The number of seconds to wait before each invocation of the block.
-    # @yieldparam timer [Lita::Timer] The current {Lita::Timer} instance.
-    # @return [void]
-    # @note The block should call {Lita::Timer#stop} at a terminating condition to avoid infinite
-    #   recursion.
-    # @since 3.0.0
-    def every(interval, &block)
-      Thread.new { Timer.new(interval: interval, recurring: true, &block).start }
-    end
-
-    # Creates a new +Faraday::Connection+ for making HTTP requests.
-    # @param options [Hash] A set of options passed on to Faraday.
-    # @yield [builder] A Faraday builder object for adding middleware.
-    # @return [Faraday::Connection] The new connection object.
-    def http(options = {}, &block)
-      options = default_faraday_options.merge(options)
-      Faraday::Connection.new(nil, options, &block)
-    end
-
-    # The Lita logger.
-    # @return [Lita::Logger] The Lita logger.
-    # @since 3.2.0
-    def log
-      Lita.logger
-    end
-
-    # @see .translate
-    def translate(*args)
-      self.class.translate(*args)
-    end
-
-    alias_method :t, :translate
-
-    private
-
-    # Default options for new Faraday connections. Sets the user agent to the
-    # current version of Lita.
-    def default_faraday_options
-      { headers: { "User-Agent" => "Lita v#{VERSION}" } }
-    end
-
-    # The handler's namespace for Redis.
-    def redis_namespace
-      "handlers:#{self.class.namespace}"
-    end
+    extend ChatRouter
+    extend HTTPRouter
+    extend EventRouter
   end
 end

data/lib/lita/handler/chat_router.rb

@@ -0,0 +1,130 @@
+module Lita
+  class Handler
+    # A handler mixin that provides the methods necessary for responding to chat messages.
+    # @since 4.0.0
+    module ChatRouter
+      # Includes common handler methods in any class that includes {ChatRouter}.
+      def self.extended(klass)
+        klass.send(:include, Common)
+      end
+
+      # A Struct representing a chat route defined by a handler.
+      class Route < Struct.new(
+        :pattern,
+        :callback,
+        :command,
+        :required_groups,
+        :help,
+        :extensions
+      )
+        alias_method :command?, :command
+      end
+
+      # @overload route(pattern, method_name, **options)
+      #   Creates a chat route.
+      #   @param pattern [Regexp] A regular expression to match incoming messages against.
+      #   @param method_name [Symbol, String] The name of the instance method to trigger.
+      #   @param command [Boolean] Whether or not the message must be directed at the robot.
+      #   @param restrict_to [Array<Symbol, String>, nil] An optional list of authorization
+      #     groups the user must be in to trigger the route.
+      #   @param help [Hash] An optional map of example invocations to descriptions.
+      #   @param options [Hash] Aribtrary additional data that can be used by Lita extensions.
+      #   @return [void]
+      # @overload route(pattern, **options)
+      #   Creates a chat route.
+      #   @param pattern [Regexp] A regular expression to match incoming messages against.
+      #   @param command [Boolean] Whether or not the message must be directed at the robot.
+      #   @param restrict_to [Array<Symbol, String>, nil] An optional list of authorization
+      #     groups the user must be in to trigger the route.
+      #   @param help [Hash] An optional map of example invocations to descriptions.
+      #   @param options [Hash] Aribtrary additional data that can be used by Lita extensions.
+      #   @yield The body of the route's callback.
+      #   @return [void]
+      #   @since 4.0.0
+      def route(pattern, method_name = nil, **options)
+        options = default_route_options.merge(options)
+        options[:restrict_to] = options[:restrict_to].nil? ? nil : Array(options[:restrict_to])
+        routes << Route.new(
+          pattern,
+          Callback.new(method_name || (proc if block_given?)),
+          options.delete(:command),
+          options.delete(:restrict_to),
+          options.delete(:help),
+          options
+        )
+      end
+
+      # A list of chat routes defined by the handler.
+      # @return [Array<Lita::Handler::Route>]
+      def routes
+        @routes ||= []
+      end
+
+      # The main entry point for the handler at runtime. Checks if the message
+      # matches any of the routes and invokes the route's method if it does.
+      # Called by {Lita::Robot#receive}.
+      # @param robot [Lita::Robot] The currently running robot.
+      # @param message [Lita::Message] The incoming message.
+      # @return [Boolean] Whether or not the message matched any routes.
+      def dispatch(robot, message)
+        routes.map do |route|
+          next unless route_applies?(route, message, robot)
+          log_dispatch(route)
+          dispatch_to_route(route, robot, message)
+          true
+        end.any?
+      end
+
+      # Dispatch directly to a {Route}, ignoring route conditions.
+      # @param route [Route] The route to invoke.
+      # @param robot [Lita::Robot] The currently running robot.
+      # @param message [Lita::Message] The incoming message.
+      # @return [void]
+      # @since 3.3.0
+      def dispatch_to_route(route, robot, message)
+        response = Response.new(message, route.pattern)
+        robot.hooks[:trigger_route].each { |hook| hook.call(response: response, route: route) }
+        handler = new(robot)
+        route.callback.call(handler, response)
+      rescue Exception => e
+        log_dispatch_error(e)
+        raise e if Lita.test_mode?
+      end
+
+      private
+
+      # The default options for every chat route.
+      def default_route_options
+        {
+          command: false,
+          restrict_to: nil,
+          help: {}
+        }
+      end
+
+      # Determines whether or not an incoming messages should trigger a route.
+      def route_applies?(route, message, robot)
+        RouteValidator.new(self, route, message, robot).call
+      end
+
+      # Logs the dispatch of message.
+      def log_dispatch(route)
+        Lita.logger.debug I18n.t(
+          "lita.handler.dispatch",
+          handler: name,
+          method: route.callback.method_name || "(block)"
+        )
+      end
+
+      # Logs an error encountered during dispatch.
+      def log_dispatch_error(e)
+        Lita.logger.error I18n.t(
+          "lita.handler.exception",
+          handler: name,
+          message: e.message,
+          backtrace: e.backtrace.join("\n")
+        )
+      end
+    end
+  end
+end

data/lib/lita/handler/common.rb

@@ -0,0 +1,114 @@
+module Lita
+  class Handler
+    # Methods included in any class that includes at least one type of router.
+    # @since 4.0.0
+    module Common
+      # Adds common functionality to the class and initializes the handler's configuration.
+      def self.included(klass)
+        klass.extend(ClassMethods)
+        klass.extend(Namespace)
+        klass.extend(Configurable)
+        klass.configuration = Configuration.new
+      end
+
+      # Common class-level methods for all handlers.
+      module ClassMethods
+        # Returns the translation for a key, automatically namespaced to the handler.
+        # @param key [String] The key of the translation.
+        # @param hash [Hash] An optional hash of values to be interpolated in the string.
+        # @return [String] The translated string.
+        # @since 3.0.0
+        def translate(key, hash = {})
+          I18n.translate("lita.handlers.#{namespace}.#{key}", hash)
+        end
+
+        alias_method :t, :translate
+      end
+
+      # A Redis::Namespace scoped to the handler.
+      # @return [Redis::Namespace]
+      attr_reader :redis
+
+      # The running {Lita::Robot} instance.
+      # @return [Lita::Robot]
+      attr_reader :robot
+
+      # @param robot [Lita::Robot] The currently running robot.
+      def initialize(robot)
+        @robot = robot
+        @redis = Redis::Namespace.new(redis_namespace, redis: Lita.redis)
+      end
+
+      # Invokes the given block after the given number of seconds.
+      # @param interval [Integer] The number of seconds to wait before invoking the block.
+      # @yieldparam timer [Lita::Timer] The current {Lita::Timer} instance.
+      # @return [void]
+      # @since 3.0.0
+      def after(interval, &block)
+        Thread.new { Timer.new(interval: interval, &block).start }
+      end
+
+      # The handler's config object.
+      # @return [Object, Lita::Config] The handler's configuration object.
+      # @since 3.2.0
+      def config
+        if robot.config.handlers.respond_to?(self.class.namespace)
+          robot.config.handlers.public_send(self.class.namespace)
+        end
+      end
+
+      # Invokes the given block repeatedly, waiting the given number of seconds between each
+      # invocation.
+      # @param interval [Integer] The number of seconds to wait before each invocation of the block.
+      # @yieldparam timer [Lita::Timer] The current {Lita::Timer} instance.
+      # @return [void]
+      # @note The block should call {Lita::Timer#stop} at a terminating condition to avoid infinite
+      #   recursion.
+      # @since 3.0.0
+      def every(interval, &block)
+        Thread.new { Timer.new(interval: interval, recurring: true, &block).start }
+      end
+
+      # Creates a new +Faraday::Connection+ for making HTTP requests.
+      # @param options [Hash] A set of options passed on to Faraday.
+      # @yield [builder] A Faraday builder object for adding middleware.
+      # @return [Faraday::Connection] The new connection object.
+      def http(options = {})
+        options = default_faraday_options.merge(options)
+
+        if block_given?
+          Faraday::Connection.new(nil, options, &proc)
+        else
+          Faraday::Connection.new(nil, options)
+        end
+      end
+
+      # The Lita logger.
+      # @return [Lita::Logger] The Lita logger.
+      # @since 3.2.0
+      def log
+        Lita.logger
+      end
+
+      # @see .translate
+      def translate(*args)
+        self.class.translate(*args)
+      end
+
+      alias_method :t, :translate
+
+      private
+
+      # Default options for new Faraday connections. Sets the user agent to the
+      # current version of Lita.
+      def default_faraday_options
+        { headers: { "User-Agent" => "Lita v#{VERSION}" } }
+      end
+
+      # The handler's namespace for Redis.
+      def redis_namespace
+        "handlers:#{self.class.namespace}"
+      end
+    end
+  end
+end