Module: Discordrb::EventContainer

Includes:
Events
Included in:
Bot
Defined in:
lib/discordrb/container.rb

Overview

This module provides the functionality required for events and awaits. It is separated from the Bot class so users can make their own container modules and include them.

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Events

matches_all

Class Method Details

.class_from_string(str) ⇒ Class

Utility method to return a class object from a string of its name. Mostly useful for internal stuff



362
363
364
365
366
 
# File 'lib/discordrb/container.rb', line 362

def self.class_from_string(str)
  str.split('::').inject(Object) do |mod, class_name|
    mod.const_get(class_name)
  end
end

.event_class(handler_class) ⇒ Class?

Returns the event class for a handler class type

See Also:

  • #handler_class


352
353
354
355
356
357
 
# File 'lib/discordrb/container.rb', line 352

def self.event_class(handler_class)
  class_name = handler_class.to_s
  return nil unless class_name.end_with? 'Handler'

  EventContainer.class_from_string(class_name[0..-8])
end

.handler_class(event_class) ⇒ Class

Returns the handler class for an event class type

See Also:

  • #event_class


344
345
346
 
# File 'lib/discordrb/container.rb', line 344

def self.handler_class(event_class)
  class_from_string(event_class.to_s + 'Handler')
end

Instance Method Details

#add_handler(handler) ⇒ Object Also known as: <<

Adds an event handler to this container. Usually, it's more expressive to just use one of the shorthand adder methods like #message, but if you want to create one manually you can use this.



321
322
323
324
325
 
# File 'lib/discordrb/container.rb', line 321

def add_handler(handler)
  clazz = EventContainer.event_class(handler.class)
  @event_handlers ||= {}
  @event_handlers[clazz] << handler
end

#await(attributes = {}) {|event| ... } ⇒ AwaitEventHandler

This event is raised when an Await is triggered. It provides an easy way to execute code on an await without having to rely on the await's block.

Options Hash (attributes):

  • :key (Symbol) —

    Exactly matches the await's key.

  • :type (Class) —

    Exactly matches the event's type.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:

  • event (AwaitEvent) —

    The event that was raised.



279
280
281
 
# File 'lib/discordrb/container.rb', line 279

def await(attributes = {}, &block)
  register_event(AwaitEvent, attributes, block)
end

#channel_create(attributes = {}) {|event| ... } ⇒ ChannelCreateEventHandler

This event is raised when a channel is created.

Options Hash (attributes):

  • :type (String) —

    Matches the type of channel that is being created (text or voice)

  • :name (String) —

    Matches the name of the created channel.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



145
146
147
 
# File 'lib/discordrb/container.rb', line 145

def channel_create(attributes = {}, &block)
  register_event(ChannelCreateEvent, attributes, block)
end

#channel_delete(attributes = {}) {|event| ... } ⇒ ChannelDeleteEventHandler

This event is raised when a channel is updated.

Options Hash (attributes):

  • :type (String) —

    Matches the type of channel that is being deleted (text or voice)

  • :name (String) —

    Matches the name of the deleted channel.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



167
168
169
 
# File 'lib/discordrb/container.rb', line 167

def channel_delete(attributes = {}, &block)
  register_event(ChannelDeleteEvent, attributes, block)
end

#channel_update(attributes = {}) {|event| ... } ⇒ ChannelUpdateEventHandler

This event is raised when a channel is updated.

Options Hash (attributes):

  • :type (String) —

    Matches the type of channel that is being updated (text or voice)

  • :name (String) —

    Matches the new name of the channel.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



156
157
158
 
# File 'lib/discordrb/container.rb', line 156

def channel_update(attributes = {}, &block)
  register_event(ChannelUpdateEvent, attributes, block)
end

#clear! ⇒ Object

Removes all events from this event handler.



314
315
316
 
# File 'lib/discordrb/container.rb', line 314

def clear!
  @event_handlers.clear if @event_handlers
end

#disconnected(attributes = {}) {|event| ... } ⇒ DisconnectEventHandler

This event is raised when the bot has disconnected from the WebSocket, due to the Bot#stop method or external causes. It's the recommended way to do clean-up tasks.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



56
57
58
 
# File 'lib/discordrb/container.rb', line 56

def disconnected(attributes = {}, &block)
  register_event(DisconnectEvent, attributes, block)
end

#include_events(container) ⇒ Object Also known as: include!

Adds all event handlers from another container into this one. Existing event handlers will be overwritten.



329
330
331
332
333
334
335
 
# File 'lib/discordrb/container.rb', line 329

def include_events(container)
  handlers = container.instance_variable_get '@event_handlers'
  return unless handlers

  @event_handlers ||= {}
  @event_handlers.merge!(handlers) { |_, old, new| old + new }
end

#member_join(attributes = {}) {|event| ... } ⇒ ServerMemberAddEventHandler

This event is raised when a new user joins a server.

Options Hash (attributes):

  • :username (String) —

    Matches the username of the joined user.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



192
193
194
 
# File 'lib/discordrb/container.rb', line 192

def member_join(attributes = {}, &block)
  register_event(ServerMemberAddEvent, attributes, block)
end

#member_leave(attributes = {}) {|event| ... } ⇒ ServerMemberDeleteEventHandler

This event is raised when a member leaves a server.

Options Hash (attributes):

  • :username (String) —

    Matches the username of the member.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



212
213
214
 
# File 'lib/discordrb/container.rb', line 212

def member_leave(attributes = {}, &block)
  register_event(ServerMemberDeleteEvent, attributes, block)
end

#member_update(attributes = {}) {|event| ... } ⇒ ServerMemberUpdateEventHandler

This event is raised when a member update happens.

Options Hash (attributes):

  • :username (String) —

    Matches the username of the updated user.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



202
203
204
 
# File 'lib/discordrb/container.rb', line 202

def member_update(attributes = {}, &block)
  register_event(ServerMemberUpdateEvent, attributes, block)
end

#mention(attributes = {}) {|event| ... } ⇒ MentionEventHandler

This event is raised when the bot is mentioned in a message.

Options Hash (attributes):

  • :start_with (String, Regexp) —

    Matches the string the message starts with.

  • :end_with (String, Regexp) —

    Matches the string the message ends with.

  • :contains (String, Regexp) —

    Matches a string the message contains.

  • :in (String, Integer, Channel) —

    Matches the channel the message was sent in.

  • :from (String, Integer, User) —

    Matches the user that sent the message.

  • :content (String) —

    Exactly matches the entire content of the message.

  • :content (String) —

    Exactly matches the entire content of the message.

  • :after (Time) —

    Matches a time after the time the message was sent at.

  • :before (Time) —

    Matches a time before the time the message was sent at.

  • :private (Boolean) —

    Matches whether or not the channel is private.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



134
135
136
 
# File 'lib/discordrb/container.rb', line 134

def mention(attributes = {}, &block)
  register_event(MentionEvent, attributes, block)
end

#message(attributes = {}) {|event| ... } ⇒ MessageEventHandler

This event is raised when a message is sent to a text channel the bot is currently in.

Options Hash (attributes):

  • :start_with (String, Regexp) —

    Matches the string the message starts with.

  • :end_with (String, Regexp) —

    Matches the string the message ends with.

  • :contains (String, Regexp) —

    Matches a string the message contains.

  • :in (String, Integer, Channel) —

    Matches the channel the message was sent in.

  • :from (String, Integer, User) —

    Matches the user that sent the message.

  • :content (String) —

    Exactly matches the entire content of the message.

  • :content (String) —

    Exactly matches the entire content of the message.

  • :after (Time) —

    Matches a time after the time the message was sent at.

  • :before (Time) —

    Matches a time before the time the message was sent at.

  • :private (Boolean) —

    Matches whether or not the channel is private.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



36
37
38
 
# File 'lib/discordrb/container.rb', line 36

def message(attributes = {}, &block)
  register_event(MessageEvent, attributes, block)
end

#message_delete(attributes = {}) {|event| ... } ⇒ MessageDeleteEventHandler

This event is raised when a message is deleted in a channel.

Options Hash (attributes):

  • :id (#resolve_id) —

    Matches the ID of the message that was deleted.

  • :in (String, Integer, Channel) —

    Matches the channel the message was deleted in.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



93
94
95
 
# File 'lib/discordrb/container.rb', line 93

def message_delete(attributes = {}, &block)
  register_event(MessageDeleteEvent, attributes, block)
end

#message_edit(attributes = {}) {|event| ... } ⇒ MessageEditEventHandler

This event is raised when a message is edited in a channel.

Options Hash (attributes):

  • :id (#resolve_id) —

    Matches the ID of the message that was edited.

  • :in (String, Integer, Channel) —

    Matches the channel the message was edited in.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



82
83
84
 
# File 'lib/discordrb/container.rb', line 82

def message_edit(attributes = {}, &block)
  register_event(MessageEditEvent, attributes, block)
end

#playing(attributes = {}) {|event| ... } ⇒ PlayingEventHandler

This event is raised when the game a user is playing changes.

Options Hash (attributes):

  • :from (String, Integer, User) —

    Matches the user whose playing game changes.

  • :game (String) —

    Matches the game the user is now playing.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



115
116
117
 
# File 'lib/discordrb/container.rb', line 115

def playing(attributes = {}, &block)
  register_event(PlayingEvent, attributes, block)
end

#pm(attributes = {}) {|event| ... } ⇒ PrivateMessageEventHandler Also known as: private_message

This event is raised when a private message is sent to the bot.

Options Hash (attributes):

  • :start_with (String, Regexp) —

    Matches the string the message starts with.

  • :end_with (String, Regexp) —

    Matches the string the message ends with.

  • :contains (String, Regexp) —

    Matches a string the message contains.

  • :in (String, Integer, Channel) —

    Matches the channel the message was sent in.

  • :from (String, Integer, User) —

    Matches the user that sent the message.

  • :content (String) —

    Exactly matches the entire content of the message.

  • :content (String) —

    Exactly matches the entire content of the message.

  • :after (Time) —

    Matches a time after the time the message was sent at.

  • :before (Time) —

    Matches a time before the time the message was sent at.

  • :private (Boolean) —

    Matches whether or not the channel is private.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



298
299
300
 
# File 'lib/discordrb/container.rb', line 298

def pm(attributes = {}, &block)
  register_event(PrivateMessageEvent, attributes, block)
end

#presence(attributes = {}) {|event| ... } ⇒ PresenceEventHandler

This event is raised when a user's status (online/offline/idle) changes.

Options Hash (attributes):

  • :from (String, Integer, User) —

    Matches the user whose status changed.

  • :status (:offline, :idle, :online) —

    Matches the status the user has now.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



104
105
106
 
# File 'lib/discordrb/container.rb', line 104

def presence(attributes = {}, &block)
  register_event(PresenceEvent, attributes, block)
end

#ready(attributes = {}) {|event| ... } ⇒ ReadyEventHandler

This event is raised when the READY packet is received, i. e. servers and channels have finished initialization. It's the recommended way to do things when the bot has finished starting up.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:

  • event (ReadyEvent) —

    The event that was raised.



46
47
48
 
# File 'lib/discordrb/container.rb', line 46

def ready(attributes = {}, &block)
  register_event(ReadyEvent, attributes, block)
end

#remove_handler(handler) ⇒ Object

Removes an event handler from this container. If you're looking for a way to do temporary events, I recommend Awaits instead of this.



307
308
309
310
311
 
# File 'lib/discordrb/container.rb', line 307

def remove_handler(handler)
  clazz = EventContainer.event_class(handler.class)
  @event_handlers ||= {}
  @event_handlers[clazz].delete(handler)
end

#server_create(attributes = {}) {|event| ... } ⇒ ServerCreateEventHandler

This event is raised when a server is created respective to the bot, i. e. the bot joins a server or creates a new one itself. It should never be necessary to listen to this event as it will only ever be triggered by things the bot itself does, but one can never know.

Options Hash (attributes):

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



246
247
248
 
# File 'lib/discordrb/container.rb', line 246

def server_create(attributes = {}, &block)
  register_event(ServerCreateEvent, attributes, block)
end

#server_delete(attributes = {}) {|event| ... } ⇒ ServerDeleteEventHandler

This event is raised when a server is deleted, or when the bot leaves a server. (These two cases are identical to Discord.)

Options Hash (attributes):

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



267
268
269
 
# File 'lib/discordrb/container.rb', line 267

def server_delete(attributes = {}, &block)
  register_event(ServerDeleteEvent, attributes, block)
end

#server_update(attributes = {}) {|event| ... } ⇒ ServerUpdateEventHandler

This event is raised when a server is updated, for example if the name or region has changed.

Options Hash (attributes):

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



256
257
258
 
# File 'lib/discordrb/container.rb', line 256

def server_update(attributes = {}, &block)
  register_event(ServerUpdateEvent, attributes, block)
end

#typing(attributes = {}) {|event| ... } ⇒ TypingEventHandler

This event is raised when somebody starts typing in a channel the bot is also in. The official Discord client would display the typing indicator for five seconds after receiving this event. If the user continues typing after five seconds, the event will be re-raised.

Options Hash (attributes):

  • :in (String, Integer, Channel) —

    Matches the channel where typing was started.

  • :from (String, Integer, User) —

    Matches the user that started typing.

  • :after (Time) —

    Matches a time after the time the typing started.

  • :before (Time) —

    Matches a time before the time the typing started.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



71
72
73
 
# File 'lib/discordrb/container.rb', line 71

def typing(attributes = {}, &block)
  register_event(TypingEvent, attributes, block)
end

#user_ban(attributes = {}) {|event| ... } ⇒ UserBanEventHandler

This event is raised when a user is banned from a server.

Options Hash (attributes):

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



223
224
225
 
# File 'lib/discordrb/container.rb', line 223

def user_ban(attributes = {}, &block)
  register_event(UserBanEvent, attributes, block)
end

#user_unban(attributes = {}) {|event| ... } ⇒ UserUnbanEventHandler

This event is raised when a user is unbanned from a server.

Options Hash (attributes):

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



234
235
236
 
# File 'lib/discordrb/container.rb', line 234

def user_unban(attributes = {}, &block)
  register_event(UserUnbanEvent, attributes, block)
end

#voice_state_update(attributes = {}) {|event| ... } ⇒ VoiceStateUpdateEventHandler

This event is raised when a user's voice state changes.

Options Hash (attributes):

  • :from (String, Integer, User) —

    Matches the user that sent the message.

  • :channel (String, Integer, Channel) —

    Matches the voice channel the user has joined.

  • :mute (true, false) —

    Matches whether or not the user is muted server-wide.

  • :deaf (true, false) —

    Matches whether or not the user is deafened server-wide.

  • :self_mute (true, false) —

    Matches whether or not the user is muted by the bot.

  • :self_deaf (true, false) —

    Matches whether or not the user is deafened by the bot.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:



182
183
184
 
# File 'lib/discordrb/container.rb', line 182

def voice_state_update(attributes = {}, &block)
  register_event(VoiceStateUpdateEvent, attributes, block)
end