add explicit IRC-aware comparison keys

(cherry picked from commit 5029a34fcb)

docs/plugin-api-additions/compatibility.md

@@ -0,0 +1,24 @@
+# Optional plugin API additions (discussion #144)
+
+Existing hooks, callbacks, return values, context lookup, strings and menu behaviour
+remain unchanged. The C plugin function table gains four fixed append-only slots;
+unused slots are NULL. Older binaries use the unchanged prefix. A plugin must check
+the documented get_info() feature key before accessing a new slot on an older host.
+New Python modules are installed by Meson and the existing Windows copy/installer
+pipeline. Only modules present in the installation are exported; imports of
+zoitechat, hexchat and xchat retain their compatibility aliases.
+
+All APIs run on the client main thread unless explicitly documented otherwise.
+New reserved flags must be zero. These changes do not make old API calls thread-safe.
+
+Nested hook dispatch defers deleted-hook reclamation until its outermost return,
+so new observers can safely emit events and unhook themselves or other hooks.
+
+The optional asyncio module requires Python 3.7 or newer; older supported
+interpreters skip that module and retain the existing scripting API.
+
+Python reload drops the script/API modules while retaining the embedding module
+so callback and lib.ph pointer types keep the same CFFI identity.
+
+Server-hook insertion matches both raw and attrs hooks so documented priorities
+are honoured for mixed registrations, including new filtered attrs callbacks.

docs/plugin-api-additions/names.md

@@ -0,0 +1,21 @@
+# Explicit IRC comparison keys
+
+`IRCName(text, context=None, casemapping=None, connection_id=None)` is an
+immutable helper, not a str subclass. Construct it explicitly for dictionary/set
+keys; existing get_info/list/event values remain normal strings.
+Equality and hashing include the connection ID and captured casemapping, so
+identical-looking names on different connections are different keys. An IRCName
+never compares equal to a plain str. `str(key)` / `key.text` recover the spelling.
+
+`irc_casefold(text, casemapping='rfc1459')` supports ascii, strict-rfc1459 and
+rfc1459. Only ASCII IRC characters fold; Unicode casefold would be incorrect.
+The new `get_info('casemapping')` reports the comparator actually used by core.
+Current master handles ASCII and RFC1459; this patch does not change its handling
+of advertised strict-rfc1459. An explicit mapping is available for scripts that
+need strict-rfc1459 independently. Keys capture their mapping so hashes stay
+stable; rebuild a collection if the connection's mapping changes.
+
+```python
+seen = {zoitechat.IRCName('[SomeNick]')}
+assert zoitechat.IRCName('{somenick}') in seen  # RFC1459 connection
+```

plugins/python/_zoitechat.py

@@ -383,3 +383,24 @@ def find_context(server=None, channel=None):
         return None
 
     return Context(ctx)
+
+
+# Optional additive APIs live in separate modules so builds can select features.
+def __load_additive_features():
+    import importlib
+    import os
+
+    for suffix in ('fd', 'events', 'async', 'names', 'contexts',
+                   'post', 'filters', 'caps'):
+        if suffix == 'async' and sys.version_info < (3, 7):
+            continue
+        name = '_zoitechat_' + suffix
+        if not os.path.isfile(os.path.join(os.path.dirname(__file__), name + '.py')):
+            continue
+        module = importlib.import_module(name)
+        for symbol in module.__all__:
+            globals()[symbol] = getattr(module, symbol)
+            __all__.append(symbol)
+
+
+__load_additive_features()

plugins/python/_zoitechat_names.py

@@ -0,0 +1,74 @@
+"""Explicit immutable IRC names; existing string-returning APIs are unchanged."""
+import _zoitechat as api
+
+__all__ = ['IRCName', 'irc_casefold']
+
+
+def irc_casefold(text, casemapping='rfc1459'):
+    """Fold ASCII IRC characters only; never apply Unicode lower()/casefold()."""
+    if casemapping not in ('ascii', 'strict-rfc1459', 'rfc1459'):
+        raise ValueError('unsupported IRC casemapping')
+    extra = {'[': '{', ']': '}', '\\': '|'} if casemapping != 'ascii' else {}
+    if casemapping == 'rfc1459':
+        extra['^'] = '~'
+    return ''.join(chr(ord(c) + 32) if 'A' <= c <= 'Z' else extra.get(c, c)
+                   for c in text)
+
+
+class IRCName:
+    """Equality/hash include connection identity and the captured casemapping."""
+    __slots__ = ('_text', '_casemapping', '_connection_id', '_key')
+
+    def __init__(self, text, context=None, casemapping=None, connection_id=None):
+        context = context or api.get_context()
+        if casemapping is None:
+            casemapping = context.get_info('casemapping')
+            if casemapping is None:
+                raise RuntimeError('host does not expose its comparison casemapping')
+        if connection_id is None:
+            previous = api.get_context()
+            if not context.set():
+                raise ValueError('context has closed')
+            try:
+                connection_id = api.get_prefs('id')
+            finally:
+                previous.set()
+        object.__setattr__(self, '_text', text)
+        object.__setattr__(self, '_casemapping', casemapping)
+        object.__setattr__(self, '_connection_id', connection_id)
+        object.__setattr__(self, '_key', (connection_id, casemapping,
+                                       irc_casefold(text, casemapping)))
+
+    def __setattr__(self, name, value):
+        raise AttributeError('IRCName is immutable')
+
+    @property
+    def text(self):
+        return self._text
+
+    @property
+    def casemapping(self):
+        return self._casemapping
+
+    @property
+    def connection_id(self):
+        return self._connection_id
+
+    def __str__(self):
+        return self._text
+
+    def __repr__(self):
+        return 'IRCName({!r}, casemapping={!r}, connection_id={!r})'.format(
+            self._text, self._casemapping, self._connection_id)
+
+    def __eq__(self, other):
+        if not isinstance(other, IRCName):
+            return NotImplemented
+        return self._key == other._key
+
+    def __ne__(self, other):
+        result = self.__eq__(other)
+        return NotImplemented if result is NotImplemented else not result
+
+    def __hash__(self):
+        return hash(self._key)

plugins/python/meson.build

@@ -27,7 +27,11 @@ python3_source = custom_target('python-bindings',
   command: [find_program('generate_plugin.py'), '@INPUT@', '@OUTPUT@']
 )
 
-install_data(['_zoitechat.py', 'zoitechat.py', 'xchat.py', 'hexchat.py'],
+# Include any selected additive API modules alongside the compatibility modules.
+python_api_files = run_command(python3, '-c',
+  'import glob,sys; print("\\n".join(sorted(glob.glob(sys.argv[1] + "/_zoitechat*.py"))))',
+  meson.current_source_dir(), check: true).stdout().strip().split('\n')
+install_data(python_api_files + ['zoitechat.py', 'xchat.py', 'hexchat.py'],
   install_dir: join_paths(get_option('libdir'), 'zoitechat/python')
 )
 

plugins/python/python.py

@@ -590,7 +590,12 @@ def _on_plugin_deinit():
     sys.stderr = sys.__stderr__
     pydoc.help = pydoc.Helper()
 
-    for mod in ('_zoitechat', 'zoitechat', 'xchat', '_zoitechat_embedded'):
+    # CFFI callbacks keep the embedding module's ffi/lib identity for the
+    # process lifetime; deleting it creates incompatible types on reload.
+    for mod in ('_zoitechat', 'zoitechat', 'hexchat', 'xchat',
+                '_zoitechat_fd', '_zoitechat_events', '_zoitechat_async',
+                '_zoitechat_names', '_zoitechat_contexts', '_zoitechat_post',
+                '_zoitechat_filters', '_zoitechat_caps'):
         try:
             del sys.modules[mod]
 

plugins/python/python3.vcxproj

@@ -52,6 +52,7 @@
     <None Include="xchat.py" />
     <None Include="hexchat.py" />
     <None Include="_zoitechat.py" />
+    <None Include="_zoitechat_*.py" />
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="$(IntDir)python.c" />

plugins/python/python38.vcxproj

@@ -52,6 +52,7 @@
     <None Include="xchat.py" />
     <None Include="hexchat.py" />
     <None Include="_zoitechat.py" />
+    <None Include="_zoitechat_*.py" />
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="$(IntDir)python.c" />

src/common/plugin.c

@@ -176,6 +176,7 @@ enum
 
 GSList *plugin_list = NULL;	/* export for plugingui.c */
 static GSList *hook_list = NULL;
+static unsigned int plugin_dispatch_depth;
 
 extern const struct prefs vars[];	/* cfgfiles.c */
 
@@ -243,7 +244,7 @@ plugin_list_add (zoitechat_context *ctx, char *filename, const char *name,
 {
 	zoitechat_plugin *pl;
 
-	pl = g_new (zoitechat_plugin, 1);
+	pl = g_new0 (zoitechat_plugin, 1);
 	pl->handle = handle;
 	pl->filename = filename;
 	pl->context = ctx;
@@ -610,6 +611,7 @@ plugin_hook_run (session *sess, char *name, char *word[], char *word_eol[],
 	zoitechat_hook *hook;
 	int ret, eat = 0;
 
+	plugin_dispatch_depth++;
 	list = hook_list;
 	while (1)
 	{
@@ -655,6 +657,10 @@ plugin_hook_run (session *sess, char *name, char *word[], char *word_eol[],
 	}
 
 xit:
+	/* Nested callbacks can unhook entries still used by an outer dispatch.
+	 * Keep both hook objects and list links alive until the outermost return. */
+	if (--plugin_dispatch_depth != 0)
+		return eat;
 	/* really remove deleted hooks now */
 	list = hook_list;
 	while (list)
@@ -806,7 +812,7 @@ plugin_insert_hook (zoitechat_hook *new_hook)
 			break;
 		case HOOK_SERVER:
 		case HOOK_SERVER_ATTRS:
-			new_hook_type = HOOK_SERVER | HOOK_PRINT_ATTRS;
+			new_hook_type = HOOK_SERVER | HOOK_SERVER_ATTRS;
 			break;
 		default:
 			new_hook_type = new_hook->type;
@@ -1181,6 +1187,16 @@ zoitechat_get_info (zoitechat_plugin *ph, const char *id)
 		return text_find_format_string (e);
 	}
 
+	/* Report the comparison actually used by this connection, not an
+	 * advertised mapping that the current core does not implement. */
+	if (strcmp (id, "casemapping") == 0)
+	{
+		if (!is_session (ph->context))
+			return NULL;
+		return ph->context->server->p_cmp == g_ascii_strcasecmp
+			? "ascii" : "rfc1459";
+	}
+
 	hash = str_hash (id);
 	/* do the session independant ones first */
 	switch (hash)

src/common/plugin.h

@@ -150,6 +150,15 @@ struct _zoitechat_plugin
 	void (*zoitechat_event_attrs_free) (zoitechat_plugin *ph,
 									  zoitechat_event_attrs *attrs);
 
+	/* Additive API slots: append only; old binary offsets are unchanged. */
+	zoitechat_hook *(*zoitechat_hook_print_after) (zoitechat_plugin *, const char *, int,
+		int, int (*)(char *[], zoitechat_event_attrs *, void *), void *);
+	zoitechat_hook *(*zoitechat_hook_server_filtered) (zoitechat_plugin *, const char *, int,
+		int, int, const char *, int (*)(char *[], char *[], zoitechat_event_attrs *, void *), void *);
+	zoitechat_hook *(*zoitechat_hook_print_filtered) (zoitechat_plugin *, const char *, int,
+		int, int, const char *, int (*)(char *[], zoitechat_event_attrs *, void *), void *);
+	zoitechat_hook *(*zoitechat_register_capability) (zoitechat_plugin *, const char *, int, int, void *);
+
 	/* PRIVATE FIELDS! */
 	void *handle;		/* from dlopen */
 	char *filename;	/* loaded from */

src/common/zoitechat-plugin.h

@@ -193,6 +193,15 @@ struct _zoitechat_plugin
 	zoitechat_event_attrs *(*zoitechat_event_attrs_create) (zoitechat_plugin *ph);
 	void (*zoitechat_event_attrs_free) (zoitechat_plugin *ph,
 									  zoitechat_event_attrs *attrs);
+	/* Additive API slots: append only; old binary offsets are unchanged. */
+	zoitechat_hook *(*zoitechat_hook_print_after) (zoitechat_plugin *, const char *, int,
+		int, int (*)(char *[], zoitechat_event_attrs *, void *), void *);
+	zoitechat_hook *(*zoitechat_hook_server_filtered) (zoitechat_plugin *, const char *, int,
+		int, int, const char *, int (*)(char *[], char *[], zoitechat_event_attrs *, void *), void *);
+	zoitechat_hook *(*zoitechat_hook_print_filtered) (zoitechat_plugin *, const char *, int,
+		int, int, const char *, int (*)(char *[], zoitechat_event_attrs *, void *), void *);
+	zoitechat_hook *(*zoitechat_register_capability) (zoitechat_plugin *, const char *, int, int, void *);
+
 };
 #endif
 

win32/copy/copy.vcxproj

@@ -90,6 +90,7 @@
       <MSWindowsTheme Include="$(DepsRoot)\share\themes\MS-Windows\**\*" />
       <HicolorIcons Include="$(DepsRoot)\share\icons\hicolor\index.theme" />
       <HicolorIcons Include="$(DepsRoot)\share\icons\hicolor\**\*.*" />
+      <PythonAdditiveApis Include="..\..\plugins\python\_zoitechat_*.py" />
     </ItemGroup>
 
     <Copy SourceFiles="@(None)" DestinationFolder="$(ZoiteChatRel)" />
@@ -115,6 +116,7 @@
     <Copy SourceFiles="..\..\plugins\python\hexchat.py" DestinationFolder="$(ZoiteChatRel)\python" Condition="'$(Python3Enabled)'=='true' or '$(Python38Enabled)'=='true'" />
     <Copy SourceFiles="..\..\plugins\python\zoitechat.py" DestinationFolder="$(ZoiteChatRel)\python" Condition="'$(Python3Enabled)'=='true' or '$(Python38Enabled)'=='true'" />
     <Copy SourceFiles="..\..\plugins\python\_zoitechat.py" DestinationFolder="$(ZoiteChatRel)\python" Condition="'$(Python3Enabled)'=='true' or '$(Python38Enabled)'=='true'" />
+    <Copy SourceFiles="@(PythonAdditiveApis)" DestinationFolder="$(ZoiteChatRel)\python" Condition="('$(Python3Enabled)'=='true' or '$(Python38Enabled)'=='true') and '@(PythonAdditiveApis)' != ''" />
 
     <WriteLinesToFile File="$(ZoiteChatRel)portable-mode" Lines="2" Overwrite="true" />