Class: Lita::Robot

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/lita/robot.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(registry = Lita) ⇒ Robot

Returns a new instance of Robot.

Parameters:

  • registry (Lita::Registry) (defaults to: Lita)

    The registry for the robot’s configuration and plugins.



51
52
53
54
55
56
57
58
59
# 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

Instance Attribute Details

#aliasString, Nil

An alias the robot will look for in incoming messages to determine if it’s being addressed.

Returns:

  • (String, Nil)

    The alias, if one was set.



26
27
28
# File 'lib/lita/robot.rb', line 26

def alias
  @alias
end

#appRack::Builder (readonly)

A Rack application used for the built-in web server.

Returns:

  • (Rack::Builder)

    The Rack app.



11
12
13
# File 'lib/lita/robot.rb', line 11

def app
  @app
end

#authLita::Authorization (readonly)

The Authorization object for the currently running robot.

Returns:

Since:

  • 4.0.0



16
17
18
# File 'lib/lita/robot.rb', line 16

def auth
  @auth
end

#mention_nameString

The name the robot will look for in incoming messages to determine if it’s being addressed.

Returns:

  • (String)

    The mention name.



21
22
23
# File 'lib/lita/robot.rb', line 21

def mention_name
  @mention_name
end

#nameString

The name of the robot as it will appear in the chat.

Returns:

  • (String)

    The robot’s name.



30
31
32
# File 'lib/lita/robot.rb', line 30

def name
  @name
end

#registryLita::Registry (readonly)

The Lita::Registry for the currently running robot.

Returns:

Since:

  • 4.0.0



35
36
37
# File 'lib/lita/robot.rb', line 35

def registry
  @registry
end

Instance Method Details

#chat_serviceObject

See Also:

Since:

  • 4.6.0



48
# File 'lib/lita/robot.rb', line 48

def_delegators :adapter, :chat_service, :mention_format, :roster

#join(room) ⇒ void

This method returns an undefined value.

Makes the robot join a room with the specified ID.

Parameters:

  • room (Room, String)

    The room to join, as a Lita::Room object or a string identifier.

Since:

  • 3.0.0



89
90
91
92
93
94
95
96
97
98
# 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

#mention_format(name) ⇒ Object

See Also:

Since:

  • 4.4.0



48
# File 'lib/lita/robot.rb', line 48

def_delegators :adapter, :chat_service, :mention_format, :roster

#part(room) ⇒ void

This method returns an undefined value.

Makes the robot part from the room with the specified ID.

Parameters:

  • room (Room, String)

    The room to leave, as a Lita::Room object or a string identifier.

Since:

  • 3.0.0



104
105
106
107
108
109
110
111
112
113
# 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_roomsArray<String>

A list of room IDs the robot should join on boot.

Returns:

  • (Array<String>)

    An array of room IDs.

Since:

  • 4.4.2



118
119
120
# File 'lib/lita/robot.rb', line 118

def persisted_rooms
  Lita.redis.smembers("persisted_rooms").sort
end

#receive(message) ⇒ void

This method returns an undefined value.

The primary entry point from the adapter for an incoming message. Dispatches the message to all registered handlers.

Parameters:



65
66
67
68
69
70
71
72
73
# 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

#roster(room) ⇒ Object

See Also:

Since:

  • 4.4.1



48
# File 'lib/lita/robot.rb', line 48

def_delegators :adapter, :chat_service, :mention_format, :roster

#runvoid

This method returns an undefined value.

Starts the robot, booting the web server and delegating to the adapter to connect to the chat service.



78
79
80
81
82
83
# File 'lib/lita/robot.rb', line 78

def run
  run_app
  adapter.run
rescue Interrupt
  shut_down
end

#send_messages(target, *strings) ⇒ void Also known as: send_message

This method returns an undefined value.

Sends one or more messages to a user or room.

Parameters:

  • 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.

  • strings (String, Array<String>)

    One or more strings to send.



128
129
130
# File 'lib/lita/robot.rb', line 128

def send_messages(target, *strings)
  adapter.send_messages(target, strings.flatten)
end

#send_messages_with_mention(target, *strings) ⇒ void Also known as: send_message_with_mention

This method returns an undefined value.

Sends one or more messages to a user or room. If sending to a room, prefixes each message with the user’s mention name.

Parameters:

  • 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.

  • strings (String, Array<String>)

    One or more strings to send.

Since:

  • 3.1.0



141
142
143
144
145
146
147
148
149
150
# 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

#set_topic(target, topic) ⇒ void

This method returns an undefined value.

Sets the topic for a chat room.

Parameters:

  • target (Lita::Source)

    A source object specifying the room.

  • topic (String)

    The new topic message to set.



157
158
159
# File 'lib/lita/robot.rb', line 157

def set_topic(target, topic)
  adapter.set_topic(target, topic)
end

#shut_downvoid

This method returns an undefined value.

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.



165
166
167
168
169
170
171
# 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 = {}) ⇒ void

This method returns an undefined value.

Triggers an event, instructing all registered handlers to invoke any methods subscribed to the event, and passing them a payload hash of arbitrary data.

Parameters:

  • event_name (String, Symbol)

    The name of the event to trigger.

  • payload (Hash) (defaults to: {})

    An optional hash of arbitrary data.



179
180
181
182
183
184
185
# 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