alchemy

v0.6.0

alchemy v0.6.0 Alchemy.Cache

This module provides a handful of useful functions to interact with the cache.

By default, Alchemy caches a great deal of information given to it, notably about guilds. In general, using the cache should be prioritised over using the api functions in Alchemy.Client. However, a lot of struct modules have “smart” functions that will correctly balance the cache and the api, as well as use macros to get information from the context of commands.

Summary

Types

snowflake()

Functions

channel(guild_id, channel_id)

Retrieves a specific channel in a guild

emoji(guild_id, emoji_id)

Retrieves a custom emoji by id in a guild

guild(guild_id)

Fetches a guild from the cache by a given id

guild_id(channel_id)

Gets the corresponding guild_id for a channel

load_guild_members(guild_id, username \\ "", limit \\ 0)

Requests the loading of offline guild members for a guild

member(guild_id, member_id)

Gets a member from a cache, by guild and member id

presence(guild_id, user_id)

Gets the presence of a user in a certain guild

private_channel(channel_id)

Fetches a private_channel in the cache by id of the channel

role(guild_id, role_id)

Gets a specific role in a guild

search(section, filter)

Searches across all guild for information

user()

Gets the user struct for this client from the cache

voice_state(guild_id, user_id)

Retrieves a user’s voice state by id in a guild

Types

Functions

channel(guild_id, channel_id)

Specs

channel(snowflake, snowflake) ::
  {:ok, Alchemy.Channel.t} |
  {:error, String.t}

Retrieves a specific channel in a guild.

emoji(guild_id, emoji_id)

Specs

emoji(snowflake, snowflake) ::
  {:ok, Alchemy.Guild.emoji} |
  {:error, String.t}

Retrieves a custom emoji by id in a guild.

guild(guild_id)

Specs

guild(snowflake) ::
  {:ok, Alchemy.Guild.t} |
  {:error, String.t}

Fetches a guild from the cache by a given id.

By default, this method needs the guild_id, but keywords can be used to specify a different id, and use the appropiate paths to get the guild using that.

In general there are “smarter” methods, that will deal with getting the id for you; nonetheless, the need for this function sometimes exists.

Keywords

  • channel Using this keyword will fetch the information for the guild a channel belongs to.
guild_id(channel_id)

Specs

guild_id(snowflake) ::
  {:ok, snowflake} |
  {:error, String.t}

Gets the corresponding guild_id for a channel.

In case the channel guild can’t be found, :none will be returned.

This is useful when the guild_id is needed for some kind of task, but there’s no need for getting the whole struct. Because of how the registry is set up, getting the entire guild requires a whole extra step, that passes through this one anyways.

load_guild_members(guild_id, username \\ "", limit \\ 0)

Requests the loading of offline guild members for a guild.

Guilds should automatically get 250 offline members after the :ready event, however, you can use this method to request a fuller list if needed.

The username is used to only select members whose username starts with a certain string; "" won’t do any filtering. The limit specifies the amount of members to get; 0 for unlimited.

There’s a ratelimit of ~100 requests per shard per minute on this function, so be wary of the fact that this might block a process.

member(guild_id, member_id)

Specs

member(snowflake, snowflake) ::
  {:ok, Alchemy.Guild.member} |
  {:error, String.t}

Gets a member from a cache, by guild and member id.

presence(guild_id, user_id)

Specs

presence(snowflake, snowflake) ::
  {:ok, Alchemy.Guild.Presence.t} |
  {:error, String.t}

Gets the presence of a user in a certain guild.

This contains info such as their status, and roles.

private_channel(channel_id)

Specs

private_channel(snowflake) ::
  {:ok, Alchemy.Channel.dm_channel} |
  {:error, String.t}

Fetches a private_channel in the cache by id of the channel.

Takes a DMChannel id. Alternatively, user: user_id can be passed to find the private channel related to a user.

role(guild_id, role_id)

Specs

role(snowflake, snowflake) ::
  {:ok, Alchemy.Guild.role} |
  {:error, String.t}

Gets a specific role in a guild.

search(section, filter)

Specs

search(atom, (any -> Boolean)) :: [struct]

Searches across all guild for information.

The section is the type of object to search for. The possibilities are: :guilds, :members, :roles, :presences, :voice_states, :emojis, :channels

The filter is a function returning a boolean, that allows you to filter out elements from this list.

The return type will be a struct of the same type of the section searched for.

Examples

Cache.search(:members, fn x -> String.length(x.nick) < 10 end)

This will return a list of all members whose nickname is less than 10 characters long.

Cache.search(:roles, &match?(%{name: "Cool Kids"}, &1))

This is a good example of using the match?/2 function to filter against a pattern.

Cache.search(:guilds, &match?(%{name: "Test"}, &1))

Will match any guilds named “Test” in the cache.

user()

Specs

user :: Alchemy.User.t

Gets the user struct for this client from the cache.

Examples

Cogs.def hello do
  Cogs.say "hello, my name is #{Cache.user().name}"
end
voice_state(guild_id, user_id)

Specs

voice_state(snowflake, snowflake) ::
  {:ok, Alchemy.Voice.state} |
  {:error, String.t}

Retrieves a user’s voice state by id in a guild.