Add basic task instructions to _MsgTokGuides.

diff --git a/ircplom/client.py b/ircplom/client.py
index 44c7b0a5e715fde1d3bb61a0980cf726f9f66b03..291f596f7d07b821b3348dff70952fe3e10e8e1c 100644 (file)
--- a/ircplom/client.py
+++ b/ircplom/client.py
@@ -43,19 +43,19 @@ _EXPECTATIONS: list[_MsgParseExpectation] = []
 _EXPECTATIONS += [
     _MsgParseExpectation(_MsgTok.SERVER,
                          '001',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '002',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '003',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '004',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY,
                           _MsgTok.ANY,
                           _MsgTok.ANY,
@@ -63,54 +63,54 @@ _EXPECTATIONS += [
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '250',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '251',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '252',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY,
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '253',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY,
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '254',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY,
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '255',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '265',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '265',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY,
                           _MsgTok.ANY,
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '266',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '266',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY,
                           _MsgTok.ANY,
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '375',  # RPL_MOTDSTART already implied by 1st 372
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY)),
 ]
 
@@ -118,22 +118,22 @@ _EXPECTATIONS += [
 _EXPECTATIONS += [
     _MsgParseExpectation(_MsgTok.SERVER,
                          '005',  # RPL_ISUPPORT
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.ANY, 'isupports'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.ANY, ':isupports'),
                           _MsgTok.ANY),
                          idx_into_list=1),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '372',  # RPL_MOTD
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.ANY, 'line'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.ANY, ':line'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '376',  # RPL_ENDOFMOTD
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '396',  # RPL_VISIBLEHOST
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.ANY, 'host_maybe_w_user'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.ANY, ':host_maybe_w_user'),
                           _MsgTok.ANY)),
 ]
 
@@ -141,18 +141,18 @@ _EXPECTATIONS += [
 _EXPECTATIONS += [
     _MsgParseExpectation(_MsgTok.SERVER,
                          '900',  # RPL_LOGGEDIN
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.USER_ADDRESS, 'full_address'),
-                          (_MsgTok.ANY, 'account'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.USER_ADDRESS, ':full_address'),
+                          (_MsgTok.ANY, 'set_db_attr:sasl_account'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '903',  # RPL_SASLSUCCESS
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.ANY, 'result'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.ANY, 'set_db_attr:sasl_auth_state'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '904',  # ERR_SASLFAIL
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.ANY, 'result'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.ANY, 'set_db_attr:sasl_auth_state'))),
     _MsgParseExpectation(_MsgTok.NONE,
                          'AUTHENTICATE',
                          ('+',)),
@@ -162,79 +162,79 @@ _EXPECTATIONS += [
 _EXPECTATIONS += [
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          ('NEW', 'subverb'),
-                          (_MsgTok.LIST, 'items'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          ('NEW', ':subverb'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          ('DEL', 'subverb'),
-                          (_MsgTok.LIST, 'items'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          ('DEL', ':subverb'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
                          ('*',
-                          ('ACK', 'subverb'),
-                          (_MsgTok.LIST, 'items'))),
+                          ('ACK', ':subverb'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          ('ACK', 'subverb'),
-                          (_MsgTok.LIST, 'items'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          ('ACK', ':subverb'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
                          ('*',
-                          ('NAK', 'subverb'),
-                          (_MsgTok.LIST, 'items'))),
+                          ('NAK', ':subverb'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          ('NAK', 'subverb'),
-                          (_MsgTok.LIST, 'items'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          ('NAK', ':subverb'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
                          ('*',
-                          ('LS', 'subverb'),
-                          (_MsgTok.LIST, 'items'))),
+                          ('LS', ':subverb'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
                          ('*',
-                          ('LS', 'subverb'),
-                          ('*', 'tbc'),
-                          (_MsgTok.LIST, 'items'))),
+                          ('LS', ':subverb'),
+                          ('*', ':tbc'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          ('LS', 'subverb'),
-                          (_MsgTok.LIST, 'items'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          ('LS', ':subverb'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          ('LS', 'subverb'),
-                          ('*', 'tbc'),
-                          (_MsgTok.LIST, 'items'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          ('LS', ':subverb'),
+                          ('*', ':tbc'),
+                          (_MsgTok.LIST, ':items'))),
 
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
                          ('*',
-                          ('LIST', 'subverb'),
-                          (_MsgTok.LIST, 'items'))),
+                          ('LIST', ':subverb'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
                          ('*',
-                          ('LIST', 'subverb'),
-                          ('*', 'tbc'),
-                          (_MsgTok.LIST, 'items'))),
+                          ('LIST', ':subverb'),
+                          ('*', ':tbc'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          ('LIST', 'subverb'),
-                          (_MsgTok.LIST, 'items'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          ('LIST', ':subverb'),
+                          (_MsgTok.LIST, ':items'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'CAP',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          ('LIST', 'subverb'),
-                          ('*', 'tbc'),
-                          (_MsgTok.LIST, 'items'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          ('LIST', ':subverb'),
+                          ('*', ':tbc'),
+                          (_MsgTok.LIST, ':items'))),
 ]
 
 # nickname management
@@ -246,7 +246,7 @@ _EXPECTATIONS += [
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '432',  # ERR_ERRONEOUSNICKNAME
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           _MsgTok.NICKNAME,
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
@@ -254,88 +254,88 @@ _EXPECTATIONS += [
                          (_MsgTok.NICKNAME,
                           _MsgTok.NICKNAME,
                           _MsgTok.ANY)),
-    _MsgParseExpectation((_MsgTok.USER_ADDRESS, 'named'),
+    _MsgParseExpectation((_MsgTok.USER_ADDRESS, ':named'),
                          'NICK',
-                         ((_MsgTok.NICKNAME, 'nickname'),)),
+                         ((_MsgTok.NICKNAME, ':nickname'),)),
 ]
 
 # joining/leaving
 _EXPECTATIONS += [
     _MsgParseExpectation(_MsgTok.SERVER,
                          '353',  # RPL_NAMREPLY
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
                           '=',
-                          (_MsgTok.CHANNEL, 'channel'),
-                          (_MsgTok.LIST, 'names'))),
+                          (_MsgTok.CHANNEL, ':channel'),
+                          (_MsgTok.LIST, ':names'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          '366',  # RPL_ENDOFNAMES
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.CHANNEL, 'channel'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.CHANNEL, ':channel'),
                           _MsgTok.ANY)),
-    _MsgParseExpectation((_MsgTok.USER_ADDRESS, 'joiner'),
+    _MsgParseExpectation((_MsgTok.USER_ADDRESS, ':joiner'),
                          'JOIN',
-                         ((_MsgTok.CHANNEL, 'channel'),)),
-    _MsgParseExpectation((_MsgTok.USER_ADDRESS, 'parter'),
+                         ((_MsgTok.CHANNEL, ':channel'),)),
+    _MsgParseExpectation((_MsgTok.USER_ADDRESS, ':parter'),
                          'PART',
-                         ((_MsgTok.CHANNEL, 'channel'),)),
-    _MsgParseExpectation((_MsgTok.USER_ADDRESS, 'parter'),
+                         ((_MsgTok.CHANNEL, ':channel'),)),
+    _MsgParseExpectation((_MsgTok.USER_ADDRESS, ':parter'),
                          'PART',
-                         ((_MsgTok.CHANNEL, 'channel'),
-                          (_MsgTok.ANY, 'reason'))),
+                         ((_MsgTok.CHANNEL, ':channel'),
+                          (_MsgTok.ANY, ':reason'))),
 ]
 
 # messaging
 _EXPECTATIONS += [
     _MsgParseExpectation(_MsgTok.SERVER,
                          '401',  # ERR_NOSUCKNICK
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.NICKNAME, 'target'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.NICKNAME, ':target'),
                           _MsgTok.ANY)),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'NOTICE',
                          ('*',
-                          (_MsgTok.ANY, 'message'))),
+                          (_MsgTok.ANY, ':message'))),
     _MsgParseExpectation(_MsgTok.SERVER,
                          'NOTICE',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.ANY, 'message'))),
-    _MsgParseExpectation((_MsgTok.USER_ADDRESS, 'sender'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.ANY, ':message'))),
+    _MsgParseExpectation((_MsgTok.USER_ADDRESS, ':sender'),
                          'NOTICE',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.ANY, 'message'))),
-    _MsgParseExpectation((_MsgTok.USER_ADDRESS, 'sender'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.ANY, ':message'))),
+    _MsgParseExpectation((_MsgTok.USER_ADDRESS, ':sender'),
                          'NOTICE',
-                         ((_MsgTok.CHANNEL, 'channel'),
-                          (_MsgTok.ANY, 'message'))),
-    _MsgParseExpectation((_MsgTok.USER_ADDRESS, 'sender'),
+                         ((_MsgTok.CHANNEL, ':channel'),
+                          (_MsgTok.ANY, ':message'))),
+    _MsgParseExpectation((_MsgTok.USER_ADDRESS, ':sender'),
                          'PRIVMSG',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.ANY, 'message'))),
-    _MsgParseExpectation((_MsgTok.USER_ADDRESS, 'sender'),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.ANY, ':message'))),
+    _MsgParseExpectation((_MsgTok.USER_ADDRESS, ':sender'),
                          'PRIVMSG',
-                         ((_MsgTok.CHANNEL, 'channel'),
-                          (_MsgTok.ANY, 'message'))),
+                         ((_MsgTok.CHANNEL, ':channel'),
+                          (_MsgTok.ANY, ':message'))),
 ]
 
 # misc.
 _EXPECTATIONS += [
     _MsgParseExpectation(_MsgTok.NONE,
                          'ERROR',
-                         ((_MsgTok.ANY, 'reason'),)),
+                         ((_MsgTok.ANY, 'set_db_attr:connection_state'),)),
     _MsgParseExpectation(_MsgTok.NICKNAME,
                          'MODE',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.ANY, 'mode'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.ANY, 'set_db_attr:user_modes'))),
     _MsgParseExpectation(_MsgTok.USER_ADDRESS,
                          'MODE',
-                         ((_MsgTok.NICKNAME, 'my_nickname'),
-                          (_MsgTok.ANY, 'mode'))),
+                         ((_MsgTok.NICKNAME, 'set_nick:my_nickname'),
+                          (_MsgTok.ANY, 'set_db_attr:user_modes'))),
     _MsgParseExpectation(_MsgTok.NONE,
                          'PING',
-                         ((_MsgTok.ANY, 'reply'),)),
-    _MsgParseExpectation((_MsgTok.USER_ADDRESS, 'quitter'),
+                         ((_MsgTok.ANY, ':reply'),)),
+    _MsgParseExpectation((_MsgTok.USER_ADDRESS, ':quitter'),
                          'QUIT',
-                         ((_MsgTok.ANY, 'message'),)),
+                         ((_MsgTok.ANY, ':message'),)),
 ]
 
 
@@ -821,7 +821,8 @@ class Client(ABC, ClientQueueMixin):
             return msg_tok
 
         for ex in [ex for ex in _EXPECTATIONS if ex.verb == msg.verb]:
-            to_return: dict[str, Any] = {'verb': ex.verb}
+            tasks: dict[str, list[str]] = {}
+            to_return: dict[str, Any] = {'verb': ex.verb, '_tasks': tasks}
             ex_tok_fields = tuple([ex.source] + list(ex.params))
             msg_params: list[str | list[str]]
             if ex.idx_into_list < 0:
@@ -839,6 +840,9 @@ class Client(ABC, ClientQueueMixin):
             for idx, ex_tok in enumerate(ex_tok_fields):
                 ex_tok, key = ((ex_tok[0], ex_tok[1])
                                if isinstance(ex_tok, tuple) else (ex_tok, ''))
+                task, key = key.split(':', maxsplit=1) if key else ('', '')
+                if task:
+                    tasks[task] = tasks.get(task, []) + [key]
                 to_return[key] = param_match(ex_tok, msg_tok_fields[idx])
                 if to_return[key] is None:
                     passing = False
@@ -851,11 +855,16 @@ class Client(ABC, ClientQueueMixin):
         'Log msg.raw, then process incoming msg into appropriate client steps.'
         self._log(msg.raw, scope=LogScope.RAW, out=False)
         ret = self._match_msg(msg)
-        if 'my_nickname' in ret:
-            self.set_nick(ret['my_nickname'], confirmed=True)
         if 'verb' not in ret:
             self._log(f'PLEASE IMPLEMENT HANDLER FOR: {msg.raw}')
-        elif ret['verb'] == '005':   # RPL_ISUPPORT
+            return
+        for task, args in ret['_tasks'].items():
+            for arg in args:
+                if task == 'set_db_attr':
+                    setattr(self._db, arg, ret[arg])
+                elif task == 'set_nick':
+                    self.set_nick(ret[arg], confirmed=True)
+        if ret['verb'] == '005':   # RPL_ISUPPORT
             for item in ret['isupports']:
                 toks = item.split('=', maxsplit=1)
                 if toks[0][0] == '-':
@@ -892,9 +901,7 @@ class Client(ABC, ClientQueueMixin):
         elif ret['verb'] == '900':  # RPL_LOGGEDIN
             self.set_nick(ret['full_address'][0], True)
             self._db.username, self._db.client_host = ret['full_address'][1:]
-            self._db.sasl_account = ret['account']
         elif ret['verb'] in {'903', '904'}:  # RPL_SASLSUCCESS, ERR_SASLFAIL
-            self._db.sasl_auth_state = ret['result']
             self._caps.end_negotiation()
         elif ret['verb'] == 'AUTHENTICATE':
             auth = b64encode((self._db.nick_wanted + '\0'
@@ -913,7 +920,6 @@ class Client(ABC, ClientQueueMixin):
                 else:
                     self._caps.end_negotiation()
         elif ret['verb'] == 'ERROR':
-            self._db.connection_state = ret['reason']
             self.close()
         elif ret['verb'] == 'JOIN':
             self._log(f'{ret["joiner"][0]} {msg.verb.lower()}s '
@@ -922,8 +928,6 @@ class Client(ABC, ClientQueueMixin):
             if ret['joiner'][0] != self._db.nickname:
                 ret['channel']['db'].append_completable('users',
                                                         ret['joiner'][0], True)
-        elif ret['verb'] == 'MODE':
-            self._db.user_modes = ret['mode']
         elif ret['verb'] == 'NICK':
             if ret['named'][0] == self._db.nickname:
                 self.set_nick(ret['nickname'], confirmed=True)