Alchemy.Events (alchemy v0.7.0)

This module provides raw Event hooks into the various events supplied by the gateway.

To use the macros in this module, it must be used. This also defines a __using__ macro for that module, which will then allow those hooks to be loaded in the main application via use.

Example Usage

defmodule Example do
  use Alchemy.Events

  Events.on_message(:inspect)
  def inspect(message) do
    IO.inspect message.content
  end
end

defmodule Application do
  use Application
  alias Alchemy.Client

  def start(_type, _args) do
    run = Client.start(@token)
    use Example
    run
  end

end

Link to this section Summary

Functions

disable(module, function)

Unhooks a function from the event handler.

on_DMChannel_create(func)

Registers a handle triggering whenever a user starts a DM with the client.

on_DMChannel_delete(func)

Registers a handle triggering whenever a user closes a DM with the client.

on_bulk_delete(func)

Registers a handle triggering whenever messages get bulk deleted from a channel.

on_channel_create(func)

Registers a handle triggering whenever a channel gets created.

on_channel_delete(func)

Registers a handle triggering whenever a guild channel gets removed.

on_channel_update(func)

Registers a handle triggering whenever a guild channel gets updated.

on_emoji_update(func)

Registers a handle triggering whenever a guild's emojis get updated.

on_guild_join(func)

Registers a handle triggering whenever this client joins a guild.

on_guild_leave(func)

Registers a handle triggering whenever the client leaves a guild.

on_guild_online(func)

Registers a handle triggering whenever a guild comes back online.

on_guild_update(func)

Registers a handle triggering whenever a guild gets updated.

on_integrations_update(func)

Registers a handle triggering whenever a guild's integrations get updated.

on_member_chunk(func)

Registers a handle triggering whenever a shard receives a member chunk.

on_member_join(func)

Registers a handle triggering whenever a member joins a guild.

on_member_leave(func)

Registers a handle triggering when a member leaves a guild.

on_member_update(func)

Registers a handle triggering when the status of a member changes in a guild.

on_message(func)

Registers a handle triggering whenever a message gets sent.

on_message_delete(func)

Registers a handle triggering whenever a single message gets deleted.

on_message_edit(func)

Registers a handle triggering whenever a message gets edited.

on_presence_update(func)

Registers a handle triggering whenever the presence of a user gets updated in a guild.

on_reaction_add(func)

Registers a handle triggering whenever a user reacts to a message.

on_reaction_remove(func)

Registers a handle triggering whenever a user deletes a reaction to a message.

on_reaction_remove_all(func)

Registere a handle triggering whenever a user deletes all reactions to a message.

on_ready(func)

Registers a handle triggering whenever a shard receives a READY event.

on_role_create(func)

Registers a handle triggering whenever a role gets created in a guild.

on_role_delete(func)

Registers a handle triggering whenever a role gets deleted from a guild.

on_role_update(func)

Registers a handle triggering whenever a role gets updated in a guild.

on_settings_update(func)

Registers a handle triggering whenever this user changes their settings.

on_typing(func)

Registers a handle triggering whenever a user starts typing in a channel.

on_user_ban(func)

Registers a handle triggering whenever a user gets banned from a guild.

on_user_unban(func)

Registers a handle triggering whenever a user gets unbanned from a guild.

on_user_update(func)

Registers a handle triggering whenever this user changes.

on_voice_update(func)

Registers a handle triggering whenever someone leaves / joins a voice channel.

unload(module)

Unloads all the hooks in a module from the handler.

Link to this section Functions

disable(module, function)

Specs

disable(atom(), atom()) :: :ok

Unhooks a function from the event handler.

If you want to unhook all the functions in a module, see Events.unload/1. Because you can have multiple hooks with the same name, this function takes both the module and the function name.

Examples

defmodule Annoying do
  use Alchemy.Events

  Events.on_message(:inspect)
  def inspect(message), do: IO.inspect message.content
end

This function is annoying us, so we can easily disable it:

Events.disable(Annoying, :inspect)

If we want to turn it back on, we can of course do

use Annoying

on_DMChannel_create(func)

(macro)

Registers a handle triggering whenever a user starts a DM with the client.

args : Alchemy.Channel.dm_channel

As opposed to on_channel_create, this event gets triggered when a user starts a direct message with this client.

Examples

Events.on_DMChannel_create(:foo)
def foo(%DMChannel{recipients: [user|_]}) do
  IO.inspect user.name <> " just DMed me!"
end

on_DMChannel_delete(func)

(macro)

Registers a handle triggering whenever a user closes a DM with the client.

args : Alchemy.Channel.dm_channel

on_bulk_delete(func)

(macro)

Registers a handle triggering whenever messages get bulk deleted from a channel.

args : [snowflake], snowflake

Receives a list of message ids that were deleted, and the channel they were deleted from.

on_channel_create(func)

(macro)

Registers a handle triggering whenever a channel gets created.

args : Alchemy.Channel.t

As opposed to on_DMChannel_create, this gets triggered when a channel gets created in a guild, and not when a user starts a DM with this client.

Examples

Events.on_channel_create(:foo)
def foo(channel), do: IO.inspect channel.name

on_channel_delete(func)

(macro)

Registers a handle triggering whenever a guild channel gets removed.

args : Alchemy.Channel.t

on_channel_update(func)

(macro)

Registers a handle triggering whenever a guild channel gets updated.

args : Alchemy.Channel.t

Examples

Events.on_channel_update(:foo)
def foo(channel) do
  IO.inspect "#{channel.name} was updated"
end

on_emoji_update(func)

(macro)

Registers a handle triggering whenever a guild's emojis get updated.

args : [Guild.emoji], snowflake

Receives a list of the current emojis in the guild, after this event, and the id of the guild itself.

on_guild_join(func)

(macro)

Registers a handle triggering whenever this client joins a guild.

args : Alchemy.Guild.t

A good amount of these events fire when the client initially connects to the gateway, and don't actually represent the client joining a new guild.

on_guild_leave(func)

(macro)

Registers a handle triggering whenever the client leaves a guild.

args : snowflake

The id of the guild the client left gets sent to the hook.

on_guild_online(func)

(macro)

Registers a handle triggering whenever a guild comes back online.

args : Alchemy.Guild.t

Sometimes due to outages, or other problems, guild may go offline. This can be checked via guild.unavailable. This event gets triggered whenever a guild comes back online after an outage.

on_guild_update(func)

(macro)

Registers a handle triggering whenever a guild gets updated.

args : Alchemy.Guild.t

A guild gets updated for various reasons, be it a member or role edition, or something else. The guild updated with this new info will be sent to the hook.

on_integrations_update(func)

(macro)

Registers a handle triggering whenever a guild's integrations get updated.

args : snowflake

Like other guild events, the info doesn't actually come through this event, but through on_guild_update. This hook is merely useful for reacting to the event having happened.

on_member_chunk(func)

(macro)

Registers a handle triggering whenever a shard receives a member chunk.

This event gets sent after a shard has requested offline guild member info for a guild.

args : snowflake, [Alchemy.Guild.GuildMember] Receives the id of the guild the members are from, and a list of members loaded.

on_member_join(func)

(macro)

Registers a handle triggering whenever a member joins a guild.

args : snowflake

The information of the member doesn't actually come through this event, but through on_guild_update.

on_member_leave(func)

(macro)

Registers a handle triggering when a member leaves a guild.

args : Alchemy.User.t, snowflake

Receives the user that left the guild, and the id of the guild they've left.

on_member_update(func)

(macro)

Registers a handle triggering when the status of a member changes in a guild.

args : Alchemy.Guild.Guild.member, snowflake

Receives the member that was updated, and the guild they belong to.

on_message(func)

(macro)

Registers a handle triggering whenever a message gets sent.

args : Alchemy.Message.t

Examples

use Alchemy.Events

Events.on_message(:ping)
def ping(msg), do: IO.inspect msg.content

on_message_delete(func)

(macro)

Registers a handle triggering whenever a single message gets deleted.

args : snowflake, snowflake

Receives the id of the message that was deleted, and the channel it was deleted from.

on_message_edit(func)

(macro)

Registers a handle triggering whenever a message gets edited.

args : snowflake, snowflake

Receives the id of the message that was edited, and the channel it was edited in.

on_presence_update(func)

(macro)

Registers a handle triggering whenever the presence of a user gets updated in a guild.

args : Alchemy.Presence.t

The presence struct here may be very incomplete.

on_reaction_add(func)

(macro)

Registers a handle triggering whenever a user reacts to a message.

args : snowflake, snowflake, snowflake %{"animated" => boolean, "id" => integer, "name" => String.t}

Receives the id of the user that reacted, the channel_id where it happened, the message_id and the emoji

on_reaction_remove(func)

(macro)

Registers a handle triggering whenever a user deletes a reaction to a message.

args : snowflake, snowflake, snowflake, %{"animated" => boolean, "id" => integer, "name" => String.t}

Receives the id of the user that reacted/deleted, the channel_id where it happened, the message_id and the emoji

on_reaction_remove_all(func)

(macro)

Registere a handle triggering whenever a user deletes all reactions to a message.

args : snowflake, snowflake

Receives the channel_id and message_id

on_ready(func)

(macro)

Registers a handle triggering whenever a shard receives a READY event.

This event gets sent after a shard connects with the gateway, filling the cache with info about the guilds the bot is in.

args : Integer, Integer Receives the shard number (starting at 0), and the total amount of shards.

After this event has been received, most of the information in the cache should be failed.

on_role_create(func)

(macro)

Registers a handle triggering whenever a role gets created in a guild.

args : Alchemy.Guild.role, snowflake

Receives the new role, as well as the id of the guild that it belongs to.

on_role_delete(func)

(macro)

Registers a handle triggering whenever a role gets deleted from a guild.

args : snowflake, snowflake

Receives the id of the role that was deleted, and the id of the guild it was deleted from.

on_role_update(func)

(macro)

Registers a handle triggering whenever a role gets updated in a guild.

args : Alchemy.Guild.role, Alchemy.Guild.role, snowflake

Receives the old role, the new role and the id of the guild that it belongs to. The old role may be nil if it was not already cached when the event was received.

on_settings_update(func)

(macro)

Registers a handle triggering whenever this user changes their settings.

args : String.t, String.t

Receives the username and avatar hash of the new settings.

on_typing(func)

(macro)

Registers a handle triggering whenever a user starts typing in a channel.

args : snowflake, snowflake, Integer

Receives the id of the user, the channel, and a timestamp (unix seconds) of the typing event.

on_user_ban(func)

(macro)

Registers a handle triggering whenever a user gets banned from a guild.

args : Alchemy.User.t, snowflake The user, as well as the id of the guild they were banned from get passed to the hook.

Example

Events.on_user_ban(:cancel_ban)
def cancel_ban(user, guild) do
  Client.unban_member(guild, user.id)
end

on_user_unban(func)

(macro)

Registers a handle triggering whenever a user gets unbanned from a guild.

args : Alchemy.User.t, snowflake Recieves the user struct, as well as the id of the guild from which the user has been unbanned.

Examples

Events.on_user_unban(:reban)
def reban(user, guild) do
  Client.ban_member(guild_id, user.id)
end

on_user_update(func)

(macro)

Registers a handle triggering whenever this user changes.

args : Alchemy.User.t

Receives the new information for this user.

on_voice_update(func)

(macro)

Registers a handle triggering whenever someone leaves / joins a voice channel.

args : Alchemy.Voice.state

Receives the corresponding voice state.

unload(module)

Specs

unload(atom()) :: :ok

Unloads all the hooks in a module from the handler.

If you just want to disable a single function from triggering, see Events.disable/1.

Examples

Client.start(@token)
use MyEvents

If we want to remove this hooks at any point, we can simply do

Events.unload(MyEvents)

And, to set hook the module back up, all we need to do is:

use MyEvents