feat(handler): add built-in predicates and OnCommand

Update.EffectiveMessage/Text accessors plus predicates: Command (slash- and
@botusername-aware), HasPrefix, HasText, TextEquals, Regex, ChatTypeIs,
CallbackData, CallbackPrefix, and the Not/Or combinators. OnCommand registers a
message handler guarded by Command. Command parsing is unit tested.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ernado

predicates.go

@@ -0,0 +1,145 @@
+package botapi
+
+import (
+	"regexp"
+	"strings"
+)
+
+// EffectiveMessage returns the message carried by the update, regardless of
+// whether it is a new/edited message or channel post. It is nil for updates
+// that carry no message (e.g. callback or inline queries).
+func (u *Update) EffectiveMessage() *Message {
+	switch {
+	case u.Message != nil:
+		return u.Message
+	case u.EditedMessage != nil:
+		return u.EditedMessage
+	case u.ChannelPost != nil:
+		return u.ChannelPost
+	case u.EditedChannelPost != nil:
+		return u.EditedChannelPost
+	default:
+		return nil
+	}
+}
+
+// Text returns the text of the effective message, or the callback query data,
+// or empty when neither is present.
+func (u *Update) Text() string {
+	if m := u.EffectiveMessage(); m != nil {
+		return m.Text
+	}
+	if u.CallbackQuery != nil {
+		return u.CallbackQuery.Data
+	}
+	return ""
+}
+
+// commandName extracts the bot command name from message text: "/start@bot foo"
+// yields ("start", true). Pure.
+func commandName(text string) (string, bool) {
+	if !strings.HasPrefix(text, "/") {
+		return "", false
+	}
+	field := text
+	if i := strings.IndexAny(text, " \t\n"); i >= 0 {
+		field = text[:i]
+	}
+	field = field[1:] // drop leading slash
+	if at := strings.IndexByte(field, '@'); at >= 0 {
+		field = field[:at]
+	}
+	return field, field != ""
+}
+
+// Command matches a message whose first token is the given bot command (with or
+// without a leading slash, and ignoring a trailing @botusername).
+func Command(name string) Predicate {
+	name = strings.TrimPrefix(name, "/")
+	return func(u *Update) bool {
+		m := u.EffectiveMessage()
+		if m == nil {
+			return false
+		}
+		got, ok := commandName(m.Text)
+		return ok && got == name
+	}
+}
+
+// HasPrefix matches a message whose text starts with prefix.
+func HasPrefix(prefix string) Predicate {
+	return func(u *Update) bool {
+		m := u.EffectiveMessage()
+		return m != nil && strings.HasPrefix(m.Text, prefix)
+	}
+}
+
+// HasText matches any message that carries non-empty text.
+func HasText() Predicate {
+	return func(u *Update) bool {
+		m := u.EffectiveMessage()
+		return m != nil && m.Text != ""
+	}
+}
+
+// TextEquals matches a message whose text equals s exactly.
+func TextEquals(s string) Predicate {
+	return func(u *Update) bool {
+		m := u.EffectiveMessage()
+		return m != nil && m.Text == s
+	}
+}
+
+// Regex matches a message whose text matches the pattern. It panics if the
+// pattern does not compile (a programming error caught at registration).
+func Regex(pattern string) Predicate {
+	re := regexp.MustCompile(pattern)
+	return func(u *Update) bool {
+		m := u.EffectiveMessage()
+		return m != nil && re.MatchString(m.Text)
+	}
+}
+
+// ChatTypeIs matches a message sent in a chat of the given type.
+func ChatTypeIs(t ChatType) Predicate {
+	return func(u *Update) bool {
+		m := u.EffectiveMessage()
+		return m != nil && m.Chat.Type == t
+	}
+}
+
+// CallbackData matches a callback query whose data equals s.
+func CallbackData(s string) Predicate {
+	return func(u *Update) bool {
+		return u.CallbackQuery != nil && u.CallbackQuery.Data == s
+	}
+}
+
+// CallbackPrefix matches a callback query whose data starts with prefix.
+func CallbackPrefix(prefix string) Predicate {
+	return func(u *Update) bool {
+		return u.CallbackQuery != nil && strings.HasPrefix(u.CallbackQuery.Data, prefix)
+	}
+}
+
+// Not inverts a predicate.
+func Not(p Predicate) Predicate {
+	return func(u *Update) bool { return !p(u) }
+}
+
+// Or matches when any of the given predicates matches.
+func Or(predicates ...Predicate) Predicate {
+	return func(u *Update) bool {
+		for _, p := range predicates {
+			if p(u) {
+				return true
+			}
+		}
+		return false
+	}
+}
+
+// OnCommand registers a handler for the given bot command (e.g. "start").
+func (b *Bot) OnCommand(name string, h Handler, predicates ...Predicate) {
+	b.OnMessage(h, prepend(Command(name), predicates)...)
+}

predicates_test.go

@@ -0,0 +1,62 @@
+package botapi
+
+import "testing"
+
+func TestCommandName(t *testing.T) {
+	cases := map[string]struct {
+		want string
+		ok   bool
+	}{
+		"/start":             {"start", true},
+		"/start@mybot":       {"start", true},
+		"/help me please":    {"help", true},
+		"/cmd@bot with args": {"cmd", true},
+		"not a command":      {"", false},
+		"/":                  {"", false},
+	}
+	for text, want := range cases {
+		got, ok := commandName(text)
+		if got != want.want || ok != want.ok {
+			t.Fatalf("commandName(%q) = (%q, %v), want (%q, %v)", text, got, ok, want.want, want.ok)
+		}
+	}
+}
+
+func TestCommandPredicate(t *testing.T) {
+	msg := &Update{Message: &Message{Text: "/start@mybot hi"}}
+	if !Command("start")(msg) || !Command("/start")(msg) {
+		t.Fatal("Command should match with and without slash")
+	}
+	if Command("help")(msg) {
+		t.Fatal("Command should not match a different command")
+	}
+	if Command("start")(&Update{CallbackQuery: &CallbackQuery{}}) {
+		t.Fatal("Command should not match a non-message update")
+	}
+}
+
+func TestTextAndChatPredicates(t *testing.T) {
+	u := &Update{Message: &Message{Text: "hello world", Chat: Chat{Type: ChatTypePrivate}}}
+	if !HasPrefix("hello")(u) || !HasText()(u) || !Regex(`^hello`)(u) {
+		t.Fatal("text predicates should match")
+	}
+	if !ChatTypeIs(ChatTypePrivate)(u) || ChatTypeIs(ChatTypeChannel)(u) {
+		t.Fatal("ChatTypeIs mismatch")
+	}
+	if !Not(TextEquals("nope"))(u) {
+		t.Fatal("Not should invert")
+	}
+}
+
+func TestCallbackPredicates(t *testing.T) {
+	u := &Update{CallbackQuery: &CallbackQuery{Data: "vote:42"}}
+	if !CallbackPrefix("vote:")(u) || !CallbackData("vote:42")(u) {
+		t.Fatal("callback predicates should match")
+	}
+	if !Or(CallbackData("x"), CallbackPrefix("vote:"))(u) {
+		t.Fatal("Or should match when one matches")
+	}
+	if u.Text() != "vote:42" {
+		t.Fatalf("Update.Text for callback = %q", u.Text())
+	}
+}