A module end to end

We will build a Notes module: save a note, list notes, delete one. It uses storage, arguments, aliases, filters and translations — most of what a real module needs.

1. Generate

.newmod Notes

2. Storage shape

Notes are per-chat, so one map keyed by chat ID, with the notes joined into a list:

package modules

import (
	"fmt"
	"strconv"
	"strings"

	"goroku/goroku"
	"goroku/goroku/utils"
)

type Notes struct {
	goroku.Base
}

func (m *Notes) Name() string { return "Notes" }

// notesFor returns the notes saved in one chat.
func (m *Notes) notesFor(chatID int64) []string {
	all := m.DB.GetStringMapStringSlice(m.Name(), "notes", nil)
	if all == nil {
		return nil
	}
	return all[strconv.FormatInt(chatID, 10)]
}

// saveNotes replaces the notes for one chat.
func (m *Notes) saveNotes(chatID int64, notes []string) error {
	all := m.DB.GetStringMapStringSlice(m.Name(), "notes", nil)
	if all == nil {
		all = map[string][]string{}
	}
	all[strconv.FormatInt(chatID, 10)] = notes
	if err := m.DB.SetStringMapStringSlice(m.Name(), "notes", all); err != nil {
		return fmt.Errorf("save notes: %w", err)
	}
	return nil
}

The getter returns a copy, so we read, modify, and write back.

3. Strings

func (m *Notes) Strings() map[string]string {
	return map[string]string{
		"name":            "Notes",
		"_cls_doc":        "Per-chat notes",
		"_cmd_doc_note":   "[text] — save a note, or reply to a message",
		"_cmd_doc_notes":  "List saved notes",
		"_cmd_doc_delnote": "[number] — delete a note",

		"saved":     "📝 <b>Saved as #{n}</b>",
		"empty":     "📭 <b>No notes yet</b>",
		"no_text":   "❌ <b>Send text or reply to a message</b>",
		"bad_index": "❌ <b>Give the note number, see .notes</b>",
		"deleted":   "🗑 <b>Deleted #{n}</b>",
	}
}

4. Commands

func (m *Notes) Commands() map[string]goroku.CommandHandler {
	return map[string]goroku.CommandHandler{
		"note":    m.NoteCmd,
		"notes":   m.NotesCmd,
		"delnote": m.DelNoteCmd,
	}
}

func (m *Notes) CommandMetas() map[string]goroku.CommandMeta {
	return map[string]goroku.CommandMeta{
		"note":    {Aliases: []string{"n"}, OnlyOwner: true},
		"notes":   {OnlyOwner: true},
		"delnote": {Aliases: []string{"dn"}, OnlyOwner: true},
	}
}

Owner-only: these touch your own storage.

5. Saving

func (m *Notes) NoteCmd(msg *goroku.Message) error {
	text := msg.ArgsOrReply()
	if text == "" {
		return msg.Answer(m.T("no_text", "❌ <b>Send text or reply to a message</b>"))
	}

	notes := append(m.notesFor(msg.ChatID), text)
	if err := m.saveNotes(msg.ChatID, notes); err != nil {
		return err
	}

	tpl := m.T("saved", "📝 <b>Saved as #{n}</b>")
	return msg.Answer(strings.Replace(tpl, "{n}", strconv.Itoa(len(notes)), 1))
}

ArgsOrReply gives us both .note buy milk and replying to a message with .note, for free.

6. Listing

func (m *Notes) NotesCmd(msg *goroku.Message) error {
	notes := m.notesFor(msg.ChatID)
	if len(notes) == 0 {
		return msg.Answer(m.T("empty", "📭 <b>No notes yet</b>"))
	}

	var b strings.Builder
	b.WriteString("📝 <b>Notes</b>\n\n")
	for i, note := range notes {
		fmt.Fprintf(&b, "%d. %s\n", i+1, utils.EscapeHTML(note))
	}
	return msg.Answer(b.String())
}

EscapeHTML matters: a note containing < would otherwise break the message.

7. Deleting

func (m *Notes) DelNoteCmd(msg *goroku.Message) error {
	notes := m.notesFor(msg.ChatID)
	if len(notes) == 0 {
		return msg.Answer(m.T("empty", "📭 <b>No notes yet</b>"))
	}

	n, err := strconv.Atoi(msg.Arg(0))
	if err != nil || n < 1 || n > len(notes) {
		return msg.Answer(m.T("bad_index", "❌ <b>Give the note number, see .notes</b>"))
	}

	notes = append(notes[:n-1], notes[n:]...)
	if err := m.saveNotes(msg.ChatID, notes); err != nil {
		return err
	}

	tpl := m.T("deleted", "🗑 <b>Deleted #{n}</b>")
	return msg.Answer(strings.Replace(tpl, "{n}", strconv.Itoa(n), 1))
}

msg.Arg(0) is bounds-safe — .delnote with no argument gives "", which Atoi rejects, and the user gets the friendly message.

8. Install

Send the file, reply, .loadmod. Then:

.note buy milk
.note      (replying to something)
.notes
.delnote 1

What this covered

Feature	Where
Storage with read-modify-write	notesFor / saveNotes
Args or replied-to text	ArgsOrReply
Bounds-safe arguments	Arg(0)
Aliases and owner-only	CommandMetas
Translatable text with a default	m.T
HTML escaping of user data	utils.EscapeHTML
Error wrapping	fmt.Errorf("...: %w", err)

Next

• Add a max_notes setting — Configuration
• React to conversation — Watchers
• Share it — Installing a module