alchemy v0.6.0 Alchemy.Events

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

Summary

Functions

disable(module, function)

Unhooks a function from the event handler

unload(module)

Unloads all the hooks in a module from the handler

Macros

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_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_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

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

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

Macros

on_DMChannel_create(func)

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)

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

args : Alchemy.Channel.dm_channel

on_bulk_delete(func)

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)

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)

Registers a handle triggering whenever a guild channel gets removed.

args : Alchemy.Channel.t

on_channel_update(func)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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_ready(func)

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)

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)

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_settings_update(func)

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)

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)

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)

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)

Registers a handle triggering whenever this user changes.

args : Alchemy.User.t

Receives the new information for this user.

on_voice_update(func)

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

args : Alchemy.Voice.state

Receives the corresponding voice state.