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
snowflake()
Specs
snowflake() :: String.t()
Link to this section 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
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
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
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.