From 08ffade13dd7291222d0a905ed214762c63f3e67 Mon Sep 17 00:00:00 2001 From: jake Date: Sun, 8 Jun 2025 02:26:06 -0400 Subject: [PATCH] [chore] comments and function scope - methods no longer exported if not used - readme update - comments updated --- README.md | 28 +++++++++++++++++++++++----- bolt.go | 10 +++++----- command.go | 14 +++++++------- 3 files changed, 35 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 9736dda..c12adea 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,30 @@ # bolt -Base Discord bot framework +The nuts and bolts of a Discord bots. Bolt is a wrapper for [discordgo](https://github.com/bwmarrin/discordgo) that provides very quick bootstrapping for simple Discord bots. -## Introduction -bolt is a wrapper for Discordgo to provide very quick and easy setup for simple Discord bots. The only code required to run bolt are the command handler functions, this provides developers with the ability to have text-based commands on a Discord server without all the bootstrapping and setup usually required. Any strings returned from the Payload function will be sent back to the Discord server as a reply to the command message. +## Usage +### Token +Bolt requires a Discord bot token to run, the token must be set as an environment variable labeled "DISCORD_TOKEN" -## Basic Usage -bolt allows developers to create a Discord bot with a discord bot token and a few lines of Go code, discord tokens must be set as an environment variable labeled DISCORD_TOKEN. The below example creates a Discord bot and registers three commands: ".ping", ".time", and ".role" the "." character is the default command indicator but that can be changed using the WithIndicator option. +### Commands +Commands are represented by the Command struct. Any roles in the Command struct can run the command, if the Roles field is empty anyone can run the command. +```go +type Command struct { + Trigger string //command that triggers payload NOT including the indicator + Payload Payload //payload function to run when a command is detected + Timeout time.Duration //the amount of time before command can be run again + lastRun time.Time //timestamp of last command run + Roles []string //roles that can use command, if none are set anyone can run the command +} +``` + +### Payload +Payload functions are executed when a command is detected, if no errors are returned and the returned string is not empty, then the returned string is sent in reply to the command message. +```go +type Payload func(msg Message) (string, error) +``` + +### Example ```go package main diff --git a/bolt.go b/bolt.go index 5a0a2b8..152405c 100644 --- a/bolt.go +++ b/bolt.go @@ -26,7 +26,7 @@ const ( // basic bot structure containing discordgo connection as well as the command map type bolt struct { *dg.Session //holds discordgo internals - Commands map[string]Command //maps trigger phrase to command struct for fast lookup + commands map[string]Command //maps trigger phrase to command struct for fast lookup indicator string //the indicator used to detect whether a message is a command } @@ -62,7 +62,7 @@ func New(opts ...Option) Bolt { b := &bolt{ Session: bot, - Commands: make(map[string]Command, 0), + commands: make(map[string]Command, 0), } //set default command indicator b.indicator = "." @@ -106,7 +106,7 @@ func (b *bolt) stop() error { // adds commands to bot command map for use func (b *bolt) AddCommands(cmd ...Command) { for _, c := range cmd { - b.Commands[c.Trigger] = c + b.commands[c.Trigger] = c } } @@ -152,7 +152,7 @@ func (b *bolt) messageHandler(s *dg.Session, msg *dg.MessageCreate) { // parses command from message and handles timeout checks, role checks, and command execution. All command responses are sent back to Discord func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Guild, channel *dg.Channel, lg int) error { words := strings.Split(msg.Content, " ") - run, ok := b.Commands[words[0][lg:]] + run, ok := b.commands[words[0][lg:]] if !ok { return nil //command doesn't exist, maybe log or respond to author } @@ -201,7 +201,7 @@ func (b *bolt) handleCommand(msg *dg.MessageCreate, s *dg.Session, server *dg.Gu //update run time run.lastRun = time.Now() - b.Commands[run.Trigger] = run + b.commands[run.Trigger] = run return nil } diff --git a/command.go b/command.go index 5793f31..3c6b6dc 100644 --- a/command.go +++ b/command.go @@ -2,23 +2,23 @@ package bolt import "time" +// custom Discord commands type Command struct { Trigger string //command that triggers payload NOT including the indicator Payload Payload //payload function to run when a command is detected - Timeout time.Duration //the amount of time before command can run again + Timeout time.Duration //the amount of time before command can be run again lastRun time.Time //timestamp of last command run - Roles []string //roles that can use command + Roles []string //roles that can use command, if none are set anyone can run the command } -// payload function type handling commands. The returned error is parsed and, if no error, -// is detected then the response string (res) will be sent in response to the command message +// command payload functions, any strings returned are sent as a response to the command type Payload func(msg Message) (string, error) -// contains the basic information needed for a message command +// message information passed to payload function type Message struct { Author string //username of message author Words []string //words from message split on whitespace Content string //entire message content - Channel string //channel message was sent in - Server string //guild message was sent in + Channel string //message channel + Server string //message guild }