util
ClassOn this page
util is a DiscordLua class representing a Discord resource. Obtain it from a manager, an event payload, or the constructor when one is documented below.
Methods
Performs basename on this util. Call it from bot code when you need that operation on the current object.
Signature
util.basename(path, ext) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
path |
any |
required | Passed through to the implementation as written. |
ext |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.basename(path, ext)Define a DiscordLua class table with callable construction and :new.
Signature
util.class(name) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
name |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.class(name)Performs clean code block content on this util. Call it from bot code when you need that operation on the current object.
Signature
util.cleanCodeBlockContent(text) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
text |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.cleanCodeBlockContent(text)Performs clean content on this util. Call it from bot code when you need that operation on the current object.
Signature
util.cleanContent(text, context) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
text |
any |
required | Passed through to the implementation as written. |
context |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.cleanContent(text, context)Performs count on this util. Call it from bot code when you need that operation on the current object.
Signature
util.count(value) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
value |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.count(value)Performs discord sort on this util. Call it from bot code when you need that operation on the current object.
Signature
util.discordSort(collection) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
collection |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.discordSort(collection)Encode an array of values for a REST body field.
Signature
util.encode_list(list) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
list |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.encode_list(list)Encode a message send/edit payload for REST.
Signature
util.encode_message(contentOrOptions) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
contentOrOptions |
table |
optional | Lua option table. Field names match the corresponding DiscordLua option type when one exists. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.encode_message("Hello")Encode a single Lua value for a REST body field.
Signature
util.encode_one(value) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
value |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.encode_one(value)Encode a poll object for a message payload.
Signature
util.encode_poll(options) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
options |
table |
optional | Lua option table. Field names match the corresponding DiscordLua option type when one exists. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.encode_poll({})Encode a single poll answer.
Signature
util.encode_poll_answer(answer) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
answer |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.encode_poll_answer(answer)Encode poll question or answer media.
Signature
util.encode_poll_media(media) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
media |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.encode_poll_media(media)Encode role create/edit options, including colors and permissions.
Signature
util.encodeRoleOptions(options) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
options |
table |
optional | Lua option table. Field names match the corresponding DiscordLua option type when one exists. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.encodeRoleOptions({})Performs find name on this util. Call it from bot code when you need that operation on the current object.
Signature
util.findName(data) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
data |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.findName(data)Flatten nested option tables before encoding a REST payload.
Signature
util.flatten(obj, props) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
obj |
any |
required | Passed through to the implementation as written. |
props |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.flatten(obj, props)Read the SortableGroupTypes value from this util.
Signature
util.getSortableGroupTypes(channelType) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
channelType |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.getSortableGroupTypes(channelType)Predicate that returns whether this util matches is_builder. Use it to branch before calling type-specific methods.
Signature
util.is_builder(value) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
value |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.is_builder(value)Predicate that returns whether this util matches is_json_null. Use it to branch before calling type-specific methods.
Signature
util.is_json_null(value) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
value |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.is_json_null(value)Performs join args on this util. Call it from bot code when you need that operation on the current object.
Signature
util.join_args(args, startIndex, fallback) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
args |
any |
required | Passed through to the implementation as written. |
startIndex |
any |
required | Passed through to the implementation as written. |
fallback |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.join_args(args, startIndex, fallback)Construct a DiscordLua error object from a name and message.
Signature
util.makeError(data) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
data |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.makeError(data)Construct a plain error table without Discord-specific fields.
Signature
util.makePlainError(err) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
err |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.makePlainError(err)Performs message ids from json on this util. Call it from bot code when you need that operation on the current object.
Signature
util.message_ids_from_json(body) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
body |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.message_ids_from_json(body)Move an element to a new index in a Lua array.
Signature
util.moveElementInArray(array, element, newIndex, offset) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
array |
any |
required | Passed through to the implementation as written. |
element |
any |
required | Passed through to the implementation as written. |
newIndex |
any |
required | Passed through to the implementation as written. |
offset |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.moveElementInArray(array, element, newIndex, offset)Performs parse duration ms on this util. Call it from bot code when you need that operation on the current object.
Signature
util.parse_duration_ms(value) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
value |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.parse_duration_ms(value)Parse a hex color string into a numeric color value.
Signature
util.parse_hex(text) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
text |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.parse_hex(text)Parse an emoji mention, unicode character, or name into a table DiscordLua can send.
Signature
util.parseEmoji(text) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
text |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.parseEmoji(text)Performs parse webhook url on this util. Call it from bot code when you need that operation on the current object.
Signature
util.parseWebhookURL(url) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
url |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.parseWebhookURL(url)Performs permission name on this util. Call it from bot code when you need that operation on the current object.
Signature
util.permission_name(bit) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
bit |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.permission_name(bit)Performs public error on this util. Call it from bot code when you need that operation on the current object.
Signature
util.public_error(err) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
err |
any |
required | Passed through to the implementation as written. |
Returns
any.
Throws
A DiscordLua error when arguments are invalid or the request fails without a callback.
Example
local discord = require("discord")
-- object is a util
util.public_error(err)Performs request on this util. Call it from bot code when you need that operation on the current object.
Signature
util.request(client, method, path, body, callback) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
client |
any |
required | Passed through to the implementation as written. |
method |
any |
required | Passed through to the implementation as written. |
path |
any |
required | Passed through to the implementation as written. |
body |
any |
required | Passed through to the implementation as written. |
callback |
function |
optional | Optional completion callback function(err, result). If omitted, failures raise a DiscordLua error. |
Returns
any.
Throws
A DiscordLua error when arguments are invalid or the request fails without a callback.
Example
local discord = require("discord")
-- object is a util
util.request(client, method, path, body, function(err, result)
if err then error(err) end
end)Encode binary or text input as a base64 string for REST image fields.
Signature
util.resolveBase64(data) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
data |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolveBase64(data)Extract an invite or template code from a URL or raw code string.
Signature
util.resolveCode(data, pattern) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
data |
any |
required | Passed through to the implementation as written. |
pattern |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolveCode(data, pattern)Convert a color name, hex string, number, or RGB table into the integer DiscordLua encodes on REST payloads.
Signature
util.resolveColor(color) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
color |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolveColor(color)Resolve a guild emoji from an id, mention, or emoji object.
Signature
util.resolveGuildEmoji(guild, emoji) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
guild |
any |
required | Passed through to the implementation as written. |
emoji |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolveGuildEmoji(guild, emoji)Extract a guild template code from a URL or raw code string.
Signature
util.resolveGuildTemplateCode(data) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
data |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolveGuildTemplateCode(data)Turn a file path, data URI, or buffer into the image data DiscordLua sends on REST.
Signature
util.resolveImage(image) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
image |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolveImage(image)Extract a Discord invite code from a URL or raw code string.
Signature
util.resolveInviteCode(data) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
data |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolveInviteCode(data)Normalize an emoji mention or id/name table into a partial emoji payload.
Signature
util.resolvePartialEmoji(emoji) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
emoji |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolvePartialEmoji(emoji)Resolve a role color value the same way role create/edit payloads accept it.
Signature
util.resolveRoleColor(value) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
value |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolveRoleColor(value)Resolve a table of role color fields before encoding a role payload.
Signature
util.resolveRoleColors(colors) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
colors |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolveRoleColors(colors)Performs resolve skuid on this util. Call it from bot code when you need that operation on the current object.
Signature
util.resolveSKUId(sku) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
sku |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.resolveSKUId(sku)Performs timeout until on this util. Call it from bot code when you need that operation on the current object.
Signature
util.timeout_until(duration) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
duration |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.timeout_until(duration)Convert a camelCase identifier into snake_case for REST body keys.
Signature
util.toSnakeCase(text) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
text |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.toSnakeCase(text)Performs transform resolved on this util. Call it from bot code when you need that operation on the current object.
Signature
util.transformResolved(resolved) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
resolved |
any |
required | Passed through to the implementation as written. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.transformResolved(resolved)Assert that a value is a non-empty string, or raise.
Signature
util.verifyString(data, errorType, errorMessage, allowEmpty) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
data |
any |
required | Passed through to the implementation as written. |
errorType |
any |
required | Passed through to the implementation as written. |
errorMessage |
any |
required | Passed through to the implementation as written. |
allowEmpty |
any |
required | Passed through to the implementation as written. |
Returns
any.
Throws
A DiscordLua error when arguments are invalid or the request fails without a callback.
Example
local discord = require("discord")
-- object is a util
util.verifyString(data, errorType, errorMessage, allowEmpty)Performs with wrapped on this util. Call it from bot code when you need that operation on the current object.
Signature
util.with_wrapped(client, wrap_fn, callback) Parameters
| Name | Type | Required | Behavior |
|---|---|---|---|
client |
any |
required | Passed through to the implementation as written. |
wrap_fn |
any |
required | Passed through to the implementation as written. |
callback |
function |
optional | Optional completion callback function(err, result). If omitted, failures raise a DiscordLua error. |
Returns
any.
Example
local discord = require("discord")
-- object is a util
util.with_wrapped(client, wrap_fn, function(err, result)
if err then error(err) end
end)Static members
-
util.null
Examples
Obtain this object from a manager, wrap helper, or event payload — it is not constructed directly in typical bot code.
Related APIs
ActionRow · Activity · ActivityInstance · ActivityLocation · AnonymousGuild · ApplicationCommand · ApplicationRoleConnectionMetadata · Attachment
Version: discord 1.2.4 · runtime 1.0.0