bot

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 15, 2023 License: EUPL-1.2 Imports: 6 Imported by: 1

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

Constants

This section is empty.

Variables

This section is empty.

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) NewRoom

func (c *Client) NewRoom(roomID string) *Room

NewRoom returns a Room for a client.

func (*Client) Run

func (c *Client) Run() error

Run the client in a blocking thread.

func (*Client) SetCommand

func (c *Client) SetCommand(name string, command *Command)

SetCommand registers a command for use in the bot.

func (*Client) SetMessageHandler

func (c *Client) SetMessageHandler(t EventType, f func(*Event))

SetMessageHandler sets the default event handlers for a message type. Note that setting the handler for EventTypeRoomMessage will disable the simple Command interface.

func (*Client) Stop

func (c *Client) Stop()

Stop stops the sync.

type ClientConfig

type ClientConfig struct {
	// MessageType contains the message type of any message by the bot.
	// Defaults to `m.notice`.
	MessageType string

	// 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 []string
}

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, 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) Execute

func (c *Command) Execute(sender, cmd string, args ...string) *Message

Execute executes the Command or any Subcommands set for the Command.

func (*Command) GetCommand

func (c *Command) GetCommand(_ string, args ...string) *Command

GetCommand returns the Command that will be executed when the command is called using the given command name and arguments.

func (*Command) Help

func (c *Command) Help() string

Help returns the help message for the Command. This is either the Description (if provided) or the Summary.

func (*Command) HelpCommand

func (c *Command) HelpCommand() *Command

HelpCommand returns the help command for a command.

func (*Command) HelpMessage

func (c *Command) HelpMessage() *Message

HelpMessage returns the help message for a command and its subcommands.

type Event

type Event struct {
	*matrix.Event
}

Event represents a Matrix Event.

type EventType

type EventType string

EventType represents an event type.

const (
	EventTypeRoomMessage      EventType = "m.room.message"
	EventTypeRoomName         EventType = "m.room.name"
	EventTypeRoomTopic        EventType = "m.room.topic"
	EventTypeRoomAvatar       EventType = "m.room.avatar"
	EventTypeRoomPinnedEvents EventType = "m.room.pinned_events"
)

Matrix event types.

type Message

type Message struct {
	MsgType       string `json:"msgtype"`
	Body          string `json:"body"`
	FormattedBody string `json:"formatted_body,omitempty"`
	Format        string `json:"format,omitempty"`
}

Message represents a formatted Matrix Message.

func NewHTMLMessage

func NewHTMLMessage(plain, html string) *Message

NewHTMLMessage creates a new message with plain-text and HTML content.

func NewMarkdownMessage

func NewMarkdownMessage(markdown string) *Message

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

func NewTextMessage(text string) *Message

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

type Room struct {
	ID string
	// contains filtered or unexported fields
}

Room represents a Matrix Room.

func (*Room) Allowed

func (r *Room) Allowed() bool

Allowed returns true if it is allowed to send messages to this room.

func (*Room) Join

func (r *Room) Join() (id string, err error)

Join joins the room.

func (*Room) SendHTML

func (r *Room) SendHTML(plain, html string) (string, error)

SendHTML sends a plain and HTML formatted message.

func (*Room) SendMarkdown

func (r *Room) SendMarkdown(markdown string) (string, error)

SendMarkdown sends a Markdown formatted message as plain text and HTML. The given Markdown is not sanitized.

func (*Room) SendMessage

func (r *Room) SendMessage(message *Message) (string, error)

SendMessage sends a message to a room.

func (*Room) SendText

func (r *Room) SendText(plain string) (string, error)

SendText sends a plain text message.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL