plugins

README

plugins

This README describes how to use plugins. See the README in the root of the repo for a description of what plugins can do.

1. Default plugins
2. Compiling a plugin
3. Hot-reloading plugins
4. Creating a plugin
5. Docker

Default plugins

Various plugins are loaded by default when using the bot, stored in the DefaultPlugins variable in bot/config.go.

You can configure the plugins that are loaded by modifying the config/plugins.json file, as described in the main README.

You are also able to change the directory that the bot looks for plugins in, which is -pluginDir="bin" by default. Changing this flag will not compile your plugins for you, the Makefile will check plugins/ for compiling, and output them to bin/.

Compiling a plugin

Running make on its own will compile the bot along with the plugins, by default. This is the code that make calls for compiling all plugins:

for d in ./plugins/*/; do
  echo "building $$d"
  go build -o "bin/" -buildmode=plugin "$$d"
done

You can compile a single plugin on your own using

go build -o "bin/" -buildmode=plugin "plugins/my-plugin/"

If you want your plugin to be loaded, you must add it to the DefaultPlugins list in bot/config.go, or the config/plugins.json file.

Hot-reloading plugins

Currently, hot-reloading is technically possible but there are no commands to do so from the user-end. This README will be updated as issue #8 is updated.

Creating a plugin

All a plugin has to do is

• Have a plugin-name.go with a package main which declares a func InitPlugin(_ *plugins.PluginInit) *plugins.Plugin.
• Be inside the plugins/ (or other) directory in a directory under its own name, for example, plugins/base/base.go or plugins/base-extra/base-extra.go

The actual plugins.go code is heavily documented and explains the technical process of how plugins are loaded and work.

An example plugin's example.go can be found in the plugins folder.

Docker

You can modify the plugins to be loaded via Docker with the config/plugins.json file, as described in the main README.

Documentation

Index

• func ClearHandlers()
• func ClearJobs()
• func Load(dir string)
• func RegisterAll(dir string)
• func RegisterHandlers()
• func RegisterJob(job bot.JobInfo)
• func RegisterJobConcurrent(job bot.JobInfo, addGlobally bool)
• func RegisterJobs()
• func SaveConfig()
• func SetupConfigSaving()
• func Shutdown()
• func Startup()
• type Plugin
  • func (p *Plugin) LoadConfig() (i interface{})
  • func (p *Plugin) Register()
  • func (p *Plugin) SaveConfig()
  • func (p *Plugin) String() string
• type PluginInit

Functions

func ClearHandlers

func ClearHandlers()

ClearHandlers will go through bot.Handlers and handle the de-registration of them

func ClearJobs

func ClearJobs()

ClearJobs will clear all registered jobs

func Load

func Load(dir string)

Load will load all the plugins

func RegisterAll

func RegisterAll(dir string)

RegisterAll will register all bot features, and then load plugins

func RegisterHandlers

func RegisterHandlers()

RegisterHandlers will go through bot.Handlers and handle the re-registration of them

func RegisterJob

func RegisterJob(job bot.JobInfo)

RegisterJob registers a job for use with gocron. Ensure you add the job to bot.Jobs for de-registration with ClearJobs.

func RegisterJobConcurrent

func RegisterJobConcurrent(job bot.JobInfo, addGlobally bool)

RegisterJobConcurrent registers a job with RegisterJob concurrently, and optionally adds the job to bot.Jobs to be tracked.

func RegisterJobs

func RegisterJobs()

RegisterJobs will go through bot.Jobs and handle the re-registration of them

func SaveConfig

func SaveConfig()

SaveConfig will save all plugin configs

func SetupConfigSaving

func SetupConfigSaving()

SetupConfigSaving will run each plugin's SaveConfig every 5 minutes with a ticker

func Shutdown

func Shutdown()

Shutdown will run the shutdown function for all plugins

func Startup

func Startup()

Startup will run the startup function for all plugins

Types

type Plugin

type Plugin struct {
	Name        string             // Name of the plugin to display to users
	Description string             // Description of what the plugin does
	Version     string             // Version in semver, e.g.., 1.1.0
	Config      interface{}        // Config is the Plugin's config, can be nil
	ConfigDir   string             // ConfigDir is the name of the config directory
	ConfigType  reflect.Type       // ConfigType is the type to validate parse the config with
	Commands    []bot.CommandInfo  // Commands to register, could be none
	Responses   []bot.ResponseInfo // Responses to register, could be none
	Handlers    []bot.HandlerInfo  // Handlers to register, could be none
	Jobs        []bot.JobInfo      // Jobs to register, could be none
	StartupFn   func()             // ShutdownFn is a function to be called when the bot starts up
	ShutdownFn  func()             // ShutdownFn is a function to be called when the bot shuts down
}

func (*Plugin) LoadConfig

func (p *Plugin) LoadConfig() (i interface{})

func (*Plugin) Register

func (p *Plugin) Register()

Register will register a plugin's commands, responses and jobs to the bot

func (*Plugin) SaveConfig

func (p *Plugin) SaveConfig()

func (*Plugin) String

func (p *Plugin) String() string

type PluginInit

type PluginInit struct {
	ConfigDir string
}