dimscmd
dimscmd copied to clipboard
A command handler for dimscord
Dimscord Command Handler
.. image:: https://github.com/ire4ever1190/dimscmd/workflows/Tests/badge.svg :alt: Test status
This is built on top of the amazing dimscord library <https://github.com/krisppurg/dimscord>
_ so if you have any questions about using dimscord or dimscmd then join the dimscord discord <https://discord.com/invite/dimscord>
_ (please send questions about dimscmd in the #dimscmd channel)
Docs available here <https://ire4ever1190.github.io/dimscmd/dimscmd>
_
Install
.. code-block::
nimble install dimscmd
Setup
First create the handler object
.. code-block:: nim
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
.. code-block:: nim
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
.. code-block:: nim
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
.. code-block:: nim
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
.. code-block:: nim
cmd.addChat("sum") do (nums: seq[int]):
var sum = 0
for num in nums:
sum += num
discard await discord.api.sendMessage(m.channelID, $sum)
.. code-block:: nim
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
.. code-block:: nim
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
.. code-block:: nim
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
.. code-block:: nim
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)
.. code-block:: nim
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
...