dgc

README

dgc

A DiscordGo command router with tons of useful features If you find any bugs or if you have a feature request, please tell me using an issue.

Basic example

This just shows a very basic example:

func main() {
    // Discord bot logic here
    session, _ := ...

    // Create a new command router
    router := dgc.Create(&dgc.Router{
        Prefixes: []string{"!"},
    })

    // Register a simple ping command
    router.RegisterCmd(&dgc.Command{
        Name: "ping",
        Description: "Responds with 'pong!'",
        Usage: "ping",
        Example: "ping",
        IgnoreCase: true,
        Handler: func(ctx *dgc.Ctx) {
            ctx.RespondText("Pong!")
        },
    })

    // Initialize the router
    router.Initialize(session)
}

Usage

You can find examples for the more complex usage and all the integrated features in the examples/*.go files.

Arguments

To find out how you can use the integrated argument parser, just look into the examples/arguments.go file.

Documentation

Index

• Variables
• type Argument
  • func (argument *Argument) AsBool() (bool, error)
  • func (argument *Argument) AsChannelMentionID() string
  • func (argument *Argument) AsDuration() (time.Duration, error)
  • func (argument *Argument) AsInt() (int, error)
  • func (argument *Argument) AsInt64() (int64, error)
  • func (argument *Argument) AsRoleMentionID() string
  • func (argument *Argument) AsUserMentionID() string
  • func (argument *Argument) Raw() string
• type Arguments
  • func ParseArguments(raw string) *Arguments
  • func (arguments *Arguments) Amount() int
  • func (arguments *Arguments) AsCodeblock() *Codeblock
  • func (arguments *Arguments) AsSingle() *Argument
  • func (arguments *Arguments) Get(n int) *Argument
  • func (arguments *Arguments) Raw() string
  • func (arguments *Arguments) Remove(n int)
• type Codeblock
• type Command
  • func (command *Command) GetSubCmd(name string) *Command
  • func (command *Command) NotifyRateLimiter(ctx *Ctx) bool
• type Ctx
  • func (ctx *Ctx) RespondEmbed(embed *discordgo.MessageEmbed) error
  • func (ctx *Ctx) RespondText(text string) error
  • func (ctx *Ctx) RespondTextEmbed(text string, embed *discordgo.MessageEmbed) error
• type DefaultRateLimiter
  • func (rateLimiter *DefaultRateLimiter) NotifyExecution(ctx *Ctx) bool
• type ExecutionHandler
• type Middleware
• type ObjectsMap
  • func (om *ObjectsMap) Delete(key string)
  • func (om *ObjectsMap) Get(key string) (interface{}, bool)
  • func (om *ObjectsMap) MustGet(key string) interface{}
  • func (om *ObjectsMap) Set(key string, val interface{})
• type RateLimiter
  • func NewRateLimiter(cooldown, cleanupInterval time.Duration, onRateLimited ExecutionHandler) RateLimiter
• type Router
  • func Create(router *Router) *Router
  • func (router *Router) GetCmd(name string) *Command
  • func (router *Router) Handler() func(*discordgo.Session, *discordgo.MessageCreate)
  • func (router *Router) Initialize(session *discordgo.Session)
  • func (router *Router) InitializeStorage(name string)
  • func (router *Router) RegisterCmd(command *Command)
  • func (router *Router) RegisterDefaultHelpCommand(session *discordgo.Session, rateLimiter RateLimiter)
  • func (router *Router) RegisterMiddleware(middleware Middleware)

Variables

var (
	// RegexArguments defines the regex the argument string has to match
	RegexArguments = regexp.MustCompile("(\"[^\"]+\"|[^\\s]+)")

	// RegexUserMention defines the regex a user mention has to match
	RegexUserMention = regexp.MustCompile("<@!?(\\d+)>")

	// RegexRoleMention defines the regex a role mention has to match
	RegexRoleMention = regexp.MustCompile("<@&(\\d+)>")

	// RegexChannelMention defines the regex a channel mention has to match
	RegexChannelMention = regexp.MustCompile("<#(\\d+)>")

	// RegexBigCodeblock defines the regex a big codeblock has to match
	RegexBigCodeblock = regexp.MustCompile("(?s)\\n*```(?:([\\w.\\-]*)\\n)?(.*)```")

	// RegexSmallCodeblock defines the regex a small codeblock has to match
	RegexSmallCodeblock = regexp.MustCompile("(?s)\\n*`(.*)`")

	// CodeblockLanguages defines which languages are valid codeblock languages
	CodeblockLanguages = []string{}/* 315 elements not displayed */

)

Types

type Argument

type Argument struct {
	// contains filtered or unexported fields
}

Argument represents a single argument

func (*Argument) AsBool

func (argument *Argument) AsBool() (bool, error)

AsBool parses the given argument into a boolean

func (*Argument) AsChannelMentionID

func (argument *Argument) AsChannelMentionID() string

AsChannelMentionID returns the ID of the mentioned channel or an empty string if it is no mention

func (*Argument) AsDuration

func (argument *Argument) AsDuration() (time.Duration, error)

AsDuration parses the given argument into a duration

func (*Argument) AsInt

func (argument *Argument) AsInt() (int, error)

AsInt parses the given argument into an int32

func (*Argument) AsInt64

func (argument *Argument) AsInt64() (int64, error)

AsInt64 parses the given argument into an int64

func (*Argument) AsRoleMentionID

func (argument *Argument) AsRoleMentionID() string

AsRoleMentionID returns the ID of the mentioned role or an empty string if it is no mention

func (*Argument) AsUserMentionID

func (argument *Argument) AsUserMentionID() string

AsUserMentionID returns the ID of the mentioned user or an empty string if it is no mention

func (*Argument) Raw

func (argument *Argument) Raw() string

Raw returns the raw string value of the argument

type Arguments

type Arguments struct {
	// contains filtered or unexported fields
}

Arguments represents the arguments that may be used in a command context

func ParseArguments

func ParseArguments(raw string) *Arguments

ParseArguments parses the raw string into several arguments

func (*Arguments) Amount

func (arguments *Arguments) Amount() int

Amount returns the amount of given arguments

func (*Arguments) AsCodeblock

func (arguments *Arguments) AsCodeblock() *Codeblock

AsCodeblock parses the given arguments as a codeblock

func (*Arguments) AsSingle

func (arguments *Arguments) AsSingle() *Argument

AsSingle parses the given arguments as a single one

func (*Arguments) Get

func (arguments *Arguments) Get(n int) *Argument

Get returns the n'th argument

func (*Arguments) Raw

func (arguments *Arguments) Raw() string

Raw returns the raw string value of the arguments

func (*Arguments) Remove

func (arguments *Arguments) Remove(n int)

Remove removes the n'th argument

type Codeblock

type Codeblock struct {
	Language string
	Content  string
}

Codeblock represents a Discord codeblock

type Command

type Command struct {
	Name        string
	Aliases     []string
	Description string
	Usage       string
	Example     string
	Flags       []string
	IgnoreCase  bool
	SubCommands []*Command
	RateLimiter RateLimiter
	Handler     ExecutionHandler
}

Command represents a simple command

func (*Command) GetSubCmd

func (command *Command) GetSubCmd(name string) *Command

GetSubCmd returns the sub command with the given name if it exists

func (*Command) NotifyRateLimiter

func (command *Command) NotifyRateLimiter(ctx *Ctx) bool

NotifyRateLimiter notifies the rate limiter about a new execution and returns false if the user is being rate limited

type Ctx

type Ctx struct {
	Session       *discordgo.Session
	Event         *discordgo.MessageCreate
	Arguments     *Arguments
	CustomObjects *ObjectsMap
	Router        *Router
	Command       *Command
}

Ctx represents the context for a command event

func (*Ctx) RespondEmbed

func (ctx *Ctx) RespondEmbed(embed *discordgo.MessageEmbed) error

RespondEmbed responds with the given embed message

func (*Ctx) RespondText

func (ctx *Ctx) RespondText(text string) error

RespondText responds with the given text message

func (*Ctx) RespondTextEmbed

func (ctx *Ctx) RespondTextEmbed(text string, embed *discordgo.MessageEmbed) error

RespondTextEmbed responds with the given text and embed message

type DefaultRateLimiter

type DefaultRateLimiter struct {
	Cooldown           time.Duration
	RateLimitedHandler ExecutionHandler
	// contains filtered or unexported fields
}

DefaultRateLimiter represents an internal rate limiter

func (*DefaultRateLimiter) NotifyExecution

func (rateLimiter *DefaultRateLimiter) NotifyExecution(ctx *Ctx) bool

NotifyExecution notifies the rate limiter about a new execution and returns whether or not the execution is allowed

type ExecutionHandler

type ExecutionHandler func(*Ctx)

ExecutionHandler represents a handler for a context execution

type Middleware

type Middleware func(following ExecutionHandler) ExecutionHandler

Middleware defines how a middleware looks like

type ObjectsMap

type ObjectsMap struct {
	// contains filtered or unexported fields
}

ObjectsMap wraps a map[string]interface to provide thread safe access endpoints.

func (*ObjectsMap) Delete

func (om *ObjectsMap) Delete(key string)

Delete removes a key-value pair from the map.

func (*ObjectsMap) Get

func (om *ObjectsMap) Get(key string) (interface{}, bool)

Get tries to get a value from the map. If a value was found, the value and true is returned. Else, nil and false is returned.

func (*ObjectsMap) MustGet

func (om *ObjectsMap) MustGet(key string) interface{}

MustGet wraps Get but only returns the value, if found, or nil otherwise.

func (*ObjectsMap) Set

func (om *ObjectsMap) Set(key string, val interface{})

Set sets a value to the map by key.

type RateLimiter

type RateLimiter interface {
	NotifyExecution(*Ctx) bool
}

RateLimiter represents a general rate limiter

func NewRateLimiter

func NewRateLimiter(cooldown, cleanupInterval time.Duration, onRateLimited ExecutionHandler) RateLimiter

NewRateLimiter creates a new rate limiter

type Router

type Router struct {
	Prefixes         []string
	IgnorePrefixCase bool
	BotsAllowed      bool
	Commands         []*Command
	Middlewares      []Middleware
	PingHandler      ExecutionHandler
	Storage          map[string]*ObjectsMap
}

Router represents a DiscordGo command router

func Create

func Create(router *Router) *Router

Create makes sure all maps get initialized

func (*Router) GetCmd

func (router *Router) GetCmd(name string) *Command

GetCmd returns the command with the given name if it exists

func (*Router) Handler

func (router *Router) Handler() func(*discordgo.Session, *discordgo.MessageCreate)

Handler provides the discordgo handler for the given router

func (*Router) Initialize

func (router *Router) Initialize(session *discordgo.Session)

Initialize initializes the message event listener

func (*Router) InitializeStorage

func (router *Router) InitializeStorage(name string)

InitializeStorage initializes a storage map

func (*Router) RegisterCmd

func (router *Router) RegisterCmd(command *Command)

RegisterCmd registers a new command

func (*Router) RegisterDefaultHelpCommand

func (router *Router) RegisterDefaultHelpCommand(session *discordgo.Session, rateLimiter RateLimiter)

RegisterDefaultHelpCommand registers the default help command

func (*Router) RegisterMiddleware

func (router *Router) RegisterMiddleware(middleware Middleware)

RegisterMiddleware registers a new middleware