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


545
546
547
548
549
# File 'lib/discordrb/container.rb', line 545

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

535
536
537
538
539
540
# File 'lib/discordrb/container.rb', line 535

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

527
528
529
# File 'lib/discordrb/container.rb', line 527

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.


503
504
505
506
507
508
# File 'lib/discordrb/container.rb', line 503

def add_handler(handler)
  clazz = EventContainer.event_class(handler.class)
  @event_handlers ||= {}
  @event_handlers[clazz] ||= []
  @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.


439
440
441
# File 'lib/discordrb/container.rb', line 439

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 (Integer)

    Matches the type of channel that is being created (0: text, 1: private, 2: voice, 3: group)

  • :name (String)

    Matches the name of the created channel.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


190
191
192
# File 'lib/discordrb/container.rb', line 190

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

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

This event is raised when a channel is deleted.

Options Hash (attributes):

  • :type (Integer)

    Matches the type of channel that is being deleted (0: text, 1: private, 2: voice, 3: group).

  • :name (String)

    Matches the name of the deleted channel.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


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

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

#channel_recipient_add(attributes = {}) {|event| ... } ⇒ ChannelRecipientAddHandler

This event is raised when a recipient is added to a group channel.

Options Hash (attributes):

  • :name (String)

    Matches the name of the group channel that the recipient is added to.

  • :owner_id (#resolve_id)

    Matches the id of the group channel's owner.

  • :id (#resolve_id)

    Matches the id of the recipient added to the group channel.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


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

def channel_recipient_add(attributes = {}, &block)
  register_event(ChannelRecipientAddEvent, attributes, block)
end

#channel_recipient_remove(attributes = {}) {|event| ... } ⇒ ChannelRecipientRemoveHandler

This event is raised when a recipient is removed from a group channel.

Options Hash (attributes):

  • :name (String)

    Matches the name of the group channel that the recipient is added to.

  • :owner_id (#resolve_id)

    Matches the id of the group channel's owner.

  • :id (#resolve_id)

    Matches the id of the recipient removed from the group channel.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


236
237
238
# File 'lib/discordrb/container.rb', line 236

def channel_recipient_remove(attributes = {}, &block)
  register_event(ChannelRecipientRemoveEvent, attributes, block)
end

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

This event is raised when a channel is updated.

Options Hash (attributes):

  • :type (Integer)

    Matches the type of channel that is being updated (0: text, 1: private, 2: voice, 3: group).

  • :name (String)

    Matches the new name of the channel.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


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

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

#clear!Object

Removes all events from this event handler.


496
497
498
# File 'lib/discordrb/container.rb', line 496

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

#heartbeat(attributes = {}) {|event| ... } ⇒ HeartbeatEventHandler

This event is raised every time the bot sends a heartbeat over the galaxy. This happens roughly every 40 seconds, but may happen at a lower rate should Discord change their interval. It may also happen more quickly for periods of time, especially for unstable connections, since discordrb rather sends a heartbeat than not if there's a choice. (You shouldn't rely on all this to be accurately timed.)

All this makes this event useful to periodically trigger something, like doing some API request every hour, setting some kind of uptime variable or whatever else. The only limit is yourself.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


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

def heartbeat(attributes = {}, &block)
  register_event(HeartbeatEvent, 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.


512
513
514
515
516
517
518
# File 'lib/discordrb/container.rb', line 512

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:


263
264
265
# File 'lib/discordrb/container.rb', line 263

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:


284
285
286
# File 'lib/discordrb/container.rb', line 284

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. This includes when a members nickname or roles are updated.

Options Hash (attributes):

  • :username (String)

    Matches the username of the updated user.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


274
275
276
# File 'lib/discordrb/container.rb', line 274

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.

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


179
180
181
# File 'lib/discordrb/container.rb', line 179

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.

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


108
109
110
# File 'lib/discordrb/container.rb', line 108

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:


97
98
99
# File 'lib/discordrb/container.rb', line 97

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.

  • :type (Integer)

    Matches the type of game object (0 game, 1 Twitch stream)

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


161
162
163
# File 'lib/discordrb/container.rb', line 161

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

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

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.

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


457
458
459
# File 'lib/discordrb/container.rb', line 457

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:


149
150
151
# File 'lib/discordrb/container.rb', line 149

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

#raw(attributes = {}) {|event| ... } ⇒ RawEventHandler

This event is raised for every dispatch received over the gateway, whether supported by discordrb or not.

Options Hash (attributes):

  • :type (String, Symbol, Regexp)

    Matches the event type of the dispatch.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:

  • event (RawEvent)

    The event that was raised.


471
472
473
# File 'lib/discordrb/container.rb', line 471

def raw(attributes = {}, &block)
  register_event(RawEvent, attributes, block)
end

#reaction_add(attributes = {}) {|event| ... } ⇒ ReactionAddEventHandler

This event is raised when somebody reacts to a message.

Options Hash (attributes):

  • :emoji (Integer, String)

    Matches the ID of the emoji that was reacted with, or its name.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


118
119
120
# File 'lib/discordrb/container.rb', line 118

def reaction_add(attributes = {}, &block)
  register_event(ReactionAddEvent, attributes, block)
end

#reaction_remove(attributes = {}) {|event| ... } ⇒ ReactionRemoveEventHandler

This event is raised when somebody removes a reaction from a message.

Options Hash (attributes):

  • :emoji (Integer, String)

    Matches the ID of the emoji that was removed from the reactions, or its name.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


129
130
131
# File 'lib/discordrb/container.rb', line 129

def reaction_remove(attributes = {}, &block)
  register_event(ReactionRemoveEvent, attributes, block)
end

#reaction_remove_all(attributes = {}) {|event| ... } ⇒ ReactionRemoveAllEventHandler

This event is raised when somebody removes all reactions from a message.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


138
139
140
# File 'lib/discordrb/container.rb', line 138

def reaction_remove_all(attributes = {}, &block)
  register_event(ReactionRemoveAllEvent, 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.


489
490
491
492
493
# File 'lib/discordrb/container.rb', line 489

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.

Options Hash (attributes):

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


317
318
319
# File 'lib/discordrb/container.rb', line 317

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:


338
339
340
# File 'lib/discordrb/container.rb', line 338

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

#server_emoji(attributes = {}) {|event| ... } ⇒ ServerEmojiChangeEventHandler

This event is raised when an emoji or collection of emojis is created/deleted/updated.

Options Hash (attributes):

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


348
349
350
# File 'lib/discordrb/container.rb', line 348

def server_emoji(attributes = {}, &block)
  register_event(ServerEmojiChangeEvent, attributes, block)
end

#server_emoji_create(attributes = {}) {|event| ... } ⇒ ServerEmojiCreateEventHandler

This event is raised when an emoji is created.

Options Hash (attributes):

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


360
361
362
# File 'lib/discordrb/container.rb', line 360

def server_emoji_create(attributes = {}, &block)
  register_event(ServerEmojiCreateEvent, attributes, block)
end

#server_emoji_delete(attributes = {}) {|event| ... } ⇒ ServerEmojiDeleteEventHandler

This event is raised when an emoji is deleted.

Options Hash (attributes):

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


372
373
374
# File 'lib/discordrb/container.rb', line 372

def server_emoji_delete(attributes = {}, &block)
  register_event(ServerEmojiDeleteEvent, attributes, block)
end

#server_emoji_update(attributes = {}) {|event| ... } ⇒ ServerEmojiUpdateEventHandler

This event is raised when an emoji is updated.

Options Hash (attributes):

  • :server (String, Integer, Server)

    Matches the server.

  • :id (String, Integer)

    Matches the id of the emoji.

  • :name (String)

    Matches the name of the emoji.

  • :old_name (String)

    Matches the name of the emoji before the update.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


385
386
387
# File 'lib/discordrb/container.rb', line 385

def server_emoji_update(attributes = {}, &block)
  register_event(ServerEmojiUpdateEvent, attributes, block)
end

#server_role_create(attributes = {}) {|event| ... } ⇒ ServerRoleCreateEventHandler

This event is raised when a role is created.

Options Hash (attributes):

  • :name (String)

    Matches the role name.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


395
396
397
# File 'lib/discordrb/container.rb', line 395

def server_role_create(attributes = {}, &block)
  register_event(ServerRoleCreateEvent, attributes, block)
end

#server_role_delete(attributes = {}) {|event| ... } ⇒ ServerRoleDeleteEventHandler

This event is raised when a role is deleted.

Options Hash (attributes):

  • :id (#resolve_id)

    Matches the role id.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


405
406
407
# File 'lib/discordrb/container.rb', line 405

def server_role_delete(attributes = {}, &block)
  register_event(ServerRoleDeleteEvent, attributes, block)
end

#server_role_update(attributes = {}) {|event| ... } ⇒ ServerRoleUpdateEventHandler

This event is raised when a role is updated.

Options Hash (attributes):

  • :name (String)

    Matches the role name.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


415
416
417
# File 'lib/discordrb/container.rb', line 415

def server_role_update(attributes = {}, &block)
  register_event(ServerRoleUpdateEvent, 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:


327
328
329
# File 'lib/discordrb/container.rb', line 327

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:


86
87
88
# File 'lib/discordrb/container.rb', line 86

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

#unknown(attributes = {}) {|event| ... } ⇒ UnknownEventHandler

This event is raised for a dispatch received over the gateway that is not currently handled otherwise by discordrb.

Options Hash (attributes):

  • :type (String, Symbol, Regexp)

    Matches the event type of the dispatch.

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


482
483
484
# File 'lib/discordrb/container.rb', line 482

def unknown(attributes = {}, &block)
  register_event(UnknownEvent, 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:


295
296
297
# File 'lib/discordrb/container.rb', line 295

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:


306
307
308
# File 'lib/discordrb/container.rb', line 306

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. This includes when a user joins, leaves, or moves between voice channels, as well as their mute and deaf status for themselves and on the server.

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.

  • :old_channel (String, Integer, Channel)

    Matches the voice channel the user was in previously.

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


253
254
255
# File 'lib/discordrb/container.rb', line 253

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

#webhook_update(attributes = {}) {|event| ... } ⇒ WebhookUpdateEventHandler

This event is raised when a webhook is updated.

Options Hash (attributes):

Yields:

  • The block is executed when the event is raised.

Yield Parameters:


427
428
429
# File 'lib/discordrb/container.rb', line 427

def webhook_update(attributes = {}, &block)
  register_event(WebhookUpdateEvent, attributes, block)
end