Alchemy.Cache (alchemy v0.7.0)

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.

Link to this section Summary

Functions

Retrieves a specific channel in a guild.

Retrieves a custom emoji by id in a guild.

Fetches a guild from the cache by a given id.

Gets the corresponding guild_id for a channel.

Requests the loading of offline guild members for a guild.

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

Gets the presence of a user in a certain guild.

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

Gets a specific role in a guild.

Searches across all guild for information.

Gets the user struct for this client from the cache.

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

Link to this section Types

Specs

snowflake() :: String.t()

Link to this section Functions

Link to this function

channel(guild_id, channel_id)

Specs

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

Retrieves a specific channel in a guild.

Link to this function

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.

Link to this function

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.
Link to this function

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.

Link to this function

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.

Link to this function

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.

Link to this function

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.

Link to this function

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.

Link to this function

role(guild_id, role_id)

Specs

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

Gets a specific role in a guild.

Link to this function

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.

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

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.