Work In Progress
This documentation is in beta. It's missing lots of content, search is broken, and many links go nowhere. These problems will be fixed before release, but there's plenty of work left!
Skip to main content

Custom Checks

You can create your own custom checks in one of several ways, using the context API and check utilities.

Writing Checks​

Inline​

If you don't need to re-use a check, you can define it inline in your check {} or validate {} builder.

  • check {} builders use a CheckContext receiver.
  • validate {} builders use a ValidationContext receiver, which extends CheckContext with some extra APIs.
check {
    val channel = guildFor(event)

    if (channel == null) {
       fail(CoreTranslations.Checks.AnyGuild.failed)
    }
}

Re-usable​

If you need a re-usable check, define an extension function against the CheckContext type. Checks written this way should be more in-depth and include logging.

suspend fun CheckContext<*>.anyGuild() {
    if (!passed) {
        return  // If the check context is already failing, we can skip this check.
    }

    // Create a logger with the containing package and function name.
    val logger = KotlinLogging.logger("dev.kordex.core.checks.anyGuild")

    if (guildFor(event) != null) {
        logger.passed()  // Logging a pass is as important as logging a failure!

        pass()
    } else {
        logger.failed("Event did not happen within a guild.")

        fail(CoreTranslations.Checks.AnyGuild.failed)
    }
}

Context API​

All check {} builders use CheckContext as their receiver type.

open class CheckContext : KordExKoinComponent

Check context type, containing everything you need to write your own checks.

Type Parameters
out TType: Event

Generic type representing the event being checked.

Constructor Arguments
val eventType: T

Event object to be checked.

val localeType: Locale

Locale for the current event, retrieved via your bot's locale resolvers.

Builders​

failIf { ... }Function Returns: BooleanLambda Returns: Boolean

Fail this check if the provided lambda returns false. Calls fail() internally.

Returns true if the check is now failing, false otherwise.

Function Arguments
Arguments
messageTypes:Key?String

Message to respond with explaining why the check failed.

failIfNot { ... }Function Returns: BooleanLambda Returns: Boolean

Fail this check if the provided lambda returns true. Calls fail() internally.

Returns true if the check is now failing.

Function Arguments
Arguments
messageTypes:Key?String

Message to respond with explaining why the check failed.

passIf { ... }Function Returns: BooleanLambda Returns: Boolean

Passes this check if the provided lambda returns true. Calls pass() internally.

Returns true if the check is now passing.

passIfNot { ... }Function Returns: BooleanLambda Returns: Boolean

Passes this check if the provided lambda returns false. Calls pass() internally.

Returns true if the check is now passing.

whenFalse { ... }Receiver: BooleanLambda Returns: T?

Calls the provided lambda only if this boolean is false, returning whatever the lambda does.

If this boolean is true, simply returns null.

whenTrue { ... }Receiver: BooleanLambda Returns: T?

Calls the provided lambda only if this boolean is true, returning whatever the lambda does.

If this boolean is false, simply returns null.

Functions​

fail(...)

Fails this check, setting passed to true.

Arguments
messageTypes:Key?String

Message to respond with explaining why the check failed.

failIf(...)

Fails this check if the provided boolean is true. Calls fail() internally.

Returns true if the check is now failing.

Arguments
valueType: Boolean

Boolean value to check.

messageTypes:Key?String

Message to respond with explaining why the check failed.

failIfNot(...)

Fails this check if the provided boolean is false. Calls fail() internally.

Returns true if the check is now failing.

Arguments
valueType: Boolean

Boolean value to check.

messageTypes:Key?String

Message to respond with explaining why the check failed.

pass(...)

Passes this check, setting passed to true.

passIf(...)

Passes this check if the provided boolean is true. Calls pass() internally.

Returns true if the check is now passing.

Arguments
valueType: Boolean

Boolean value to check.

passIfNot(...)

Passes this check if the provided boolean is false. Calls pass() internally.

Returns true if the check is now passing.

Arguments
valueType: Boolean

Boolean value to check.

Show/Hide Internal APIs
getMessageKey(...)Returns:Key?

Get a pre-translation Key representing the current failure message, provided the check is failing and a message was set.

Otherwise, this function returns null.

getTranslatedMessage(...)Returns:String?

Returns a translated string based on the value returned by getMessageKey(), returning null in the same situations.

throwIfFailedWithMessage(...)

Throws a DiscordRelayedException with the value returned by getMessageKey(), if that value isn't null.

Properties​

errorResponseKeyType: KeyDefault: CoreTranslations.Checks.responseTemplate

Translation key used to construct an error message to display on Discord.

You can replace this with your own key if you need to. Custom keys must support one ordinal placeholder, {0}, containing the error message.

messageType: String?Default: null

Error message to respond with.

Usually set via the various fail builders and functions, and not used if passed is true.

passedType: BooleanDefault: true

Whether this check is currently passing, which is also the default state.

Usually set via the various pass and fail builders and functions.

Validation Contexts​

All validate {} builders use ValidationContext as their receiver type. This type provides the same CheckContext API surface, with some extras.

class ValidationContext : CheckContext

Validation context type, containing everything you need to write your own validators.

Type Parameters
out T

Generic type representing the type of the command argument's value.

Constructor Arguments
val converterType: Converter

Converter used to generate the current argument's value.

val valueType: T

The current argument's value.

val contextType: CommandContext

The command context representing the command invocation triggering this validator.

localeType: Locale

Locale for the current event, retrieved via your bot's locale resolvers.

Show/Hide Internal APIs
getMessageKey(...)

Get a pre-translation Key representing the current failure message, provided the validator is failing.

If message is null, this returns a default error message. Returns null if the validator is passing.

throwIfFailed(...)

If this validator is failing, throws a DiscordRelayedException with the value returned by getMessageKey(),.

If the value returned by getMessageKey() is null, this function throws an IllegalStateException instead.