README
¶
Matrix Bot
This package contains an extremely simple Matrix Bot framework.
Usage is fairly simple:
package main
import (
"log"
"os"
"gitlab.com/slxh/matrix/bot"
)
func main() {
// Configure the bot so that it only listens for commands prefixed by `!bot` (and highlights).
config := &bot.ClientConfig{CommandPrefixes: []string{"!bot "}}
// Create a client based on environment variables
client, err := bot.NewClient(os.Getenv("MATRIX_URL"), os.Getenv("MATRIX_UID"), os.Getenv("MATRIX_TOKEN"), config)
if err != nil {
log.Fatal(err)
}
// Set a command for the bot.
client.SetCommand("test", &bot.Command{
Summary: "Test command",
Description: "This shows the description",
MessageHandler: nil,
Subcommands: map[string]*bot.Command{
"sub": &bot.Command{
Summary: "Test subcommand",
Description: "This shows the description of the subcommand",
MessageHandler: nil,
},
},
})
// Run the bot
log.Fatal(client.Run())
}
Documentation
¶
Overview ¶
Package bot contains a simple Matrix bot framework.
Index ¶
- Variables
- type Client
- type ClientConfig
- type Command
- type Event
- type Message
- type Room
- func (r *Room) Allowed() bool
- func (r *Room) Join(ctx context.Context) (id mid.RoomID, err error)
- func (r *Room) SendHTML(ctx context.Context, plain, html string) (mid.EventID, error)
- func (r *Room) SendMarkdown(ctx context.Context, markdown string) (mid.EventID, error)
- func (r *Room) SendMessage(ctx context.Context, message *Message) (mid.EventID, error)
- func (r *Room) SendText(ctx context.Context, plain string) (mid.EventID, error)
Constants ¶
This section is empty.
Variables ¶
var ErrNotAMessage = errors.New("not a message")
ErrNotAMessage is returned by Event.MessageEventContent when the Event is not a message.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
Client *matrix.Client
Config *ClientConfig
// contains filtered or unexported fields
}
Client represents a Matrix Client This is a slightly modified version of gomatrix.Client.
func NewClient ¶
func NewClient(homeserverURL, userID, accessToken string, config *ClientConfig) (c *Client, err error)
NewClient returns a configured Matrix client.
func (*Client) SetCommand ¶
SetCommand registers a command for use in the bot.
func (*Client) SetMessageHandler ¶
SetMessageHandler sets the default event handlers for a message type. Note that setting the handler for mevent.EventMessage will disable the simple Command interface.
type ClientConfig ¶
type ClientConfig struct {
// MessageType contains the message type of any message by the bot.
// Defaults to `m.notice`.
MessageType mevent.MessageType
// CommandPrefixes contains required prefixes for commands.
// Add an empty string to match all messages.
CommandPrefixes []string
// IgnoreHighlights disables command matching on highlights.
// This means that only the CommandPrefixes will be matched.
IgnoreHighlights bool
// Commands contains a set of commands to handle.
// It defaults to a map containing only the "help" command.
Commands map[string]*Command
// AllowRooms contains a list of allowed room IDs.
// All rooms are allowed if left empty.
AllowedRooms []mid.RoomID
}
ClientConfig contains all tunable Client configuration.
type Command ¶
type Command struct {
// Summary contains a short description of the command.
Summary string
// Description (optional) contains a longer description of the command.
Description string
// MessageHandler contains a simple Matrix Message handler.
// The Matrix ID of the sender, original command and arguments are provided.
MessageHandler func(sender mid.UserID, cmd string, args ...string) *Message
// Subcommands (optional) contains any subcommands under this command.
// These subcommands are executed instead of the main command when matched.
Subcommands map[string]*Command
}
Command represents a simple Matrix command.
func (*Command) GetCommand ¶
GetCommand returns the Command that will be executed when the command is called using the given command name and arguments.
func (*Command) Help ¶
Help returns the help message for the Command. This is either the Description (if provided) or the Summary.
func (*Command) HelpCommand ¶
HelpCommand returns the help command for a command.
func (*Command) HelpMessage ¶
HelpMessage returns the help message for a command and its subcommands.
type Event ¶
Event represents a Matrix Event.
func (Event) MessageEventContent ¶ added in v0.4.0
func (e Event) MessageEventContent() (*mevent.MessageEventContent, error)
MessageEventContent returns the parsed message event contents.
type Message ¶
type Message struct {
MsgType mevent.MessageType `json:"msgtype"`
Body string `json:"body"`
FormattedBody string `json:"formatted_body,omitempty"`
Format mevent.Format `json:"format,omitempty"`
}
Message represents a formatted Matrix Message.
func NewHTMLMessage ¶
NewHTMLMessage creates a new message with plain-text and HTML content.
func NewMarkdownMessage ¶
NewMarkdownMessage creates a new message with the original Markdown as the plain-text content, and the rendered markdown as HTML content. The given Markdown is not sanitized.
func NewTextMessage ¶
NewTextMessage creates a new plain-text message. messageType may be left empty, in which case it's overridden by the configured message type.
type Room ¶
Room represents a Matrix Room.
func (*Room) SendMarkdown ¶
SendMarkdown sends a Markdown formatted message as plain text and HTML. The given Markdown is not sanitized.
func (*Room) SendMessage ¶
SendMessage sends a message to a room.
Source Files