Edit
kc3-lang/libxkbcommon/scripts/update-message-registry.py
Pierre Le Marre
- scripts/update-message-registry.py
-
#!/usr/bin/env python3 from __future__ import annotations import argparse import random import re from dataclasses import astuple, dataclass from pathlib import Path from typing import Any, Callable, ClassVar, Generic, Sequence, TypeAlias, TypeVar import jinja2 import yaml @dataclass(order=True) class Version: """A semantic version number: MAJOR.MINOR.PATCH.""" UNKNOWN_VERSION: ClassVar[str] = "ALWAYS" DEFAULT_VERSION: ClassVar[str] = "1.0.0" major: int minor: int patch: int = 0 def __str__(self) -> str: return ".".join(map(str, astuple(self))) @classmethod def parse(cls, raw_version: str) -> Version: if raw_version == cls.UNKNOWN_VERSION: raw_version = cls.DEFAULT_VERSION version = raw_version.split(".") assert 2 <= len(version) <= 3 and all(n.isdecimal() for n in version), ( raw_version ) return Version(*map(int, version)) @dataclass class Example: """An example in a message entry.""" name: str description: str before: str | None after: str | None @classmethod def parse(cls, entry: dict[str, Any]) -> Example: name = entry.get("name") assert name, entry description = entry.get("description") assert description before = entry.get("before") after = entry.get("after") # Either none or both of them assert not (bool(before) ^ bool(after)) return Example(name=name, description=description, before=before, after=after) @dataclass class Entry: """An xkbcommon message entry in the message registry""" VALID_TYPES = ("warning", "error") code: int """A unique strictly positive integer identifier""" id: str """A unique short human-readable string identifier""" type: str """Log level of the message""" description: str """A short description of the meaning of the message""" details: str """A long description of the meaning of the message""" added: Version """Version of xkbcommon the message has been added""" removed: Version | None """Version of xkbcommon the message has been removed""" examples: tuple[Example, ...] """ Optional examples of situations in which the message occurs. If the message is an error or a warning, also provide hints on how to fix it. """ @classmethod def parse(cls, entry: dict[str, Any]) -> Entry: code = entry.get("code") assert code is not None and isinstance(code, int) and code > 0, entry id = entry.get("id") assert id is not None, entry type_ = entry.get("type") assert type_ in cls.VALID_TYPES, entry description = entry.get("description") assert description is not None, entry details = entry.get("details", "") raw_added = entry.get("added", "") assert raw_added, entry added = Version.parse(raw_added) assert added, entry if removed := entry.get("removed"): removed = Version.parse(removed) assert added < removed, entry if examples := entry.get("examples", ()): examples = tuple(map(Example.parse, examples)) return Entry( code=code, id=id, type=type_, description=description, added=added, removed=removed, details=details, examples=examples, ) @property def message_code(self) -> str: """Format the message code for display""" return f"XKB-{self.code:0>3}" @property def message_code_constant(self: Entry) -> str: """Returns the C enumeration member denoting the message code""" id = self.id.replace("-", "_").upper() return f"XKB_{self.type.upper()}_{id}" @property def message_name(self: Entry) -> str: """Format the message string identifier for display""" return self.id.replace("-", " ").capitalize() Registry: TypeAlias = Sequence[Entry] def prepend_todo(text: str) -> str: if text.startswith("TODO"): return f"""<span class="todo">{text[:5]}</span>{text[5:]}""" else: return text def load_message_registry( env: jinja2.Environment, constants: dict[str, int], path: Path ) -> Registry: # Load the message registry YAML file as a Jinja2 template registry_template = env.get_template(str(path)) # Load message registry message_registry = sorted( map(Entry.parse, yaml.safe_load(registry_template.render(constants))), key=lambda e: e.code, ) # Check message codes and identifiers are unique codes: set[int] = set() identifiers: set[str] = set() for n, entry in enumerate(message_registry): if entry.code in codes: raise ValueError(f"Duplicated code in entry #{n}: {entry.code}") if entry.id in identifiers: raise ValueError(f"Duplicated identifier in entry #{n}: {entry.id}") codes.add(entry.code) identifiers.add(entry.id) return message_registry def generate_file( registry: Registry, env: jinja2.Environment, root: Path, file: Path, skip_removed: bool = False, ) -> None: """Generate a file from its Jinja2 template and the message registry""" template_path = file.with_suffix(f"{file.suffix}.jinja") template = env.get_template(str(template_path)) path = root / file script = Path(__file__).name with path.open("wt", encoding="utf-8") as fd: entries = ( tuple(filter(lambda e: e.removed is None, registry)) if skip_removed else registry ) fd.writelines(template.generate(entries=entries, script=script)) T = TypeVar("T") @dataclass class Constant(Generic[T]): name: str pattern: re.Pattern[str] conversion: Callable[[str], T] def read_constants(path: Path, patterns: Sequence[Constant[T]]) -> dict[str, T]: constants: dict[str, T] = {} patternsʹ = list(patterns) with path.open("rt", encoding="utf-8") as fd: for line in fd: for k, constant in enumerate(patternsʹ): if m := constant.pattern.match(line): constants[constant.name] = constant.conversion(m.group(1)) del patternsʹ[k] continue # Expect only one match per line if not patternsʹ: # No more pattern to match break for constant in patternsʹ: print(f"ERROR: could not find constant: {constant.name}.") if patternsʹ: raise ValueError("Some constants were not found.") return constants def generate( args: argparse.Namespace, registry: Registry, jinja_env: jinja2.Environment ): """ Generate the files """ generate_file( registry, jinja_env, args.root, Path("src/messages-codes.h"), skip_removed=True, ) generate_file( registry, jinja_env, args.root, Path("tools/messages.c"), skip_removed=True ) generate_file(registry, jinja_env, args.root, Path("doc/message-registry.md")) def get_new_code( args: argparse.Namespace, registry: Registry, jinja_env: jinja2.Environment ): """ Get a free code """ # Get all codes codes = frozenset(entry.code for entry in registry) # Filter free ones free = tuple(code for code in range(args.min, args.max + 1) if code not in codes) print(*random.sample(free, k=args.count)) # Root of the project ROOT = Path(__file__).parent.parent # Parse commands parser = argparse.ArgumentParser(description="Generate files from the message registry") parser.add_argument( "--root", type=Path, default=ROOT, help="Path to the root of the project (default: %(default)s)", ) parser.set_defaults(func=generate) subparsers = parser.add_subparsers() new_id_parser = subparsers.add_parser("get-new-code", help="Get a new message codes") new_id_parser.set_defaults(func=get_new_code) new_id_parser.add_argument("--min", type=int, default=1, help="default: %(default)s") new_id_parser.add_argument("--max", type=int, default=999, help="default: %(default)s") new_id_parser.add_argument("--count", type=int, default=10, help="default: %(default)s") generate_parser = subparsers.add_parser("generate", help="Generate files") args = parser.parse_args() # Read some constants from libxkbcommon that we need constants = read_constants( Path(__file__).parent.parent / "src" / "keymap.h", ( Constant( "XKB_MAX_GROUPS", re.compile(r"^#define\s+XKB_MAX_GROUPS\s+(\d+)"), int, ), Constant( "XKB_MAX_GROUPS_X11", re.compile(r"^#define\s+XKB_MAX_GROUPS_X11\s+(\d+)"), int, ), ), ) # Configure Jinja template_loader = jinja2.FileSystemLoader(args.root, encoding="utf-8") jinja_env = jinja2.Environment( loader=template_loader, keep_trailing_newline=True, trim_blocks=True, lstrip_blocks=True, ) jinja_env.filters["prepend_todo"] = prepend_todo # Load message registry message_registry = load_message_registry( jinja_env, constants, Path("doc/message-registry.yaml") ) args.func(args=args, registry=message_registry, jinja_env=jinja_env)