readme.rst

Dimscord Command Handler

This is built on top of the amazing dimscord library so if you have any questions about using dimscord or dimscmd then join the dimscord discord (please send questions about dimscmd in the #dimscmd channel)

Docs available here

Install

nimble install dimscmd

Setup

First create the handler object

import dimscord
import dimscmd
let discord = newDiscordClient(token)
var cmd = discord.newHandler() # Must be var

Then add the handler into your message_create event using handleMessage() proc. It is in this proc that you can define the prefix (or prefixes) that you want the bot to handle

proc messageCreate (s: Shard, msg: Message) {.event(discord).} =
    discard await cmd.handleMessage("$$", s, msg) # Returns true if a command was handled
    # You can also pass in a list of prefixes
    # discard await cmd.handleMessage(@["$$", "&"], s, msg)

Use

Commands are created using Nim's do notation

cmd.addChat("ping") do ():
    discard await discord.api.sendMessage(msg.channelID, "pong") # Message is passed to the proc as msg

# If msg is not to your fancy then you can change it
cmd.addChat("ping") do (m: Message):
    discard await discord.api.sendMessage(m.channelID, "pong")

But you are probably wondering "can I add parameters to my commands?" and the answer is yes and it is very easy. Just add parameters to the signature and you're off

cmd.addChat("echo") do (word: string):
    discard await discord.api.sendMessage(m.channelID, word)

# You can add as many types as you want
cmd.addChat("repeat") do (word: string, times: int):
    for i in 0..<times:
        discard await discord.api.sendMessage(m.channelID, word)

Current supported types are (don't think you want any other types)

• string
• bool
• int
• enums
• discord user
• discard channel
• discord role

seq[T] and Option[T] for those types are also supported

cmd.addChat("sum") do (nums: seq[int]):
    var sum = 0
    for num in nums:
        sum += num
    discard await discord.api.sendMessage(m.channelID, $sum)

cmd.addChat("kill") do (user: Option[User]):
    if user.isSome():
        discard await discord.api.sendMessage(msg.channelID, "Killing them...")
        # TODO, see if this is legal before implementing.
    else:
        discard await discord.api.sendMessage(msg.channelID, "I can't kill nobody")

Dimscmd does do other stuff like generate a help message automatically when the user sends the message "help" after the prefix. This can be overrided by defining a help command yourself

cmd.addChat("help") do (commandName: Option[string]): # parameters can be whatever you want
    if commandName.isSome():
        # Send help message for that command
    else:
        # Say something helpful

Slash commands

Slash commands are also supported with this library and are declared in a similar fashion. There are some things to be mindful of though when using slash commands such as

• names cannot contain capital letters
• This library currently doesn't provide any help with creating interaction responses

First add the handler into the interaction create event like with messages and also add the command register into the on ready event

proc onReady (s: Shard, r: Ready) {.event(discord).} =
    await cmd.registerCommands()

proc interactionCreate (s: Shard, i: Interaction) {.event(discord).} =
    discard await cmd.handleInteraction(s, i)

Then add your slash commands

cmd.addSlash("add") do (a: int, b: int):
    ## Adds two numbers
    await discord.api.interactionResponseMessage(i.id, i.token,
        kind = irtChannelMessageWithSource,
        response = InteractionCallbackDataMessage(
            content: fmt"{a} + {b} = {a + b}"
        )
    )

Slash commands support the types supported (including enums) with the exception of seq[T]

During testing it is recommend that you set a specific guild so that slash commands will be registered instantly (instead of waiting an hour for them to be register globally)

cmd.addSlash("add", guildID = "123456789") do (a: int, b: int):
    ## Adds to numbers
    ...

# I recommend setting up something like this
when defined(debug):
    const defaultGuildID = "3456789"
else:
    const defaultGuildID = "" # Global

# This will set the default guild for all slash commands
let cmd = discord.newHandler(defaultGuildID = defaultGuildID)

cmd.addSlash("add") do (a: int, b: int):
    ## Adds to numbers
    ...