Rewrite parser and Register methods to use global keys for event IDs

It is preferred to use the abstraction of the global event key, in case event IDs change in the future

Author: Foereaper

docs/ElunaDoc/__main__.py

@@ -1,126 +1,223 @@
 import os
 import shutil
 import typing
-from jinja2 import Environment, FileSystemLoader
-from typedecorator import params, returns
-from ElunaDoc.parser import ClassParser, MethodDoc
 import glob
 import time
+import re
+from jinja2 import Environment, FileSystemLoader
+from typedecorator import params, returns
+
+from ElunaDoc.parser import ClassParser
 
 
 @returns([(str, typing.IO)])
 @params(search_path=str)
 def find_class_files(search_path):
-    """Find and open all files containing Eluna class methods in `search_path`.
-
-    :param search_path: the path to search for Eluna methods in
-    :return: a list of all files containing Eluna methods, and the name of their respective classes
-    """
-    # Get the current working dir and switch to the search path.
+    """Find and open all files containing Eluna class methods in `search_path`."""
     old_dir = os.getcwd()
     os.chdir(search_path)
-    # Search for all files ending in "Methods.h", and exclude BigIntMethods.h
-    method_file_names = [file_name for file_name in glob.glob('*Methods.h') if file_name != 'BigIntMethods.h']
-    # Open each file.
-    method_files = [open(file_name, 'r') for file_name in method_file_names]
-    # Go back to where we were before.
+    method_file_names = [file_name for file_name in glob.glob("*Methods.h") if file_name != "BigIntMethods.h"]
+    method_files = [open(file_name, "r", encoding="utf-8") for file_name in method_file_names]
     os.chdir(old_dir)
     return method_files
 
 
 def make_renderer(template_path, link_parser_factory):
     """Return a function that can be used to render Jinja2 templates from the `template_path` directory."""
-
-    # Set up jinja2 environment to load templates from the templates folder.
     env = Environment(loader=FileSystemLoader(template_path))
 
-
     def inner(template_name, output_path, level, **kwargs):
-        env.filters['parse_links'], env.filters['parse_data_type'] = link_parser_factory(level)
+        env.filters["parse_links"], env.filters["parse_data_type"] = link_parser_factory(level)
         template = env.get_template(template_name)
         static = make_static(level)
         root = make_root(level)
 
-        with open('build/' + output_path, 'w') as out:
+        with open("build/" + output_path, "w", encoding="utf-8") as out:
             out.write(template.render(level=level, static=static, root=root, **kwargs))
 
     return inner
 
 
 def make_static(level):
-    return lambda file_name: ('../' * level) + 'static/' + file_name
+    return lambda file_name: ("../" * level) + "static/" + file_name
 
 
 def make_root(level):
-    return lambda file_name: ('../' * level) + file_name
+    return lambda file_name: ("../" * level) + file_name
+
 
+# ---------------- Hooks.h parsing (events.<category>.<name>) ----------------
 
-if __name__ == '__main__':
+_macro_start = re.compile(r"^\s*#define\s+([A-Z0-9_]+)_EVENTS_LIST\(X\)\s*\\\s*$")
+_macro_item = re.compile(r'^\s*X\(\s*([A-Z0-9_]+)\s*,\s*([0-9]+)\s*,\s*"([^"]+)"\s*\)\s*\\?\s*$')
+
+# Capture: { "category", SomeEventsTable, CountOf(SomeEventsTable) },
+_hook_table_entry = re.compile(
+    r'^\s*\{\s*"([^"]+)"\s*,\s*([A-Za-z0-9_]+)\s*,\s*CountOf\(\2\)\s*\}\s*,?\s*$'
+)
+
+
+def _table_name_to_macro_key(events_table_name: str) -> str:
+    """
+    Converts 'InstanceEventsTable' -> 'instance'
+             'GameObjectEventsTable' -> 'gameobject'
+             'PacketEventsTable' -> 'packet'
+    """
+    suffix = "EventsTable"
+    if events_table_name.endswith(suffix):
+        return events_table_name[: -len(suffix)].lower()
+    return events_table_name.lower()
+
+
+def parse_macro_lists(hooks_h_path: str) -> dict[str, dict[str, dict]]:
+    """
+    Return mapping per macro_category (derived from *_EVENTS_LIST macro name):
+      {
+        "spell": {
+          "by_id":   { 1: "on_cast", ... },
+          "by_enum": { "SPELL_EVENT_ON_CAST": (1, "on_cast"), ... }
+        },
+        ...
+      }
+    """
+    hooks: dict[str, dict[str, dict]] = {}
+    current: str | None = None
+
+    with open(hooks_h_path, "r", encoding="utf-8") as f:
+        for line in f:
+            m = _macro_start.match(line)
+            if m:
+                current = m.group(1).lower()  # e.g. SPELL -> "spell", INSTANCE -> "instance"
+                hooks.setdefault(current, {"by_id": {}, "by_enum": {}})
+                continue
+
+            if current:
+                mi = _macro_item.match(line)
+                if mi:
+                    enum_name = mi.group(1)
+                    id_value = int(mi.group(2))
+                    lua_name = mi.group(3)
+                    hooks[current]["by_id"][id_value] = lua_name
+                    hooks[current]["by_enum"][enum_name] = (id_value, lua_name)
+                    continue
+
+                # End macro block when we hit a line not continuing with '\'
+                if not line.rstrip().endswith("\\"):
+                    current = None
+
+    return hooks
+
+
+def build_exported_hook_map(hooks_h_path: str) -> dict[str, dict]:
+    """
+    Builds a map keyed by exported Lua category from HookTypeTable.
+
+    IMPORTANT: the macro key is derived from the backing EventsTable name, not the exported category.
+    Example:
+      { "map", InstanceEventsTable, CountOf(InstanceEventsTable) }
+      -> macro key = "instance" -> INSTANCE_EVENTS_LIST
+    """
+    macro_lists = parse_macro_lists(hooks_h_path)
+
+    exported: dict[str, dict] = {}
+    in_hook_table = False
+
+    with open(hooks_h_path, "r", encoding="utf-8") as f:
+        for line in f:
+            if "static constexpr HookStorage HookTypeTable" in line:
+                in_hook_table = True
+                continue
+            if in_hook_table and "};" in line:
+                in_hook_table = False
+                continue
+            if not in_hook_table:
+                continue
+
+            m = _hook_table_entry.match(line)
+            if not m:
+                continue
+
+            exported_category = m.group(1)   # e.g. "map"
+            events_table_name = m.group(2)   # e.g. "InstanceEventsTable"
+
+            macro_key = _table_name_to_macro_key(events_table_name)  # e.g. "instance"
+            table_map = macro_lists.get(macro_key)
+
+            if not table_map:
+                exported[exported_category] = {"by_id": {}, "by_enum": {}}
+                print(
+                    f"[docs] Warning: HookTypeTable exports '{exported_category}' ({events_table_name}) "
+                    f"but no matching *_EVENTS_LIST was found for key '{macro_key}'"
+                )
+                continue
+
+            exported[exported_category] = table_map
+
+    return exported
+
+
+# ---------------- Main ----------------
+
+if __name__ == "__main__":
     # Recreate the build folder and copy static files over.
-    if os.path.exists('build'):
-        shutil.rmtree('build')
-    os.mkdir('build')
-    shutil.copytree('ElunaDoc/static', 'build/static')
+    if os.path.exists("build"):
+        shutil.rmtree("build")
+    os.mkdir("build")
+    shutil.copytree("ElunaDoc/static", "build/static")
+
+    # Load hook globals (events.<category>.<name>) from Hooks.h
+    hooks_path = os.path.normpath(os.path.join(os.path.dirname(__file__), "..", "..", "hooks", "Hooks.h"))
+    print(f"Loading hook globals from: {hooks_path}")
+    exported_hooks = build_exported_hook_map(hooks_path)
 
     # Load up all files with methods we need to parse.
-    # Hard-coded to the TC files for now. Will have to add core support later on.
-    print('Finding Eluna method files...')
-    class_files = find_class_files('../methods/TrinityCore/')
+    print("Finding Eluna method files...")
+    class_files = find_class_files("../methods/TrinityCore/")
 
     # Parse all the method files.
     classes = []
     for f in class_files:
-        print(f'Parsing file {f.name}...')
-        classes.append(ClassParser.parse_file(f))
+        print(f"Parsing file {f.name}...")
+        classes.append(ClassParser.parse_file(f, exported_hooks=exported_hooks))
         f.close()
 
     # Sort the classes so they are in the correct order in lists.
     classes.sort(key=lambda c: c.name)
 
     def make_parsers(level):
-        """Returns a function that parses content for refs to other classes, methods, or enums,
-        and automatically inserts the correct link.
-        """
-        # Make lists of all class names and method names.
+        """Returns filters that parse refs to other classes/methods/enums and insert links."""
         class_names = []
         method_names = []
 
         for class_ in classes:
-            class_names.append('[' + class_.name + ']')
-
+            class_names.append("[" + class_.name + "]")
             for method in class_.methods:
-                method_names.append('[' + class_.name + ':' + method.name + ']')
+                method_names.append("[" + class_.name + ":" + method.name + "]")
 
         def link_parser(content):
-            # Replace all occurrencies of &Class:Function and then &Class with a link to given func or class
-
+            # Replace [Class:Method] and [Class] with links
             for name in method_names:
-                # Take the [] off the front of the method's name.
                 full_name = name[1:-1]
-                # Split "Class:Method" into "Class" and "Method".
-                class_name, method_name = full_name.split(':')
-                url = '{}{}/{}.html'.format(('../' * level), class_name, method_name)
-                # Replace occurrencies of &Class:Method with the url created
+                class_name, method_name = full_name.split(":")
+                url = "{}{}/{}.html".format(("../" * level), class_name, method_name)
                 content = content.replace(name, '<a class="fn" href="{}">{}</a>'.format(url, full_name))
 
             for name in class_names:
-                # Take the [] off the front of the class's name.
                 class_name = name[1:-1]
-                url = '{}{}/index.html'.format(('../' * level), class_name)
-                # Replace occurrencies of &Class:Method with the url created
+                url = "{}{}/index.html".format(("../" * level), class_name)
                 content = content.replace(name, '<a class="mod" href="{}">{}</a>'.format(url, class_name))
 
             return content
 
         # Links to the "Programming in Lua" documentation for each Lua type.
         lua_type_documentation = {
-            'nil': 'http://www.lua.org/pil/2.1.html',
-            'boolean': 'http://www.lua.org/pil/2.2.html',
-            'number': 'http://www.lua.org/pil/2.3.html',
-            'string': 'http://www.lua.org/pil/2.4.html',
-            'table': 'http://www.lua.org/pil/2.5.html',
-            'function': 'http://www.lua.org/pil/2.6.html',
-            '...': 'http://www.lua.org/pil/5.2.html',
+            "nil": "http://www.lua.org/pil/2.1.html",
+            "boolean": "http://www.lua.org/pil/2.2.html",
+            "number": "http://www.lua.org/pil/2.3.html",
+            "string": "http://www.lua.org/pil/2.4.html",
+            "table": "http://www.lua.org/pil/2.5.html",
+            "function": "http://www.lua.org/pil/2.6.html",
+            "...": "http://www.lua.org/pil/5.2.html",
         }
 
         def data_type_parser(content):
@@ -132,44 +229,44 @@ def data_type_parser(content):
             # Otherwise try to build a link to the proper page.
             if content in class_names:
                 class_name = content[1:-1]
-                url = '{}{}/index.html'.format(('../' * level), class_name)
+                url = "{}{}/index.html".format(("../" * level), class_name)
                 return '<strong><a class="mod" href="{}">{}</a></strong>'.format(url, class_name)
 
             # Case for enums to direct to a search on github
             enum_name = content[1:-1]
-            url = 'https://github.com/ElunaLuaEngine/ElunaTrinityWotlk/search?l=cpp&q=%22enum+{}%22&type=Code&utf8=%E2%9C%93'.format(enum_name)
+            url = (
+                'https://github.com/ElunaLuaEngine/ElunaTrinityWotlk/search?l=cpp&q=%22enum+{}%22'
+                "&type=Code&utf8=%E2%9C%93"
+            ).format(enum_name)
             return '<strong><a href="{}">{}</a></strong>'.format(url, enum_name)
 
-            # By default we just return the name without the [] around it
-            return content[1:-1]
-
         return link_parser, data_type_parser
 
     # Create the render function with the template path and parser maker.
-    render = make_renderer('ElunaDoc/templates', make_parsers)
+    render = make_renderer("ElunaDoc/templates", make_parsers)
 
     # Render the index.
-    render('index.html', 'index.html', level=0, classes=classes)
+    render("index.html", "index.html", level=0, classes=classes)
     # Render the search index.
-    render('search-index.js', 'search-index.js', level=0, classes=classes)
+    render("search-index.js", "search-index.js", level=0, classes=classes)
     # Render the date.
-    render('date.js', 'date.js', level=0, currdate=time.strftime("%d/%m/%Y"))
+    render("date.js", "date.js", level=0, currdate=time.strftime("%d/%m/%Y"))
 
     for class_ in classes:
-        print(f'Rendering pages for class {class_.name}...')
+        print(f"Rendering pages for class {class_.name}...")
 
         # Make a folder for the class.
-        os.mkdir('build/' + class_.name)
-        index_path = '{}/index.html'.format(class_.name)
-        sidebar_path = '{}/sidebar.js'.format(class_.name)
+        os.mkdir("build/" + class_.name)
+        index_path = "{}/index.html".format(class_.name)
+        sidebar_path = "{}/sidebar.js".format(class_.name)
 
         # Render the class's index page.
-        render('class.html', index_path, level=1, classes=classes, current_class=class_)
+        render("class.html", index_path, level=1, classes=classes, current_class=class_)
 
         # Render the class's sidebar script.
-        render('sidebar.js', sidebar_path, level=1, classes=classes, current_class=class_)
+        render("sidebar.js", sidebar_path, level=1, classes=classes, current_class=class_)
 
         # Render each method's page.
         for method in class_.methods:
-            method_path = '{}/{}.html'.format(class_.name, method.name)
-            render('method.html', method_path, level=1, current_class=class_, current_method=method)
+            method_path = "{}/{}.html".format(class_.name, method.name)
+            render("method.html", method_path, level=1, current_class=class_, current_method=method)