Converter Basics

Converters are responsible for converting command arguments from their basic (usually String) representations into rich types. They're a core part of Kord Extensions' command system, allowing you to focus on getting your bot working without worrying about parsing logic.

Each converter is a class extending the Converter type, and annotated with the @Converter annotation. You can read the custom converters page for more information on converter anatomy, but for now you should understand that converters can:

• Parse String-based values.
• Transform entities and Snowflakes received from Discord.
• Wrap other converters to change their behaviour.

Usage

You can create a converter using the corresponding builder functions, available in your Arguments subtype, which you'll need to create to handle command arguments. Builder functions have descriptive names based on the corresponding converter's name, and the behaviour you should expect from them.

Default Behaviour

The default behaviour type is single, which represents a single, mandatory argument. Builder functions don't have anything special in their names to denote this, as it is the default.

You can modify argument expectations and behaviour using builder functions that reference other argument types.

Optional Types

You can make arguments optional by specifying their defaulting or optional variants. Optional arguments default to null when not provided, while defaulting arguments let you provide your own default value.

Multiple Inputs

Chat commands only!

As of this writing, while you can use these argument types with slash commands, they can only process and return a single value. This is because Discord lacks any real way to provide an argument with multiple values.

If you do use these argument types with slash commands, please note that they will only ever resolve a single value. For list converters, this value is a List<T> with one element.

You can make arguments consume or output multiple inputs by specifying their coalescing or list variants.

Coalescing arguments are meant for use with chat commands, allowing your bot to combine multiple arguments into a single value. This is helpful when you want to make it easier to provide arguments containing spaces without requiring quoting, but remember that coalescing arguments consume as many arguments as possible until the next value would make argument data invalid.

List arguments are also meant for use with chat commands, but instead of combining arguments into a single value, they place them into a list. However, like coalescing arguments, list arguments consume as many arguments as possible until the next value would be an invalid argument.

Limited Inputs

You can limit the values accepted by an argument by specifying the choice variant.

Choice arguments include a limited set of pre-set possible values, and they respond with an error when users provide other values.

When used with slash commands, Discord shows the first 25 acceptable values to the user.

Configuration

You can configure a converter via the builder functions it provides. While some converters may support special configuration functions and properties, all converters support a common set of options.

Shared Settings

Required Settings

var nameType: key

Translation key representing this argument's name.

Should be short, lowered-kebab-case, and without spaces.

var descriptionType: key

Translation key representing this argument's description.

Should be descriptive, but try to avoid making it too long.

---

Optional Settings

autoComplete { ... }Receiver: AutoCompleteInteraction

Register the auto-complete callback for this argument. Use the APIs provided by the AutoCompleteInteraction object to check the provided partial argument, and respond with some options.

Extra APIs are available to help with this, which you can read about on the interaction utils page (TODO).

Lambda Arguments

eventType: AutoCompleteInteractionCreateEvent

The event that triggered the auto-completion interaction.

mutate { ... }Receiver: CommandContextLambda Returns: T

Register the mutator for this argument. A mutator takes the final result of an argument conversion, and either returns that value or a new one based on it.

The generic type T represents the argument value's type. A mutator may only return the same type.

Lambda Arguments

valueType: T

The value to mutate.

validate { ... }Receiver: ValidationContext

Register the validator for this argument. A validator examines the final result of an argument conversion, and may decide to cause a parsing failure via the fail() function.

The API matches the one provided by check contexts, but with some additional properties. The generic type T represents the argument value's type.

val contextType: CommandContext

The command context that triggered this validation.

val converterType: Converter

The current converter object.

val valueType: T

The value to examine.

Settings: Choice Converters

Choice converter builders additionally extend ChoiceConverterBuilder, providing an API that allows you to define what the possible choices are. Choices have a human-readable component, represented by a Key object, which your bot will translate using its locale resolvers.

The generic type T below represents the argument value's type.

choice(...)

Add a single choice to the collection of possible choices.

Arguments

keyType: Key

Translation key, used to display the name of the choice on Discord.

valueType: T

Corresponding value, used as the argument's value when a user selects this choice.

choices(...)

Add multiple choices to the collection of possible choices.

Arguments

allType: Map<Key, T>

Collection of possible choices to add.

var choicesType: MutableMap<Key, T>

The collection of possible choices, which you can mutate directly if needed.

Settings: Coalescing Converters

Coalescing converter builders extend CoalescingConverterBuilder, instead of directly extending ConverterBuilder.

There may be situations where you'd like to decide whether your coalescing converter should respond with an error when it can't parse any values, and this builder type provides a property for that.

var ignoreErrorsType: BooleanDefault: true

Whether to ignore parsing errors when no values can be parsed.

If your argument should always require a value, set this to false.

Settings: Defaulting Converters

Defaulting converter builders extend DefaultingConverterBuilder, instead of directly extending ConverterBuilder. This type provides an API you can use to specify a default value, and what should happen when arguments fail to parse.

The generic type T below represents the argument value's type.

Required Settings

var defaultValueType: T

The default value to use when a user doesn't provide one, or when parsing fails and ignoreErrors is true.

---

Optional Settings

var ignoreErrorsType: BooleanDefault: false

Whether to use the default value when parsing fails.

Set this to true to ignore parsing errors, and use the default value instead.

Settings: List Converters

List converter builders extend ListConverterBuilder, instead of directly extending ConverterBuilder.

There may be situations where you'd like to decide whether your list converter should respond with an error when it can't parse any values, and this builder type provides a property for that.

var ignoreErrorsType: BooleanDefault: true

Whether to ignore parsing errors when no values can be parsed.

If your argument should always require a value, set this to false.

Settings: Optional Converters

List converter builders extend OptionalConverterBuilder, instead of directly extending ConverterBuilder.

There may be situations where you'd like to decide whether your optional converter should respond with an error when it can't parse any values, and this builder type provides a property for that.

var ignoreErrorsType: BooleanDefault: false

Whether to ignore parsing errors when no values can be parsed.

Set this to true to ignore parsing errors, and use null instead.

Note: Combined Converters

Coalescing converters created using the defaulting or optional builder variants are represented using their own builder types — DefaultingCoalescingConverterBuilder and OptionalCoalescingConverterBuilder. These builder types don't extend the DefaultingConverterBuilder or OptionalConverterBuilder types, but they still have the same API.

These types work as you'd expect, but note that while the ignoreErrors property defaults to true for coalescing converters, it defaults to false for the defaulting and optional variants.