From e710bc1c9005d6327e402739ebd74fef76e23796 Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Mon, 22 Apr 2024 19:41:07 +0100 Subject: [PATCH 1/6] Add new API methods cheat sheet --- guides/cheat-sheets/api.cheatmd | 139 ++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 guides/cheat-sheets/api.cheatmd diff --git a/guides/cheat-sheets/api.cheatmd b/guides/cheat-sheets/api.cheatmd new file mode 100644 index 000000000..3ec1fa043 --- /dev/null +++ b/guides/cheat-sheets/api.cheatmd @@ -0,0 +1,139 @@ +# API Usage + +This cheat sheet covers basic use of the Discord API through the `Nostrum.Api` module. + +## Messages +{: .col-2} + +### Sending a message + +```elixir +utc_now = DateTime.now!("Etc/UTC") +atom_count = :erlang.system_info(:atom_count) + +content = """ +UTC time is: #{DateTime.to_iso8601(utc_now)} +Atom table size is: #{atom_count} +""" + +Nostrum.Api.create_message(msg.channel_id, content) +``` + +### Sending a message with an embed + +```elixir +import Nostrum.Struct.Embed + +embed = + %Nostrum.Struct.Embed{} + |> put_title("Craig's Cats") + |> put_description("nostrum") + |> put_url("https://google.com/") + |> put_timestamp("2016-05-05T21:04:13.203Z") + |> put_color(431_948) + |> put_field("Field 1", "Test") + # set inline attribute to true + |> put_field("Field 2", "More test", true) + +Nostrum.Api.create_message(msg.channel_id, embeds: [embed]) +``` + +You can look at the documentation in `m:Nostrum.Struct.Embed#module-using-structs` for more advanced usage. + +### Upload an attachment + +```elixir +Nostrum.Api.create_message( + msg.channel_id, + files: [ + # file from filesystem + "/path/to/file.txt", + # file from memory + %{body: "test file", name: "example.txt"} + ] +) +``` + +### Reply to a message + +With a mention: + +```elixir +Nostrum.Api.create_message( + msg.channel_id, + content: "Hello!", + message_reference: %{message_id: msg.id} +) +``` + +Without a mention: + +```elixir +Nostrum.Api.create_message( + msg.channel_id, + content: "Hello!", + message_reference: %{message_id: msg.id}, + allowed_mentions: :none +) +``` + +### Send a poll + +```elixir +poll = Poll.create_poll( + "Do you enjoy pineapple on pizza?", + duration: 2, + allow_multiselect: false +) +|> Poll.put_answer("Yes!", default_emoji: "\u2705") +|> Poll.put_answer("No!", default_emoji: "\u274C") + +Api.create_message(channel_id, poll: poll) +``` + +### React to a message + +Using a default emoji (unicode representation): +```elixir +Nostrum.Api.create_reaction( + msg.channel_id, + msg.id, + "\xF0\x9F\x98\x80" +) +``` + +Using a custom Discord emoji: +```elixir +emoji = %Nostrum.Struct.Emoji{ + name: "emojiname", + id: 1228698654022434866 +} + +Nostrum.Api.create_reaction(msg.channel_id, msg.id, emoji) +``` + +## Miscellaneous +{: .col-2} + +### Update the bot status + +```elixir +Nostrum.Api.update_status( + :dnd, + "craigs cats", + 3 # Watching status +) +``` +You can also update a single shard with `Nostrum.Api.update_shard_status/5`. + +### Create a guild emoji + +```elixir +image = "data:image/png;base64,..." + +Nostrum.Api.create_guild_emoji( + msg.guild_id, + name: "nostrum", + image: image +) +``` From 579eecebfcb139f426e1f3fedc108c268d141d2f Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Mon, 22 Apr 2024 19:41:28 +0100 Subject: [PATCH 2/6] Add new cheat sheets category to ExDoc options --- mix.exs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/mix.exs b/mix.exs index d4e250122..b32a9689f 100644 --- a/mix.exs +++ b/mix.exs @@ -47,7 +47,8 @@ defmodule Nostrum.Mixfile do Introduction: ~r"/introduction/", Functionality: ~r"/functionality/", Configuration: ~r"/configuration/", - Advanced: ~r"/advanced/" + Advanced: ~r"/advanced/", + "Cheat Sheets": ~r"/cheat-sheets/" ], source_ref: "master", assets: "guides/assets", @@ -79,7 +80,8 @@ defmodule Nostrum.Mixfile do "guides/functionality/voice.md", "guides/advanced/pluggable_caching.md", "guides/advanced/multi_node.md", - "guides/advanced/hot_code_upgrade.md" + "guides/advanced/hot_code_upgrade.md", + "guides/cheat-sheets/api.cheatmd" ] end From 56649d4da88c6ed0d537402674bc424a40ccfc64 Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Sat, 4 May 2024 14:57:18 +0100 Subject: [PATCH 3/6] Simplify UTC time fetch in API cheatsheet --- guides/cheat-sheets/api.cheatmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/cheat-sheets/api.cheatmd b/guides/cheat-sheets/api.cheatmd index 3ec1fa043..ea2cea670 100644 --- a/guides/cheat-sheets/api.cheatmd +++ b/guides/cheat-sheets/api.cheatmd @@ -8,7 +8,7 @@ This cheat sheet covers basic use of the Discord API through the `Nostrum.Api` m ### Sending a message ```elixir -utc_now = DateTime.now!("Etc/UTC") +utc_now = DateTime.utc_now atom_count = :erlang.system_info(:atom_count) content = """ From 4d8030acffdeb40840e1768a5e6e7afb85e0fc4c Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Sat, 4 May 2024 15:09:50 +0100 Subject: [PATCH 4/6] Add QLC cheatsheet --- guides/cheat-sheets/qlc.cheatmd | 60 +++++++++++++++++++++++++++++++++ mix.exs | 3 +- 2 files changed, 62 insertions(+), 1 deletion(-) create mode 100644 guides/cheat-sheets/qlc.cheatmd diff --git a/guides/cheat-sheets/qlc.cheatmd b/guides/cheat-sheets/qlc.cheatmd new file mode 100644 index 000000000..298c57af1 --- /dev/null +++ b/guides/cheat-sheets/qlc.cheatmd @@ -0,0 +1,60 @@ +# QLC Usage + +This cheat sheet covers some example queries using Query-List Comprehensions in Erlang, as well as some debugging tips. + +QLC modules must include this library include as part of their prelude: + +```erl +-include_lib("stdlib/include/qlc.hrl"). +``` + +As per the Erlang docs for QLC: + +> This causes a parse transform to substitute a fun for the QLC. The (compiled) fun is called when the query handle is evaluated. + +## Examples + +### Fetch role members + +```erl +find_role_users(RequestedGuildId, RoleId, MemberCache) -> + qlc:q([{User, Member} || {{GuildId, MemberId}, Member} <- MemberCache:query_handle(), + % Filter to member objects of the selected guild + GuildId =:= RequestedGuildId, + % Filter to members of the provided role + lists:member(RoleId, map_get(roles, Member))]). +``` + +### Fetch guilds over a certain size + +```erl +find_large_communities(Threshold, GuildCache) -> + qlc:q([Guild || {_, Guild} <- GuildCache:query_handle(), + % Filter for guilds that are over the provided size + map_get(member_count, Guild) > Threshold]). +``` + +## Debugging QLC + +{: .col-2 } + +### View query info + +You can use `:qlc.info/1` to evaluate how Erlang will parse a query. You can read the Erlang docs for an explanation of the value returned by this call + +```elixir +:qlc.info( + :my_queries.find_users(..., Nostrum.Cache.UserCache) +) +``` + +### Sampling a query + +You can return only X records that match a query using `:qlc.next_answers/2`, passing in the query as the first argument and the number of answers to return as the second argument. + +```elixir +:qlc.next_answers( + :my_queries.find_users(..., Nostrum.Cache.UserCache), + 5 +) +``` diff --git a/mix.exs b/mix.exs index b32a9689f..a79ea2453 100644 --- a/mix.exs +++ b/mix.exs @@ -81,7 +81,8 @@ defmodule Nostrum.Mixfile do "guides/advanced/pluggable_caching.md", "guides/advanced/multi_node.md", "guides/advanced/hot_code_upgrade.md", - "guides/cheat-sheets/api.cheatmd" + "guides/cheat-sheets/api.cheatmd", + "guides/cheat-sheets/qlc.cheatmd" ] end From 4cfd6f756550bc8e53693d6a4d732180323d0578 Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Sat, 4 May 2024 15:12:02 +0100 Subject: [PATCH 5/6] Update from unicode escapes to unicode emoji in API cheatsheet --- guides/cheat-sheets/api.cheatmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/cheat-sheets/api.cheatmd b/guides/cheat-sheets/api.cheatmd index ea2cea670..773f4d918 100644 --- a/guides/cheat-sheets/api.cheatmd +++ b/guides/cheat-sheets/api.cheatmd @@ -98,7 +98,7 @@ Using a default emoji (unicode representation): Nostrum.Api.create_reaction( msg.channel_id, msg.id, - "\xF0\x9F\x98\x80" + "👾" ) ``` From fd9bf4209f02d16a0d6efef8181d46d506c34e28 Mon Sep 17 00:00:00 2001 From: Joe Banks Date: Sat, 4 May 2024 18:50:35 +0100 Subject: [PATCH 6/6] Add online user query to QLC cheatsheet --- guides/cheat-sheets/qlc.cheatmd | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/guides/cheat-sheets/qlc.cheatmd b/guides/cheat-sheets/qlc.cheatmd index 298c57af1..8118c3e6e 100644 --- a/guides/cheat-sheets/qlc.cheatmd +++ b/guides/cheat-sheets/qlc.cheatmd @@ -34,6 +34,23 @@ find_large_communities(Threshold, GuildCache) -> map_get(member_count, Guild) > Threshold]). ``` +### Find all online users in a guild + +```erl +find_online_users(RequestedGuildId, PresenceCache, UserCache) -> + qlc:q([User || {{GuildId, PresenceUserId}, Presence} <- PresenceCache:query_handle(), + % Filter to members in the requested guild ID + GuildId =:= RequestedGuildId, + % Fetch any members where the status is not offline + map_get(status, Presence) /= offline, + % Join the found users on the UserCache + {UserId, User} <- UserCache:query_handle(), + % Return the users that match the found presences + UserId =:= PresenceUserId]). +``` + +This depends on the guild presences intent being enabled and the bot storing received presences in the presence cache. + ## Debugging QLC {: .col-2 }