From d6e97bea98d49406679767bf30ba2c8fe70b34c4 Mon Sep 17 00:00:00 2001 From: kuro Date: Sun, 18 Oct 2026 03:35:39 +0200 Subject: [PATCH] readme update --- README.md | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a076bbe..19ca508 100644 --- a/README.md +++ b/README.md @@ -19,12 +19,14 @@ The linter analyzes the code in real-time, remembers states across line breaks, * **Strict Hierarchy Checking:** Monitors the correct order of blocks within patterns and syncmappings (`metadata` -> `overview` -> `constants` -> `triggers` -> `mapping`/`removal` -> `body`). * **Smart Assignment Check:** Finds missing semicolons (but tolerates them in `enumeration` blocks or multi-line statements). Warns strictly with an error if `=` is used instead of `:=` for variable assignments (outside of legitimate `if`/`where` comparisons). * **Block & Bracket Tracking:** Detects unclosed blocks (like missing `end body;` or `end pattern;`) and finds unclosed parentheses `(` or brackets `[`. -* **Mandatory Field Validation:** Checks if mandatory module-level metadata (`origin`, `author`, `products`, `publishers`, `tree_path`) are present and if an initial `log.debug` statement exists in the `body`. +* **Mandatory Field Validation:** Checks if mandatory module-level metadata (`origin`, `author`, `products`, `publishers`, `tree_path`) are present based on your dynamic compliance settings, and if an initial `log.debug` statement exists in the `body`. +* **Indentation Checking (New):** Instantly highlights messy indentation (any space count that is not a clean multiple of 4) with a warning, reminding you to use the Auto-Formatter. * **Version Checking:** Compares the TPL version declared in the module with the target version defined in your settings and warns about outdated scripts. -### ⚙️ Configurable Plugin Settings +### ⚙️ Configurable Plugin Settings & Compliance Personalize the plugin directly via the VS Code user interface (File > Preferences > Settings > Extensions > BMC TPL Settings): -* **Default Metadata:** Store your own values for `Author`, `Publisher`, `Origin`, and `Tree Path`. These are automatically inserted when generating new modules. +* **Metadata Compliance (New):** Define exact compliance rules for your workspace. Choose which metadata fields are mandatory and configure the `tree_path` strictly (e.g., minimum depth and forced static base nodes like `['MyCompany', 'IT']`). +* **Default Metadata:** Store your own values for `Author`, `Publisher`, `Origin`, etc. These are automatically inserted when generating new modules. * **TPL Target Version:** Define the default TPL version (e.g., `23` for 1.23) you are developing for. * **Live Reload:** Changes to settings take effect immediately, no editor restart required. @@ -43,12 +45,12 @@ Saves an extreme amount of coding time through massive context awareness: ### 🔍 Hover Documentation (Tooltips) When you hover over a method name, a pattern, or a table: -* **Official BMC Docs:** Full integration of the original, multi-line BMC documentation for all built-in functions (no browser needed anymore!). +* **Official BMC Docs:** Full integration of the original, multi-line BMC documentation for all built-in functions loaded dynamically (no browser needed anymore!). * **DocString Extraction:** Reads custom multi-line comments (`"""` or `'''`) placed under `define` or `pattern` declarations and renders them as clean Markdown tooltips (even cross-project!). ### ⚡ Quick Fixes (Code Actions / Lightbulb) Offers immediate repair options with a single click: -* **"Insert missing module metadata":** Instantly generates all 5 mandatory fields in the module metadata block. +* **"Insert missing module metadata":** Instantly generates missing mandatory fields in the module metadata block based on your workspace compliance settings. * **"Insert log statement":** Adds the missing `log.debug("Start pattern...");` right at the beginning of the `body` block. * **"Tabs to Spaces":** Instantly replaces all illegal tabs (`\t`) in a line with 4 correct spaces each. @@ -60,10 +62,11 @@ Just type the keyword and press `Enter` to generate complete, perfectly indented | Keyword | Description | | :--- | :--- | -| `tpl_skeleton` | **God-Snippet**: Generates a completely fresh TPL module. Automatically uses your configured settings for metadata and version. | +| `tpl_skeleton` | **God-Snippet**: Generates a completely fresh TPL module. Automatically uses your configured compliance rules, settings, and dynamic tree paths. | +| `metadata` | **Context-Aware**: Knows where your cursor is. Generates a full module block at the top, or a compact pattern block inside a pattern. | | `pattern` / `syncmapping` | Builds an empty pattern/syncmapping block including DocString and end-tag. | | `define` | Generates a method definition (`define name(params) ... end define;`). | -| `metadata`, `overview`, `body`... | Builds the respective block and places the cursor right in the middle. | +| `overview`, `body`... | Builds the respective block and places the cursor right in the middle. | | `table` | Creates a table including the `default -> "unknown";` fallback. | | `if`, `elif`, `else` | Builds conditional statements incl. `then` and `end if;`, placing the cursor neatly at the condition. | | `for`, `while` | Builds standard loops incl. `do` and end-tag, letting you iterate directly. | @@ -111,12 +114,14 @@ Der Linter analysiert den Code in Echtzeit, merkt sich Zustände über Zeilenumb * **Strikte Hierarchie-Prüfung:** Überwacht die korrekte Reihenfolge der Blöcke innerhalb von Patterns und Syncmappings (`metadata` -> `overview` -> `constants` -> `triggers` -> `mapping`/`removal` -> `body`). * **Smarter Zuweisungs-Check:** Findet fehlende Semikolons (toleriert sie aber in `enumeration`-Blöcken oder bei umgebrochenen Code-Zeilen). Warnt streng mit einem Fehler, wenn `=` anstelle von `:=` für Variablenzuweisungen genutzt wird (außerhalb von legitimen `if`/`where` Vergleichen). * **Block- & Klammer-Tracking:** Erkennt nicht geschlossene Blöcke (wie fehlende `end body;` oder `end pattern;`) und findet ungeschlossene runde `(` oder eckige `[` Klammern. -* **Pflichtfeld-Validierung:** Prüft, ob auf Modul-Ebene zwingend benötigte Metadaten (`origin`, `author`, `products`, `publishers`, `tree_path`) vorhanden sind und ob im `body` ein initiales `log.debug` Statement steht. +* **Pflichtfeld-Validierung:** Prüft basierend auf deinen dynamischen Compliance-Settings, ob auf Modul-Ebene zwingend benötigte Metadaten (`origin`, `author`, `tree_path` etc.) vorhanden sind und ob im `body` ein initiales `log.debug` Statement steht. +* **Einrückungs-Prüfung (Neu):** Ein neuer Check im Hintergrund markiert unsaubere Einrückungen (alles, was kein sauberes Vielfaches von 4 Leerzeichen ist) sofort mit einer Warnung, um an den Auto-Formatter zu erinnern. * **Versions-Prüfung:** Gleicht die im Modul deklarierte TPL-Version mit der in deinen Settings definierten Version ab und warnt vor veralteten Skripten. -### ⚙️ Konfigurierbare Plugin-Einstellungen (Settings) +### ⚙️ Konfigurierbare Plugin-Einstellungen & Compliance Personalisiere das Plugin direkt über die VS Code Benutzeroberfläche (File > Preferences > Settings > Extensions > BMC TPL Einstellungen): -* **Standard Metadaten:** Hinterlege deine eigenen Werte für `Author`, `Publisher`, `Origin` und den `Tree Path`. Diese werden beim Generieren neuer Module automatisch eingesetzt. +* **Metadaten-Compliance (Neu):** Definiere exakte Regeln für deinen Workspace. Wähle, welche Felder Pflicht sind und konfiguriere den `tree_path` strikt (z.B. Mindest-Ebenen und feste Basis-Nodes wie `['MeineFirma', 'IT']`). +* **Standard Metadaten:** Hinterlege deine eigenen Werte für `Author`, `Publisher`, `Origin` etc. Diese werden beim Generieren neuer Module automatisch eingesetzt. * **TPL Zielversion:** Definiere die TPL-Version (z.B. `23` für 1.23), für die du standardmäßig entwickelst. * **Live-Reload:** Änderungen an den Einstellungen greifen sofort, ganz ohne Neustart des Editors. @@ -130,7 +135,7 @@ Schluss mit kaputten Einrückungen! Der Formatter bringt deinen Code in Bestform Spart extrem viel Zeit beim Coden durch massives Kontext-Wissen: * **Volle BMC Standard-Bibliothek:** Nahtlose Integration aller Built-In Funktionen (z.B. `discovery`, `number`, `text`, `model`). Unterstützt Parameter-Überladungen (z.B. `number.toText` wahlweise mit oder ohne Basis) per Tab-Navigation. * **Workspace-Scanning:** Importierst du ein Modul (z.B. `from company.helpers import my_helper`), durchsucht das Plugin im Hintergrund dein gesamtes Projekt. Tippst du `my_helper.`, werden dir automatisch alle verfügbaren `define`-Methoden vorgeschlagen. -* **Lokale Namespaces:** Erkennt `definitions`-Blöcke in class gleichen Datei und schlägt deren Methoden vor. +* **Lokale Namespaces:** Erkennt `definitions`-Blöcke in der gleichen Datei und schlägt deren Methoden vor. * **Variablen-Tracking:** Lernt alle Variablen, die du mit `:=` definiert hast, und schlägt sie dir später vor. ### 🔍 Hover-Dokumentation (Tooltips) @@ -140,7 +145,7 @@ Wenn du mit der Maus über einem Methodennamen, einem Pattern oder einer Tabelle ### ⚡ Quick Fixes (Code Actions / Glühbirne) Bietet sofortige Reparaturoptionen mit einem Klick: -* **"Fehlende Modul-Metadaten einfügen":** Generiert sofort alle 5 Pflichtfelder im Modul-Metadata-Block. +* **"Fehlende Modul-Metadaten einfügen":** Generiert sofort alle fehlenden Pflichtfelder im Modul-Metadata-Block, basierend auf deinen Compliance-Settings. * **"Log-Statement einfügen":** Baut das fehlende `log.debug("Start pattern...");` direkt am Anfang des `body`-Blocks ein. * **"Tabs zu Spaces":** Ersetzt sofort alle illegalen Tabs (`\t`) in einer Zeile durch jeweils 4 korrekte Leerzeichen. @@ -152,10 +157,11 @@ Einfach das Keyword tippen und `Enter` drücken, um komplette, perfekt eingerüc | Keyword | Beschreibung | | :--- | :--- | -| `tpl_skeleton` | **God-Snippet**: Generiert ein komplett frisches TPL Modul. Nutzt automatisch deine hinterlegten Settings für Metadaten und Version. | +| `tpl_skeleton` | **God-Snippet**: Generiert ein komplett frisches TPL Modul. Nutzt automatisch deine hinterlegten Settings, dynamischen Tree-Paths und Compliance-Regeln. | +| `metadata` | **Kontext-sensitiv**: Weiß genau, wo dein Cursor steht. Generiert einen großen Modul-Block ganz oben oder einen kompakten Pattern-Block innerhalb eines Patterns. | | `pattern` / `syncmapping` | Baut einen leeren Pattern/Syncmapping-Block inklusive DocString und End-Tag. | | `define` | Generiert eine Methodendefinition (`define name(params) ... end define;`). | -| `metadata`, `overview`, `body`... | Baut den jeweiligen Block auf und platziert den Cursor in der Mitte. | +| `overview`, `body`... | Baut den jeweiligen Block auf und platziert den Cursor in der Mitte. | | `table` | Erstellt eine Tabelle inklusive des `default -> "unknown";` Fallbacks. | | `if`, `elif`, `else` | Baut bedingte Abfragen inkl. `then` und `end if;` und platziert den Cursor sauber bei der Bedingung. | | `for`, `while` | Baut Standard-Schleifen inkl. `do` und End-Tag und lässt dich direkt iterieren. |