Alchemy.Events (alchemy v0.6.8)

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

Unhooks a function from the event handler.

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

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

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

Registers a handle triggering whenever a channel gets created.

Registers a handle triggering whenever a guild channel gets removed.

Registers a handle triggering whenever a guild channel gets updated.

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

Registers a handle triggering whenever this client joins a guild.

Registers a handle triggering whenever the client leaves a guild.

Registers a handle triggering whenever a guild comes back online.

Registers a handle triggering whenever a guild gets updated.

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

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

Registers a handle triggering whenever a member joins a guild.

Registers a handle triggering when a member leaves a guild.

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

Registers a handle triggering whenever a message gets sent.

Registers a handle triggering whenever a single message gets deleted.

Registers a handle triggering whenever a message gets edited.

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

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

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

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

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

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

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

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

Registers a handle triggering whenever this user changes their settings.

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

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

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

Registers a handle triggering whenever this user changes.

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

Unloads all the hooks in a module from the handler.

Link to this section Functions

Link to this function

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
Link to this macro

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
Link to this macro

on_DMChannel_delete(func)

(macro)

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

args : Alchemy.Channel.dm_channel

Link to this macro

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.

Link to this macro

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
Link to this macro

on_channel_delete(func)

(macro)

Registers a handle triggering whenever a guild channel gets removed.

args : Alchemy.Channel.t

Link to this macro

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
Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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
Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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

Link to this macro

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

Link to this macro

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

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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.

Link to this macro

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
Link to this macro

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
Link to this macro

on_user_update(func)

(macro)

Registers a handle triggering whenever this user changes.

args : Alchemy.User.t

Receives the new information for this user.

Link to this macro

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.

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