Skip to content

Parsing Discord entities

Jump to bottom
GoldenDelicios edited this page Jul 17, 2021 · 1 revision

Modbot contains utility methods to parse strings as a Role, User, Member, or TextChannel, through static methods provided by their respective classes (Roles, Users, Members, or TextChannels) in the org.slabserver.modbot.entity package.

The string may be one of:

  • a Snowflake ID (e.g. "167087172371873793")
  • a mention (e.g. "<@167087172371873793>")
  • a name (e.g. "MCfineplayer")
  • a user tag, if searching for Members or Users (e.g. "MCfineplayer#8714")
  • a nickname, if searching for Members or Users in a particular guild (e.g. "GoldenDelicios")

Methods

All methods take two arguments: a string query, and a guild. The guild may be null for Roles, Users, or TextChannels, but not for Members.

find(String, Guild)

Tries to find exactly one entity that matches the provided query. The result will be from the provided guild, if not null. If there are zero or multiple matches, an EntityNotFoundException is thrown with an appropriate message.

// finds exactly one role from all guilds named "Member", or else throws an exception
Role role = Roles.find("Member", null);

// finds exactly one role from the provided guild named "Member", or else throws an exception
Role role2 = Roles.find("Member", guild);

findId(String, Guild)

Tries to find exactly one ID that matches the provided query. If there are zero or multiple matches, an EntityNotFoundException is thrown with an appropriate message.

If the query is an ID or mention, the String is parsed as a Snowflake directly, regardless of whether it corresponds to a valid entity. Otherwise, the resulting ID will be from the provided guild, if not null.

In other words, this method does not guarantee that the resulting ID will be from the guild or valid at all. This method's purpose is to allow commands to accept direct IDs of entities that may not be accessible anymore on Discord but are still useful otherwise, usually for other queries or future API calls.

// finds exactly one role from the provided guild named "Member" and returns its ID, or else throws an exception.
// This is not an ID or mention, so the resulting ID will be valid and from the provided guild, if successful.
long roleId = Roles.findId("Member", guild);

// finds "245315595640242177" and returns it as a long, regardless of whether it's a valid role ID, or whether the role is from the provided guild.
long roldId2 = Roles.findId("<@&245315595640242177>", guild);

search(String, Guild)

Returns a list of all entities that match the provided query. This list may be empty or contain multiple results. All results will be from the provided guild, if not null.

// finds all roles from all guilds named "Member"
List<Role> roles = Roles.search("Member", null);

// finds all roles from the provided guild named "Member"
List<Role> roles2 = Roles.search("Member", guild);

searchIds(String, Guild)

Returns a list of IDs that match the provided query. This list may be empty or contain multiple results.

If the query is an ID or mention, the String is parsed as a Snowflake directly, regardless of whether it corresponds to a valid entity. Otherwise, the resulting IDs will be from the provided guild, if not null.

In other words, this method does not guarantee that the resulting IDs will be from the guild or valid at all. This method's purpose is to allow commands to accept direct IDs of entities that may not be accessible anymore on Discord but are still useful otherwise, usually for other queries or future API calls.

// finds all roles from the provided guild named "Member", and returns a list of their IDs.
List<String> roleIds = Roles.searchIds("Member", guild);

// finds "245315595640242177" and returns it in a list, regardless of whether it's a valid role ID, or whether the role is from the provided guild.
List<String> roleIds2 = Roles.searchIds("<@&245315595640242177>", guild);

EntityNotFoundException

find() and findId() may throw an EntityNotFoundException if exactly one result cannot be found. EntityNotFoundException extends CommandException, meaning that it will be relayed to the user if encountered during a command response.

Clone this wiki locally