bot

README

What happened here?

We've moved everything to https://github.com/diamondburned/ak-rfrouter, as this package will be replaced with a go-chi style router.

Documentation

Index

• Constants
• Variables
• func Start(token string, cmd interface{}, opts func(*Context) error) (stop func() error, err error)
• func Wait()
• type Argument
• type CanSetup
• type CommandContext
  • func (cctx *CommandContext) Usage() []string
• type Context
  • func New(s *state.State, cmd interface{}) (*Context, error)
  • func (ctx *Context) Call(event interface{}) error
  • func (ctx *Context) FindCommand(structname, methodname string) *CommandContext
  • func (ctx *Context) Help() string
  • func (ctx *Context) MustRegisterSubcommand(cmd interface{}) *Subcommand
  • func (ctx *Context) RegisterSubcommand(cmd interface{}) (*Subcommand, error)
  • func (ctx *Context) Start() func()
  • func (ctx *Context) Subcommands() []*Subcommand
• type ErrInvalidUsage
  • func (err *ErrInvalidUsage) Error() string
• type ErrUnknownCommand
  • func (err *ErrUnknownCommand) Error() string
• type ManualParseable
• type NameFlag
  • func ParseFlag(name string) (NameFlag, string)
  • func (f NameFlag) Is(flag NameFlag) bool
• type Parseable
• type RawArguments
  • func (r *RawArguments) ParseContent(args []string) error
• type Subcommand
  • func NewSubcommand(cmd interface{}) (*Subcommand, error)
  • func (sub *Subcommand) ChangeCommandInfo(methodName, cmd, desc string) bool
  • func (sub *Subcommand) InitCommands(ctx *Context) error
  • func (sub *Subcommand) NeedsName()

Constants

const FlagSeparator = 'ー'

Variables

var ParseArgs = func(args string) ([]string, error) {

	r := csv.NewReader(strings.NewReader(args))
	r.Comma = ' '

	return r.Read()
}

Functions

func Start

func Start(token string, cmd interface{},
	opts func(*Context) error) (stop func() error, err error)

Start quickly starts a bot with the given command. It will prepend "Bot" into the token automatically. Refer to example/ for usage.

func Wait

func Wait()

Wait is a convenient function that blocks until a SIGINT is sent.

Types

type Argument

type Argument struct {
	String string
	Type   reflect.Type
	// contains filtered or unexported fields
}

Argument is each argument in a method.

type CanSetup

type CanSetup interface {
	// Setup should panic when it has an error.
	Setup(*Subcommand)
}

CanSetup is used for subcommands to change variables, such as Description. This method will be triggered when InitCommands is called, which is during New for Context and during RegisterSubcommand for subcommands.

type CommandContext

type CommandContext struct {
	Description string
	Flag        NameFlag

	MethodName string
	Command    string

	Arguments []Argument
	// contains filtered or unexported fields
}

CommandContext is an internal struct containing fields to make this library work. As such, they're all unexported. Description, however, is exported for editing, and may be used to generate more informative help messages.

func (*CommandContext) Usage

func (cctx *CommandContext) Usage() []string

type Context

type Context struct {
	*Subcommand
	*state.State

	// Descriptive (but optional) bot name
	Name string

	// Descriptive help body
	Description string

	// The prefix for commands
	Prefix string

	// FormatError formats any errors returned by anything, including the method
	// commands or the reflect functions. This also includes invalid usage
	// errors or unknown command errors. Returning an empty string means
	// ignoring the error.
	FormatError func(error) string

	// ErrorLogger logs any error that anything makes and the library can't
	// reply to the client. This includes any event callback errors that aren't
	// Message Create.
	ErrorLogger func(error)

	// ReplyError when true replies to the user the error.
	ReplyError bool
	// contains filtered or unexported fields
}

Context is the bot state for commands and subcommands.

A command can be created by making it a method of Commands, or whatever struct was given to the constructor. This following example creates a command with a single integer argument (which can be ran with "~example 123"):

func (c *Commands) Example(m *gateway.MessageCreateEvent, i int) error {
    _, err := c.Ctx.SendMessage(m.ChannelID, fmt.Sprintf("You sent: %d", i))
    return err
}

Commands' exported methods will all be used as commands. Messages are parsed with its first argument (the command) mapped accordingly to c.MapName, which capitalizes the first letter automatically to reflect the exported method name.

func New

func New(s *state.State, cmd interface{}) (*Context, error)

New makes a new context with a "~" as the prefix. cmds must be a pointer to a struct with a *Context field. Example:

type Commands struct {
    Ctx *Context
}

cmds := &Commands{}
c, err := rfrouter.New(session, cmds)

The default prefix is "~", which means commands must start with "~" followed by the command name in the first argument, else it will be ignored.

c.Start() should be called afterwards to actually handle incoming events.

func (*Context) Call

func (ctx *Context) Call(event interface{}) error

Call should only be used if you know what you're doing.

func (*Context) FindCommand

func (ctx *Context) FindCommand(structname, methodname string) *CommandContext

FindCommand finds a command based on the struct and method name. The queried names will have their flags stripped.

Example

// Find a command from the main context:
cmd := ctx.FindCommand("", "Method")
// Find a command from a subcommand:
cmd  = ctx.FindCommand("Starboard", "Reset")

func (*Context) Help

func (ctx *Context) Help() string

Help generates one. This function is used more for reference than an actual help message. As such, it only uses exported fields or methods.

func (*Context) MustRegisterSubcommand

func (ctx *Context) MustRegisterSubcommand(cmd interface{}) *Subcommand

MustRegisterSubcommand tries to register a subcommand, and will panic if it fails. This is recommended, as subcommands won't change after initializing once in runtime, thus fairly harmless after development.

func (*Context) RegisterSubcommand

func (ctx *Context) RegisterSubcommand(cmd interface{}) (*Subcommand, error)

RegisterSubcommand registers and adds cmd to the list of subcommands. It will also return the resulting Subcommand.

func (*Context) Start

func (ctx *Context) Start() func()

Start adds itself into the discordgo Session handlers. This needs to be run. The returned function is a delete function, which removes itself from the Session handlers.

func (*Context) Subcommands

func (ctx *Context) Subcommands() []*Subcommand

type ErrInvalidUsage

type ErrInvalidUsage struct {
	Args   []string
	Prefix string

	Index int
	Err   string
	// contains filtered or unexported fields
}

func (*ErrInvalidUsage) Error

func (err *ErrInvalidUsage) Error() string

type ErrUnknownCommand

type ErrUnknownCommand struct {
	Command string
	Parent  string

	Prefix string
	// contains filtered or unexported fields
}

func (*ErrUnknownCommand) Error

func (err *ErrUnknownCommand) Error() string

type ManualParseable

type ManualParseable interface {
	// $0 will have its prefix trimmed.
	ParseContent([]string) error
}

ManaulParseable implements a ParseContent(string) method. If the library sees this for an argument, it will send all of the arguments (including the command) into the method. If used, this should be the only argument followed after the Message Create event. Any more and the router will ignore.

type NameFlag

type NameFlag uint64

const (
	None NameFlag = 1 << iota

	// R - Raw, which tells the library to use the method name as-is (flags will
	// still be stripped). For example, if a method is called Reset its
	// command will also be Reset, without being all lower-cased.
	Raw

	// A - AdminOnly, which tells the library to only run the Subcommand/method
	// if the user is admin or not. This will automatically add GuildOnly as
	// well.
	AdminOnly

	// G - GuildOnly, which tells the library to only run the Subcommand/method
	// if the user is inside a guild.
	GuildOnly

	// M - Middleware, which tells the library that the method is a middleware.
	// The method will be executed anytime a method of the same struct is
	// matched.
	//
	// Using this flag inside the subcommand will drop all methods (this is an
	// undefined behavior/UB).
	Middleware
)

func ParseFlag

func ParseFlag(name string) (NameFlag, string)

func (NameFlag) Is

func (f NameFlag) Is(flag NameFlag) bool

type Parseable

type Parseable interface {
	Parse(string) error
}

Parseable implements a Parse(string) method for data structures that can be used as arguments.

type RawArguments

type RawArguments struct {
	Arguments []string
}

RawArguments implements ManualParseable, in case you want to implement a custom argument parser. It borrows the library's argument parser.

func (*RawArguments) ParseContent

func (r *RawArguments) ParseContent(args []string) error

type Subcommand

type Subcommand struct {
	Description string

	// Raw struct name, including the flag (only filled for actual subcommands,
	// will be empty for Context):
	StructName string
	// Parsed command name:
	Command string

	// All registered command contexts:
	Commands []*CommandContext

	// struct flags
	Flag NameFlag
	// contains filtered or unexported fields
}

func NewSubcommand

func NewSubcommand(cmd interface{}) (*Subcommand, error)

func (*Subcommand) ChangeCommandInfo

func (sub *Subcommand) ChangeCommandInfo(methodName, cmd, desc string) bool

ChangeCommandInfo changes the matched methodName's Command and Description. Empty means unchanged. The returned bool is true when the method is found.

func (*Subcommand) InitCommands

func (sub *Subcommand) InitCommands(ctx *Context) error

InitCommands fills a Subcommand with a context. This shouldn't be called at all, rather you should use the RegisterSubcommand method of a Context.

func (*Subcommand) NeedsName

func (sub *Subcommand) NeedsName()

NeedsName sets the name for this subcommand. Like InitCommands, this shouldn't be called at all, rather you should use RegisterSubcommand.