Table of Contents
🏗️ Architektur & Struktur
Diese Seite richtet sich an Entwickler (und an das zukünftige Ich), die den Quellcode der BMC TPL Code All around Extension verstehen, erweitern oder debuggen möchten.
Die Erweiterung nutzt die native Visual Studio Code Extension API und verzichtet bewusst auf einen schweren, externen Language Server, um maximale Performance und einfache Wartbarkeit zu garantieren.
📂 Projektstruktur (Ziel-Architektur)
Um den Code wartbar zu halten und nicht alles in wenige, riesige Dateien zu packen, folgt das Projekt dieser logischen Modul-Struktur:
```text src/ ├── core/ │ └── TplLinter.ts # Kernlogik des Syntax-Scanners und State-Trackings ├── providers/ │ ├── TplCompletionProvider.ts # Autovervollständigung & Snippets │ ├── TplHoverProvider.ts # Tooltips und DocString-Parsing │ ├── TplDocumentFormatter.ts # Auto-Formatierung & Visual Alignment │ └── TplCodeActionProvider.ts # Quick Fixes (Glühbirne) ├── data/ │ └── TplBuiltIns.ts # Statische BMC-Dokumentationen und Snippet-Strukturen ├── utils/ │ ├── DocStringExtractor.ts # Hilfsfunktionen zum Parsen von Multiline-Kommentaren │ └── RegexHelpers.ts # Zentrale Reguläre Ausdrücke für das Projekt └── extension.ts # Entry-Point der Extension (Registrierung der Module) ```
⚙️ Die Kernkomponenten
Wie arbeiten die Teile zusammen? Hier ist der Workflow der wichtigsten Module:
1. Entry Point (extension.ts)
Dies ist der Dreh- und Angelpunkt. Die activate-Funktion wird von VS Code aufgerufen, sobald eine .tpl Datei geöffnet wird. Sie erledigt zwei Dinge:
- Event-Listener binden: Lauscht auf das Öffnen von Dokumenten (
onDidOpenTextDocument), Änderungen am Code (onDidChangeTextDocument) und Anpassungen an den Einstellungen (onDidChangeConfiguration). - Provider registrieren: Meldet dem VS Code-Editor, welche Klassen für Hover, Autocomplete und Formatierung zuständig sind.
2. Der Linter / Scanner (core/TplLinter.ts)
Das Herzstück der Code-Analyse. Es handelt sich um einen zeilenbasierten, zustandsbehafteten (stateful) Scanner.
- State Tracking: Der Linter merkt sich Variablen über Zeilengrenzen hinweg (z.B.
inConditionBlock,parenStack), um zu wissen, ob ein=als Vergleich oder fehlerhafte Zuweisung gewertet werden muss. - Diagnostics: Findet der Scanner einen Fehler, erzeugt er eine
vscode.Diagnostic(die roten oder gelben Kringel im Editor) und übergibt sie an dieDiagnosticCollection.
3. Autovervollständigung (providers/TplCompletionProvider.ts)
Dieser Provider feuert bei jedem Tastendruck oder via Ctrl + Space.
- Regelwerk: Er analysiert den Text vor dem Cursor (
linePrefix). - Kontext: Endet die Zeile auf einen Punkt (z.B.
discovery.), wird das dynamischeTplBuiltInsObjekt durchsucht und die passenden Parameter-Überladungen als Snippets generiert. - Dynamik: Zieht sich für das
tpl_skeleton-Snippet live die VS Code Workspace-Konfigurationen (Author, Publisher etc.).
4. Tooltips (providers/TplHoverProvider.ts)
Reagiert, wenn die Maus über einem Wort stehen bleibt.
- Er greift das Wort (inkl. Namespace-Punkten) unter dem Cursor ab.
- Entweder schlägt er den Namen in den statischen BMC-Daten (
data/TplBuiltIns.ts) nach und rendert die Markdown-Beschreibung. - Oder er durchsucht das aktuelle/importierte Dokument nach der Definition und extrahiert den zugehörigen
"""-DocString aus dem Code.
🔄 Lifecycle-Management
Das Plugin ist ressourcenschonend konzipiert:
- Der Linter analysiert den Code on-the-fly im Arbeitsspeicher, ohne Dateien auf die Festplatte schreiben zu müssen.
- Einstellungen (Settings) werden beim Tippen live geladen. Ein Neustart des Editors ist bei Konfigurationsänderungen nicht notwendig.