dcli

README

dcli

A command line interface framework for discord bots written in Go.

Documentation

Index

• Constants
• type Arg
  • func BoolArg(name string) Arg
  • func ChannelMentionArg(name string) Arg
  • func Float32Arg(name string, min *float32, max *float32) Arg
  • func Float64Arg(name string, min *float64, max *float64) Arg
  • func IntArg(name string, min *int, max *int) Arg
  • func RoleMentionArg(name string) Arg
  • func StringArg(name string, minLength *int, maxLength *int) Arg
  • func UserMentionArg(name string) Arg
• type Command
• type CommandSystem
  • func CompileCommands(name string, commands ...Command) (*CommandSystem, error)
  • func (cs *CommandSystem) Exec(cmd string, m *discordgo.Message, s *discordgo.Session) error
• type Exec
  • func (e *Exec) GetBoolArg(name string) (bool, error)
  • func (e *Exec) GetChannelMentionArg(name string) (string, error)
  • func (e *Exec) GetFloat32Arg(name string) (float32, error)
  • func (e *Exec) GetFloat64Arg(name string) (float64, error)
  • func (e *Exec) GetIntArg(name string) (int, error)
  • func (e *Exec) GetRoleMentionArg(name string) (string, error)
  • func (e *Exec) GetStringArg(name string) (string, error)
  • func (e *Exec) GetUserMentionArg(name string) (string, error)
• type Permission
  • func PermissionAnd(permissions ...Permission) Permission
  • func PermissionChannel(channelID string) Permission
  • func PermissionGuild(guildID string) Permission
  • func PermissionGuildRole(guildID, roleID string) Permission
  • func PermissionGuildRoleSafe(guildID, roleID string) Permission
  • func PermissionOr(permissions ...Permission) Permission
  • func PermissionUser(userID string) Permission
  • func TextPermission(permission textPermissionEnum) Permission

Constants

const (
	// TextPermissionCreateInstantInvite allows creation of instant invites
	TextPermissionCreateInstantInvite = textPermissionEnum(0x00000001)
	// TextPermissionKickMembers allows kicking members
	TextPermissionKickMembers = textPermissionEnum(0x00000002)
	// TextPermissionBanMembers allows banning members
	TextPermissionBanMembers = textPermissionEnum(0x00000004)
	// TextPermissionAdministrator allows all permissions and bypasses channel permission overwrites
	TextPermissionAdministrator = textPermissionEnum(0x00000008)
	// TextPermissionManageChannels allows management and editing of channels
	TextPermissionManageChannels = textPermissionEnum(0x00000010)
	// TextPermissionManageGuild allows management and editing of the guild
	TextPermissionManageGuild = textPermissionEnum(0x00000020)
	// TextPermissionAddReaction allows for the addition of reactions to messages
	TextPermissionAddReaction = textPermissionEnum(0x00000040)
	// TextPermissionViewAuditLog allows for viewing of audit logs
	TextPermissionViewAuditLog = textPermissionEnum(0x00000080)
	// TextPermissionViewChannel allows guild members to view a channel, which includes reading messages in text channels
	TextPermissionViewChannel = textPermissionEnum(0x00000400)
	// TextPermissionSendMessages allows for sending messages in a channel
	TextPermissionSendMessages = textPermissionEnum(0x00000800)
	// TextPermissionSendTtsMessages allows for sending of /tts messages
	TextPermissionSendTtsMessages = textPermissionEnum(0x00001000)
	// TextPermissionManageMessages allows for deletion of other users messages
	TextPermissionManageMessages = textPermissionEnum(0x00002000)
	// TextPermissionEmbedLinks ainks sent by users with this permission will be auto-embedded
	TextPermissionEmbedLinks = textPermissionEnum(0x00004000)
	// TextPermissionAttachFiles allows for uploading images and files
	TextPermissionAttachFiles = textPermissionEnum(0x00008000)
	// TextPermissionReadMessageHistory allows for reading of message history
	TextPermissionReadMessageHistory = textPermissionEnum(0x00010000)
	// TextPermissionMentionEveryone allows for using the @everyone tag to notify all users in a channel, and the @here tag to notify all online users in a channel
	TextPermissionMentionEveryone = textPermissionEnum(0x00020000)
	// TextPermissionUseExternalEmojis allows the usage of custom emojis from other servers
	TextPermissionUseExternalEmojis = textPermissionEnum(0x00040000)
	// TextPermissionChangeNickname allows for modification of own nickname
	TextPermissionChangeNickname = textPermissionEnum(0x04000000)
	// TextPermissionManageNicknames allows for modification of other users nicknames
	TextPermissionManageNicknames = textPermissionEnum(0x08000000)
	// TextPermissionManageRoles allows management and editing of roles
	TextPermissionManageRoles = textPermissionEnum(0x10000000)
	// TextPermissionManageWebhooks allows management and editing of webhooks
	TextPermissionManageWebhooks = textPermissionEnum(0x20000000)
	// TextPermissionManageEmojis allows management and editing of emojis
	TextPermissionManageEmojis = textPermissionEnum(0x40000000)
)

Types

type Arg

type Arg interface {
	// contains filtered or unexported methods
}

Arg takes a string value and parses it into whatever type the interface implimentation is for E.g. int, float32, bool, etc

func BoolArg

func BoolArg(name string) Arg

BoolArg creates an argument of type bool

func ChannelMentionArg

func ChannelMentionArg(name string) Arg

ChannelMentionArg creates an argument for discord channel mentions

func Float32Arg

func Float32Arg(name string, min *float32, max *float32) Arg

Float32Arg creates an argument of type float32 min and max are pointers so that they can be assignmed the value nil, in which case they will be ignored

func Float64Arg

func Float64Arg(name string, min *float64, max *float64) Arg

Float64Arg creates an argument of type float64 min and max are pointers so that they can be assignmed the value nil, in which case they will be ignored

func IntArg

func IntArg(name string, min *int, max *int) Arg

IntArg creates an argument of type integer min and max are pointers so that they can be assignmed the value nil, in which case they will be ignored

func RoleMentionArg

func RoleMentionArg(name string) Arg

RoleMentionArg creates an argument for discord role mentions

func StringArg

func StringArg(name string, minLength *int, maxLength *int) Arg

StringArg creates an argument of type string minLength and maxLength are pointers so that they can be assignmed the value nil, in which case they will be ignored

func UserMentionArg

func UserMentionArg(name string) Arg

UserMentionArg creates an argument for discord user mentions

type Command

type Command struct {
	// Name is the identifier of the command
	// No whitespace or non-alphabetic characters
	// should be present within Name
	Name string
	// Args is the list of arguments the command
	// must be provided with the be executed
	Args []Arg
	// Permissions is a collection of permissions
	// which can authorize the execution of the command
	Permissions []Permission
	// SubCommands is the list of commands that are
	// parented by this command
	SubCommands []Command
	// Func is the function that is ran when the
	// command is called
	// Func can be nil (Usually desired if a command
	// is used to simply group sub commands together)
	Func func(*Exec) error
}

Command represents a callable command

type CommandSystem

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

CommandSystem is a collection of commands that have been compiled together Commands must be compiled into a CommandSystem before they can be executed

func CompileCommands

func CompileCommands(name string, commands ...Command) (*CommandSystem, error)

CompileCommands creates a command system by grouping a set of commands together Throughout the process of adding commands to the system, each command and its features are checked and validated

Do NOT use the same command object for multiple CompileCommands calls, the Args of the command will be referenced in two different command systems with seperate mutexes

func (*CommandSystem) Exec

func (cs *CommandSystem) Exec(cmd string, m *discordgo.Message, s *discordgo.Session) error

Exec parses a command string into command identifier and args then executes the respective command, passing in the args

type Exec

type Exec struct {
	// Message is the discord message that called
	// the command
	Message *discordgo.Message
	// Session is the discord session that listens
	// for and handles command calls
	Session *discordgo.Session
	// contains filtered or unexported fields
}

Exec holds information that give context to a command execution call

func (*Exec) GetBoolArg

func (e *Exec) GetBoolArg(name string) (bool, error)

GetBoolArg gets the boolean value of a boolean argument provided by a user during the command execution call

func (*Exec) GetChannelMentionArg

func (e *Exec) GetChannelMentionArg(name string) (string, error)

GetChannelMentionArg gets the channel id of a channel mention argument provided by a user during the command execution call

func (*Exec) GetFloat32Arg

func (e *Exec) GetFloat32Arg(name string) (float32, error)

GetFloat32Arg gets the float32 value of a float32 argument provided by a user during the command execution call

func (*Exec) GetFloat64Arg

func (e *Exec) GetFloat64Arg(name string) (float64, error)

GetFloat64Arg gets the float64 value of a float64 argument provided by a user during the command execution call

func (*Exec) GetIntArg

func (e *Exec) GetIntArg(name string) (int, error)

GetIntArg gets the integer value of an integer argument provided by a user during the command execution call

func (*Exec) GetRoleMentionArg

func (e *Exec) GetRoleMentionArg(name string) (string, error)

GetRoleMentionArg gets the role id of a role mention argument provided by a user during the command execution call

func (*Exec) GetStringArg

func (e *Exec) GetStringArg(name string) (string, error)

GetStringArg gets the string value of a string argument provided by a user during the command execution call

func (*Exec) GetUserMentionArg

func (e *Exec) GetUserMentionArg(name string) (string, error)

GetUserMentionArg gets the user id of a user mention argument provided by a user during the command execution call

type Permission

type Permission func(*Exec) (bool, error)

Permission is a function that is used to authorise the execution of a command from an execution context

func PermissionAnd

func PermissionAnd(permissions ...Permission) Permission

PermissionAnd combines multiple permission checks into one permission check where all have to pass

func PermissionChannel

func PermissionChannel(channelID string) Permission

PermissionChannel creates a permission which passes if the channel the command is executed from has the specified id

func PermissionGuild

func PermissionGuild(guildID string) Permission

PermissionGuild creates a permission which passes if the guild the command is executed from has the specified id

func PermissionGuildRole

func PermissionGuildRole(guildID, roleID string) Permission

PermissionGuildRole creates a permission which passes if the user executing the command has the specified role

It is recommended to use PermissionGuildRoleSafe over PermissionGuildRole as it also checks if the user is executing the command from within the guild they have their role in

Make sure you know what this means before using it

func PermissionGuildRoleSafe

func PermissionGuildRoleSafe(guildID, roleID string) Permission

PermissionGuildRoleSafe creates a permission which passes if the user executing the command has the specified role

It is recommended over PermissionGuildRole as it also checks if the user is executing the command from within the guild they have their role in

func PermissionOr

func PermissionOr(permissions ...Permission) Permission

PermissionOr combines multiple permission checks into one permission check where only one has to pass

func PermissionUser

func PermissionUser(userID string) Permission

PermissionUser creates a permission which passes if the user executing the command has the specified id

func TextPermission

func TextPermission(permission textPermissionEnum) Permission

TextPermission creates a permission which passes if the user has the specified text permission within the channel they're executing from Note this function does check that all permissions described in the permission parameter For example: `TextPermissionManageRoles | TextPermissionManageNicknames` to check if a user has both of these text permissions