class Lita::Robot

The main object representing a running instance of Lita. Provides a high level API for the underlying adapter. Dispatches incoming messages to registered handlers. Can send outgoing chat messages and set the topic of chat rooms.

Attributes

alias[RW]

An alias the robot will look for in incoming messages to determine if it's being addressed. @return [String, Nil] The alias, if one was set.

app[R]

A Rack application used for the built-in web server. @return [Rack::Builder] The Rack app.

auth[R]

The {Authorization} object for the currently running robot. @return [Lita::Authorization] The authorization object. @since 4.0.0

mention_name[RW]

The name the robot will look for in incoming messages to determine if it's being addressed. @return [String] The mention name.

name[RW]

The name of the robot as it will appear in the chat. @return [String] The robot's name.

registry[R]

The {Registry} for the currently running robot. @return [Lita::Registry] The registry. @since 4.0.0

Public Class Methods

new(registry = Lita) click to toggle source

@param registry [Lita::Registry] The registry for the robot's configuration and plugins.

# File lib/lita/robot.rb, line 51
def initialize(registry = Lita)
  @registry = registry
  @name = config.robot.name
  @mention_name = config.robot.mention_name || @name
  @alias = config.robot.alias
  @app = RackApp.build(self)
  @auth = Authorization.new(config)
  trigger(:loaded, room_ids: persisted_rooms)
end

Public Instance Methods

join(room) click to toggle source

Makes the robot join a room with the specified ID. @param room [Room, String] The room to join, as a {Lita::Room} object or a string identifier. @return [void] @since 3.0.0

# File lib/lita/robot.rb, line 89
def join(room)
  room_object = find_room(room)

  if room_object
    Lita.redis.sadd("persisted_rooms", room_object.id)
    adapter.join(room_object.id)
  else
    adapter.join(room)
  end
end
part(room) click to toggle source

Makes the robot part from the room with the specified ID. @param room [Room, String] The room to leave, as a {Lita::Room} object or a string identifier. @return [void] @since 3.0.0

# File lib/lita/robot.rb, line 104
def part(room)
  room_object = find_room(room)

  if room_object
    Lita.redis.srem("persisted_rooms", room_object.id)
    adapter.part(room_object.id)
  else
    adapter.part(room)
  end
end
persisted_rooms() click to toggle source

A list of room IDs the robot should join on boot. @return [Array<String>] An array of room IDs. @since 4.4.2

# File lib/lita/robot.rb, line 118
def persisted_rooms
  Lita.redis.smembers("persisted_rooms").sort
end
receive(message) click to toggle source

The primary entry point from the adapter for an incoming message. Dispatches the message to all registered handlers. @param message [Lita::Message] The incoming message. @return [void]

# File lib/lita/robot.rb, line 65
def receive(message)
  matched = handlers.map do |handler|
    next unless handler.respond_to?(:dispatch)

    handler.dispatch(self, message)
  end.any?

  trigger(:unhandled_message, message: message) unless matched
end
run() click to toggle source

Starts the robot, booting the web server and delegating to the adapter to connect to the chat service. @return [void]

# File lib/lita/robot.rb, line 78
def run
  run_app
  adapter.run
rescue Interrupt
  shut_down
end
send_message(target, *strings)
Alias for: send_messages
send_message_with_mention(target, *strings)
send_messages(target, *strings) click to toggle source

Sends one or more messages to a user or room. @param target [Lita::Source] The user or room to send to. If the Source

has a room, it will choose the room. Otherwise, it will send to the
user.

@param strings [String, Array<String>] One or more strings to send. @return [void]

# File lib/lita/robot.rb, line 128
def send_messages(target, *strings)
  adapter.send_messages(target, strings.flatten)
end
Also aliased as: send_message
send_messages_with_mention(target, *strings) click to toggle source

Sends one or more messages to a user or room. If sending to a room, prefixes each message with the user's mention name. @param target [Lita::Source] The user or room to send to. If the Source

has a room, it will choose the room. Otherwise, it will send to the
user.

@param strings [String, Array<String>] One or more strings to send. @return [void] @since 3.1.0

# File lib/lita/robot.rb, line 141
def send_messages_with_mention(target, *strings)
  return send_messages(target, *strings) if target.private_message?

  mention_name = target.user.mention_name
  prefixed_strings = strings.map do |s|
    "#{adapter.mention_format(mention_name).strip} #{s}"
  end

  send_messages(target, *prefixed_strings)
end
Also aliased as: send_message_with_mention
set_topic(target, topic) click to toggle source

Sets the topic for a chat room. @param target [Lita::Source] A source object specifying the room. @param topic [String] The new topic message to set. @return [void]

# File lib/lita/robot.rb, line 157
def set_topic(target, topic)
  adapter.set_topic(target, topic)
end
shut_down() click to toggle source

Gracefully shuts the robot down, stopping the web server and delegating to the adapter to perform any shut down tasks necessary for the chat service. @return [void]

# File lib/lita/robot.rb, line 165
def shut_down
  trigger(:shut_down_started)
  @server.stop(true) if @server
  @server_thread.join if @server_thread
  adapter.shut_down
  trigger(:shut_down_complete)
end
trigger(event_name, payload = {}) click to toggle source

Triggers an event, instructing all registered handlers to invoke any methods subscribed to the event, and passing them a payload hash of arbitrary data. @param event_name [String, Symbol] The name of the event to trigger. @param payload [Hash] An optional hash of arbitrary data. @return [void]

# File lib/lita/robot.rb, line 179
def trigger(event_name, payload = {})
  handlers.each do |handler|
    next unless handler.respond_to?(:trigger)

    handler.trigger(self, event_name, payload)
  end
end

Private Instance Methods

adapter() click to toggle source

Loads and caches the adapter on first access.

# File lib/lita/robot.rb, line 190
def adapter
  @adapter ||= load_adapter
end
find_room(room_or_identifier) click to toggle source

Ensure the argument is a Lita::Room.

# File lib/lita/robot.rb, line 195
def find_room(room_or_identifier)
  case room_or_identifier
  when Room
    room_or_identifier
  else
    Room.fuzzy_find(room_or_identifier)
  end
end
load_adapter() click to toggle source

Loads the selected adapter.

# File lib/lita/robot.rb, line 205
def load_adapter
  adapter_name = config.robot.adapter
  adapter_class = adapters[adapter_name.to_sym]

  unless adapter_class
    Lita.logger.fatal I18n.t("lita.robot.unknown_adapter", adapter: adapter_name)
    abort
  end

  adapter_class.new(self)
end
run_app() click to toggle source

Starts the web server.

# File lib/lita/robot.rb, line 218
def run_app
  http_config = config.http

  @server_thread = Thread.new do
    @server = Puma::Server.new(app)
    begin
      @server.add_tcp_listener(http_config.host, http_config.port.to_i)
    rescue Errno::EADDRINUSE, Errno::EACCES => e
      Lita.logger.fatal I18n.t(
        "lita.http.exception",
        message: e.message,
        backtrace: e.backtrace.join("\n")
      )
      abort
    end
    @server.min_threads = http_config.min_threads
    @server.max_threads = http_config.max_threads
    @server.run
  end

  @server_thread.abort_on_exception = true
end