plugin

README

plugin

Lua-based plugin system for extending Matcha. Plugins are loaded from ~/.config/matcha/plugins/ and run inside a sandboxed Lua VM (no os, io, or debug libraries).

How it works

The Manager creates a Lua VM at startup, registers the matcha module, and loads all plugins from the user's plugins directory. Plugins can be either a single .lua file or a directory with an init.lua entry point.

Plugins interact with Matcha by registering callbacks on hooks:

local matcha = require("matcha")

matcha.on("email_received", function(email)
    matcha.log("New email from: " .. email.from)
    matcha.notify("New mail!", 3)
end)

Lua API (matcha module)

Function	Description
matcha.on(event, callback)	Register a callback for a hook event
matcha.log(msg)	Log a message to stderr
matcha.notify(msg [, seconds])	Show a temporary notification in the TUI (default 2s)
matcha.set_status(area, text)	Set a persistent status string for a view area ("inbox", "composer", "email_view")
matcha.set_compose_field(field, value)	Set a compose field value ("to", "cc", "bcc", "subject", "body")
matcha.bind_key(key, area, description, callback)	Register a custom keyboard shortcut for a view area ("inbox", "email_view", "composer")

Hook events

Event	Callback argument	Description
startup	—	Matcha has started
shutdown	—	Matcha is exiting
email_received	Lua table with uid, from, to, subject, date, is_read, account_id, folder	New email arrived
email_viewed	Same as email_received	User opened an email
email_send_before	Table with to, cc, subject, account_id	About to send an email
email_send_after	Same as email_send_before	Email sent successfully
folder_changed	Folder name (string)	User switched folders
composer_updated	Table with body, body_len, subject, to, cc, bcc	Composer content changed

Available plugins

The following example plugins ship in ~/.config/matcha/plugins/:

• email_age.lua
• recipient_counter.lua

Files

File	Description
plugin.go	Plugin manager — Lua VM setup, plugin discovery and loading, notification/status state
hooks.go	Hook definitions, callback registration, and hook invocation helpers
api.go	matcha Lua module registration (on, log, notify, set_status, set_compose_field, bind_key)

Documentation

Index

• Constants
• type KeyBinding
• type Manager
  • func NewManager() *Manager
  • func (m *Manager) Bindings(area string) []KeyBinding
  • func (m *Manager) CallComposerHook(event string, body, subject, to, cc, bcc string)
  • func (m *Manager) CallFolderHook(event string, folderName string)
  • func (m *Manager) CallHook(event string, args ...lua.LValue)
  • func (m *Manager) CallKeyBinding(binding KeyBinding, args ...lua.LValue)
  • func (m *Manager) CallSendHook(event string, to, cc, subject, accountID string)
  • func (m *Manager) Close()
  • func (m *Manager) EmailToTable(uid uint32, from string, to []string, subject string, date time.Time, ...) *lua.LTable
  • func (m *Manager) LoadPlugins()
  • func (m *Manager) LuaState() *lua.LState
  • func (m *Manager) Plugins() []string
  • func (m *Manager) StatusText(area string) string
  • func (m *Manager) TakePendingFields() map[string]string
  • func (m *Manager) TakePendingNotification() (PendingNotification, bool)
• type PendingNotification

Constants

const (
	HookStartup         = "startup"
	HookShutdown        = "shutdown"
	HookEmailReceived   = "email_received"
	HookEmailSendBefore = "email_send_before"
	HookEmailSendAfter  = "email_send_after"
	HookEmailViewed     = "email_viewed"
	HookFolderChanged   = "folder_changed"
	HookComposerUpdated = "composer_updated"
)

Hook event names.

const (
	StatusInbox     = "inbox"
	StatusComposer  = "composer"
	StatusEmailView = "email_view"
)

Status area names.

Types

type KeyBinding

type KeyBinding struct {
	Key         string
	Area        string // "inbox", "email_view", or "composer"
	Description string
	Fn          *lua.LFunction
}

KeyBinding represents a plugin-registered keyboard shortcut.

type Manager

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

Manager manages the Lua VM and loaded plugins.

func NewManager

func NewManager() *Manager

NewManager creates a new plugin manager with a Lua VM.

func (*Manager) Bindings

func (m *Manager) Bindings(area string) []KeyBinding

Bindings returns all plugin-registered key bindings for the given view area.

func (*Manager) CallComposerHook

func (m *Manager) CallComposerHook(event string, body, subject, to, cc, bcc string)

CallComposerHook calls a hook with composer state info.

func (*Manager) CallFolderHook

func (m *Manager) CallFolderHook(event string, folderName string)

CallFolderHook calls a hook with a folder name.

func (*Manager) CallHook

func (m *Manager) CallHook(event string, args ...lua.LValue)

CallHook invokes all callbacks registered for the given event.

func (*Manager) CallKeyBinding

func (m *Manager) CallKeyBinding(binding KeyBinding, args ...lua.LValue)

CallKeyBinding invokes a plugin key binding callback with the given arguments.

func (*Manager) CallSendHook

func (m *Manager) CallSendHook(event string, to, cc, subject, accountID string)

CallSendHook calls a hook with email send metadata.

func (*Manager) Close

func (m *Manager) Close()

Close shuts down the Lua VM.

func (*Manager) EmailToTable

func (m *Manager) EmailToTable(uid uint32, from string, to []string, subject string, date time.Time, isRead bool, accountID string, folder string) *lua.LTable

EmailToTable converts email fields into a Lua table.

func (*Manager) LoadPlugins

func (m *Manager) LoadPlugins()

LoadPlugins discovers and loads plugins from ~/.config/matcha/plugins/.

func (*Manager) LuaState

func (m *Manager) LuaState() *lua.LState

LuaState returns the Lua VM state for building tables.

func (*Manager) Plugins

func (m *Manager) Plugins() []string

Plugins returns the names of all loaded plugins.

func (*Manager) StatusText

func (m *Manager) StatusText(area string) string

StatusText returns the plugin status string for the given view area.

func (*Manager) TakePendingFields

func (m *Manager) TakePendingFields() map[string]string

TakePendingFields returns and clears any pending compose field updates.

func (*Manager) TakePendingNotification

func (m *Manager) TakePendingNotification() (PendingNotification, bool)

TakePendingNotification returns and clears any pending notification.

type PendingNotification

type PendingNotification struct {
	Message  string
	Duration float64 // seconds, 0 means default
}

PendingNotification holds a notification message and its display duration.