feat: ✨ trigger the bot by mentioning it

doc/manual/match.md

@@ -70,6 +70,17 @@ async def example(room, message):
         #Respond to help command
 ```
 
+It is also possible to match by mention of the bot's username, matrix ID, etc.
+In the next example, we can use the prefix or mention the bot to show its help message.
+
+```python
+bot.listener.on_message_event
+async def help(room, message):
+    match = botlib.MessageMatch(room, message, bot, "!")
+    if match.command("help") and (match.prefix() or match.mention()):
+        #Respond to help command
+```
+
 A list of methods for the Match class is shown below. [Methods from the Match class](#match-methods) can also be used with the MessageMatch class.
 
 #### List of Methods:
@@ -78,5 +89,6 @@ A list of methods for the Match class is shown below. [Methods from the Match cl
 | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `MessageMatch.command()` or `MessageMatch.command(command)` | The "command" is the beginning of messages that are intended to be commands, but after the prefix; e.g. "help". Returns the command if the command argument is empty. Returns True if the command argument is equivalent to the command. |
 | `MessageMatch.prefix()`                                     | Returns True if the message begins with the prefix specified during the initialization of the instance of the MessageMatch class. Returns True if no prefix was specified during the initialization.                                     |
+| `MessageMatch.mention()`                                    | Returns True if the message begins with the bot's display name, disambiguated display name, matrix ID, or pill (HTML link to the bot via matrix.to) if formatted_body is present.                                                        |
 | `MessageMatch.args()`                                       | Returns a list of strings; each string is part of the message separated by a space, with the exception of the part of the message before the first space (the prefix and command). Returns an empty list if it is a single-word command. |
-| `MessageMatch.contains(string)`                             | Returns True if the message contains the value specified in the string argument.                                                                                                                                                         |
+| `MessageMatch.contains(string)`                             | Returns True if the message contains the value specified in the string argument.                                                                                                                                                         |

simplematrixbotlib/bot.py

@@ -39,7 +39,7 @@ async def main(self):
 
 
         resp = await self.async_client.sync(timeout=65536,
-                                     full_state=False)  #Ignore prior messages
+                                     full_state=True)  #Ignore prior messages
 
         if isinstance(resp, SyncResponse):
             print(f"Connected to {self.async_client.homeserver} as {self.async_client.user_id} ({self.async_client.device_id})")

simplematrixbotlib/match.py

@@ -82,6 +82,15 @@ def __init__(self, room, event, bot, prefix="") -> None:
         """
         super().__init__(room, event, bot)
         self._prefix = prefix
+        bot_user = self.room.users[self.room.own_user_id]
+        # in case another user uses the same display name, we need to regard the disambiguation if present
+        self._disambiguated_name = bot_user.disambiguated_name
+        # still we allow to mention without disambiguation if typing manually for now
+        self._display_name = bot_user.display_name
+        # element generates a "pill" from formatted (HTML) links to matrix.to/#/@matrix:id
+        # this isn't really specced but still the status quo
+        self._pill = f'<a href="https://matrix.to/#/{self.room.own_user_id}">'
+        self._body_without_prefix = None
 
     def command(self, command=None):
         """
@@ -99,18 +108,17 @@ def command(self, command=None):
             Returns the string after the prefix and before the first space if no arg is passed to this method.
         """
 
-        if self._prefix == self.event.body[0:len(self._prefix)]:
-            body_without_prefix = self.event.body[len(self._prefix):]
-        else:
-            body_without_prefix = self.event.body
-
-        if not body_without_prefix:
-            return []
+        # we cache this part
+        if self._body_without_prefix is None:
+            if self._prefix == self.event.body[0:len(self._prefix)]:
+                self._body_without_prefix = self.event.body[len(self._prefix):]
+            elif not self.mention():  # if mention() is True then it also sets the _body_without_prefix
+                self._body_without_prefix = self.event.body
 
         if command:
-            return body_without_prefix.split()[0] == command
+            return self._body_without_prefix.split()[0] == command
         else:
-            return body_without_prefix.split()[0]
+            return self._body_without_prefix.split()[0]
 
     def prefix(self):
         """
@@ -123,6 +131,36 @@ def prefix(self):
 
         return self.event.body.startswith(self._prefix)
 
+    def mention(self):
+        """
+
+        Returns
+        -------
+        boolean
+            Returns True if the message begins with the bot's username, MXID, or pill targeting the MXID, and False otherwise.
+        """
+
+        body = self.event.body
+        for id in [self._disambiguated_name, self._display_name, self.room.own_user_id]:
+            if body.startswith(id):
+                body_ = body[len(id):]
+                # the match needs to end here, otherwise someone else is mentioned
+                # this isn't perfect but probably the best effort
+                if body_[0] in [' ', ':']:
+                    self._body_without_prefix = body_[1:].strip()
+                    return True
+
+        # pills on the other hand are a clearer case thanks to HTML tags which include delimiters
+        body = self.event.formatted_body
+        if body is not None and body.startswith(self._pill):
+            # remove the first half of the pill
+            body = body[len(self._pill):]
+            # find pill end + trailing delimiter + maybe whitespace
+            self._body_without_prefix = body[body.index('</a>')+5:].strip()
+            return True
+
+        return False
+
     def args(self):
         """
 
@@ -132,7 +170,7 @@ def args(self):
             Returns a list of strings that are the "words" of the message, except for the first "word", which would be the command.
         """
 
-        return self.event.body.split()[1:]
+        return self._body_without_prefix.split()[1:]
 
     def contains(self, string):
         """

tests/match/test_messagematch.py

@@ -3,21 +3,54 @@
 
 mock_room = mock.MagicMock()
 
+mock_room2 = mock.MagicMock()
+mock_room2.own_user_id = "@bot:matrix.org"
+mock_user = mock.MagicMock()
+mock_user.display_name = "bot"
+mock_user.disambiguated_name = f"{mock_user.display_name} ({mock_room2.own_user_id})"
+mock_room2.users = {mock_room2.own_user_id: mock_user}
+
 mock_event = mock.MagicMock()
 mock_event.body = "p!help example"
 
 mock_event2 = mock.MagicMock()
 mock_event2.body = "p!help"
 
+mock_event3 = mock.MagicMock()
+mock_event3.body = "bot help"
+mock_event3.formatted_body = None
+mock_event4 = mock.MagicMock()
+mock_event4.body = "bot: help"
+mock_event4.formatted_body = None
+mock_event5 = mock.MagicMock()
+mock_event5.body = f"{mock_room2.own_user_id} help"
+mock_event5.formatted_body = None
+mock_event6 = mock.MagicMock()
+mock_event6.body = f"bot ({mock_room2.own_user_id}) help"
+mock_event6.formatted_body = None
+mock_event7 = mock.MagicMock()
+mock_event7.body = "something else"
+mock_event7.formatted_body = "<a href=\"https://matrix.to/#/@bot:matrix.org\">bot</a> help"
+mock_event8 = mock.MagicMock()
+mock_event8.body = "bottom help"
+mock_event8.formatted_body = None
+
 mock_bot = mock.MagicMock()
 
 prefix = "p!"
 prefix2 = "!!"
 
-match = MessageMatch(mock_room, mock_event, mock_bot, prefix)
-match2 = MessageMatch(mock_room, mock_event, mock_bot)
-match3 = MessageMatch(mock_room, mock_event, mock_bot, prefix2)
-match4 = MessageMatch(mock_room, mock_event2, mock_bot, prefix)
+match = MessageMatch(mock_room, mock_event, mock_bot, prefix)      # prefix match
+match2 = MessageMatch(mock_room, mock_event, mock_bot)             # no prefix given
+match3 = MessageMatch(mock_room, mock_event, mock_bot, prefix2)    # wrong prefix given
+match4 = MessageMatch(mock_room, mock_event2, mock_bot, prefix)    # no arguments given
+
+match5 = MessageMatch(mock_room2, mock_event3, mock_bot, prefix)   # mention with display name
+match6 = MessageMatch(mock_room2, mock_event4, mock_bot, prefix)   # mention with colon
+match7 = MessageMatch(mock_room2, mock_event5, mock_bot, prefix)   # mention with user id
+match8 = MessageMatch(mock_room2, mock_event6, mock_bot, prefix)   # mention with disambiguated name
+match9 = MessageMatch(mock_room2, mock_event7, mock_bot, prefix)   # mention with pill
+match10 = MessageMatch(mock_room2, mock_event8, mock_bot, prefix)  # mention someone else
 
 def test_init():
     assert issubclass(MessageMatch, Match)
@@ -30,6 +63,25 @@ def test_command():
     assert match2.command() == "p!help"
     assert match2.command("p!help") == True
 
+def test_mention():
+    assert match5.command() == "help"
+    assert match5.mention() == True
+
+    assert match6.command() == "help"
+    assert match6.mention() == True
+
+    assert match7.command() == "help"
+    assert match7.mention() == True
+
+    assert match8.command() == "help"
+    assert match8.mention() == True
+
+    assert match9.command() == "help"
+    assert match9.mention() == True
+
+    assert match10.command() == "bottom"
+    assert match10.mention() == False
+
 def test_prefix():
     assert match.prefix() == True
     assert match3.prefix() == False