module Lita::Handler::ChatRouter

A handler mixin that provides the methods necessary for responding to chat messages. @since 4.0.0

Constants

Route

A Struct representing a chat route defined by a handler.

Public Class Methods

extended(klass) click to toggle source

Includes common handler methods in any class that includes {ChatRouter}.

# File lib/lita/handler/chat_router.rb, line 7
def self.extended(klass)
  klass.send(:include, Common)
end

Public Instance Methods

dispatch(robot, message) click to toggle source

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.

# File lib/lita/handler/chat_router.rb, line 71
def dispatch(robot, message)
  routes.map do |route|
    next unless route_applies?(route, message, robot)
    log_dispatch(route)
    robot.trigger(
      :message_dispatched,
      handler: self,
      route: route,
      message: message,
      robot: robot
    )
    dispatch_to_route(route, robot, message)
    true
  end.any?
end
dispatch_to_route(route, robot, message) click to toggle source

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

# File lib/lita/handler/chat_router.rb, line 93
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 => error
  log_error(robot, error)
end
route(pattern, method_name = nil, **options, &block) click to toggle source

@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
# File lib/lita/handler/chat_router.rb, line 46
def route(pattern, method_name = nil, **options, &block)
  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 || block),
    options.delete(:command),
    options.delete(:restrict_to),
    options.delete(:help),
    options
  )
end
routes() click to toggle source

A list of chat routes defined by the handler. @return [Array<Lita::Handler::Route>]

# File lib/lita/handler/chat_router.rb, line 61
def routes
  @routes ||= []
end

Private Instance Methods

default_route_options() click to toggle source

The default options for every chat route.

# File lib/lita/handler/chat_router.rb, line 105
def default_route_options
  {
    command: false,
    restrict_to: nil,
    help: {}
  }
end
log_dispatch(route) click to toggle source

Logs the dispatch of message.

# File lib/lita/handler/chat_router.rb, line 119
def log_dispatch(route)
  Lita.logger.debug I18n.t(
    "lita.handler.dispatch",
    handler: name,
    method: route.callback.method_name || "(block)"
  )
end
route_applies?(route, message, robot) click to toggle source

Determines whether or not an incoming messages should trigger a route.

# File lib/lita/handler/chat_router.rb, line 114
def route_applies?(route, message, robot)
  RouteValidator.new(self, route, message, robot).call
end