TerminalBasic/docs/ide-bedienung.md

Terminal Basic IDE bedienen

cargo run -p tb-ide -- [Projekt.mak|Modul.bas|Formular.frm] startet die IDE. Ohne Datei erscheint ein neues Projekt mit [1] Untitled und dem Project Window rechts. Versions- und Copyright-Begrüßung blockieren keine Eingabe. Bei bereits vorhandener Untitled.bas bekommt das neue Dokument einen freien Namen. Es wird beim Start keine Datei angelegt.

Das Terminal muss mindestens 80×25 Zellen haben. Darunter erscheint nur der Größenhinweis; Dokumente, Fokus und Fensterzustand bleiben erhalten. Beim Vergrößern werden die Fenster wieder innerhalb der Terminalfläche dargestellt. Normales Beenden und Fehlerpfade stellen Raw Mode, Cursor, Mausmodus und Alternate Screen zurück.

Menüs, Fenster und Dialoge

• Alt plus Menübuchstabe oder F11 öffnet die Menüleiste. Pfeile wählen Menü/Eintrag, Enter führt aus; der unterstrichene Buchstabe wählt direkt. Esc bricht ab. F11 ist die Alternative, wenn das Terminal Alt allein nicht meldet. Menüs sind auch anklickbar, Help steht rechts.
• File enthält Projekt- und Dateiaktionen einschließlich New Form, New Module, Add/Remove File, Save File/As, Load/Save Text und Exit. Run → Set Start-up File speichert eine Auswahl oder den bisherigen Standard.
• Dialoge binden Tastatur und Maus an sich. Tab/Shift+Tab wechselt das Feld, Links/Rechts ändert Auswahlwerte, Leertaste schaltet Kästchen. Textfelder unterstützen Cursor, Pos1/Ende, Backspace/Entf und Ctrl+A zum Ersetzen. Enter/OK übernimmt, Esc/Abbrechen verwirft den Dialog.
• F2 in einem Dateipfad öffnet die Dateiauswahl. Links/Rechts wählt einen Eintrag, Enter öffnet ein Verzeichnis oder übernimmt eine Datei. Esc kehrt zum vorherigen Dialog mit dessen Angaben zurück. Neue Dateinamen lassen sich direkt ins Pfadfeld schreiben.
• F6/Ctrl+F6 bzw. Shift+F6 wechselt Fenster. Ctrl+F4 schließt eine Ansicht; Dokument und Änderungen bleiben im Projektmodell erhalten. Alt+Minus oder die Control-Menü-Box öffnet die Fensterbefehle.
• Ctrl+F7 verschiebt und Ctrl+F8 skaliert mit Pfeilen (Ctrl+Pfeile: fünf Zellen); Enter bestätigt, Esc stellt die vorige Geometrie wieder her. Ctrl+F9 minimiert, Ctrl+F10 maximiert, Ctrl+F5 stellt die Normalgeometrie wieder her. Window → Arrange All kachelt, New Window öffnet eine weitere Ansicht desselben Dokuments. Die Window-Liste markiert die aktive Ansicht.
• Im Project Window wählen Pfeile das Mitglied; Enter öffnet Code oder Formular entsprechend dem Dateityp. Form/Code-Buttons öffnen die gewählte Ansicht. View → Code/Form bietet zusätzlich einen Auswahldialog.
• Die Umgebung zeigt unten anklickbare Tastenkürzel und 00001:001 als Zeile/Spalte. Der Designer besitzt stattdessen die Properties Bar. F10 wechselt dort zwischen Menü- und Properties Bar, F2 fokussiert Value. Die fachliche Formularbearbeitung folgt in Change 05.

Speichern und Wechseln

Save File nutzt den bestehenden Pfad; neue Dateien, Importziele und Speicherkonflikte öffnen den Speicherdialog. Save Project zeigt Projektziel und Dokumentziele mit separaten Überschreibentscheidungen. Eine Änderung eines Pfades allein autorisiert kein Überschreiben einer vorhandenen Datei. Binäre FRM-Originale bleiben auch mit gesetzter Überschreibentscheidung geschützt; für bearbeitete Importe ist ein anderes Textziel erforderlich.

Beim Projektwechsel und Beenden stehen Abbrechen, Speichern und Verwerfen zur Auswahl. Abbrechen ist vorausgewählt. Bei einem Teilspeicherfehler bleibt der Dialog mit allen Angaben offen: erfolgreich gespeicherte Dateien sind gespeichert, übrige Änderungen bleiben erhalten; die IDE schließt nicht. Die MAK-Datei wird zuletzt geschrieben. Details stehen in Dateiformate.

Load Text fügt am Cursor als eine Undo-Aktion ein; Save Text exportiert im Rahmen den gesamten Code. Der Dokumentvertrag unterstützt bereits Auswahlexport des markierten Bereichs. Remove File löscht keine Datei; beim Entfernen der Startdatei ist die Wahl eines Ersatzes oder des bisherigen Standards ausdrücklich im Dialog enthalten.

Display und Benutzereinstellungen

Options → Display bietet Vorder- und Hintergrund (0–15) für Menü, Desktop, Code, aktiven Titel, Rahmen, Dialog/Projekt und Status. Default ist Schwarz auf Hellgrau für Menüs/Dialogs, Hellgrau auf Blau für Code, Weiß auf Magenta für aktive Titel und Schwarz auf Cyan für den Status. Desktop: ▒, Hellgrau auf Schwarz; Tabweite: 8. Ein Desktopzeichen muss genau eine Terminalzelle belegen, Tabweite liegt zwischen 1 und 32. Änderungen gelten sofort für die IDE; BASIC-Laufzeitfarben bleiben unabhängig.

Set Paths verwaltet Quellen-, Ausgabe- und Include-Verzeichnisse. Mehrere Includes werden mit | getrennt; relative Optionspfade werden beim Übernehmen relativ zum Projektverzeichnis absolut aufgelöst. Das Include neben der Quelldatei hat Vorrang vor Suchverzeichnissen. Right Mouse schaltet Kontext-Hilfe per Rechtsklick (Default an); die Hilfefunktion folgt in Change 07. Syntax Checking ist zunächst an; seine Wirkung ist unten beschrieben.

Erst Options → Save… / OK schreibt die versionierte Benutzerdatei:

System	Pfad
Unix mit absolutem XDG_CONFIG_HOME	$XDG_CONFIG_HOME/TerminalBasic/options.ini
macOS ohne XDG_CONFIG_HOME	$HOME/Library/Application Support/TerminalBasic/options.ini
anderes Unix ohne XDG_CONFIG_HOME	$HOME/.config/TerminalBasic/options.ini
Windows	%APPDATA%/TerminalBasic/options.ini

Die Datei ist unabhängig vom Arbeitsverzeichnis. Ungültige Werte erhalten eine Diagnose und behalten die Vorgabe; unbekannte Schlüssel werden mit Hinweis ignoriert. Unbekannte Versionen/ungültige Textkodierung verwenden Defaults. Schreibfehler erhalten die aktuellen, ungespeicherten Optionen. Externe Änderungen der Optionsdatei werden vor dem Ersetzen erkannt.

Native Exporte: UI in Phase 5, Erzeugung in Phase 6

Run → Make EXE File… (Alt+R, E) und Make Library… (Alt+R, L) öffnen vollständig bedienbare Dialoge. Artefaktart ist das native eigenständige Executable bzw. die native Systembibliothek. Zielsystem (Linux/macOS/Windows) und Architektur (x86_64/aarch64) sind auswählbar; Vorgabe ist das laufende Zielsystem. Ausgabepfad und Überschreibentscheidung werden je Auftrag erfasst. Die Auswahl ist noch keine Zusage einer vom Backend unterstützten Kombination; die Phase-6-Plattformmatrix bestätigt die tatsächlichen Ziele.

Prüfen/Enter validiert die Angaben und schützt Projektdatei, geöffnete Dokumente und binäre FRM-Originale. Leere/ungültige Pfade, fehlende Zielverzeichnisse, bestehende Ziele ohne Zustimmung und .tbc als natives Ziel ergeben eine Diagnose; die anderen Angaben bleiben erhalten.

Nur Erzeugen ist bis Phase 6 gesperrt, mit dem Hinweis „Native Erzeugung folgt in Phase 6“. Ein Produktionsaufruf schreibt keine Datei und meldet keinen erfundenen Erfolg. Der vorbereitete Auftrag trägt Projektidentität und Revisionsstand, Artefakt, Zielsystem, Architektur, Pfad und Überschreibentscheidung. Die UI kann zu diesem Auftrag Laufend, Erfolg, Fehler und Abbruch darstellen. Oberflächentests speisen diese Ergebnisse kontrolliert ein; sie belegen keine native Erzeugung.

Die tatsächliche Erzeugung und reale Backend-Anbindung, native Formate, Library-Symbole/Aufrufvertrag und der native Verbraucher-Nachweis stehen explizit in PLAN.md, Phase 6. Ein umbenanntes TBC erfüllt keines der beiden Exportziele.

Befehlsabdeckung nach Change 03

Alle Referenzbefehle sind in ihrer Menüfolge vorhanden. Fachbefehle der folgenden Changes sind sichtbar deaktiviert und zeigen einen Verfügbarkeitsgrund; ihre Kürzel gelangen nicht versehentlich an BASIC. Ctrl+C im Editor ist Kopieren, bei laufendem Programm mit Output-Fokus unterbricht Ctrl+C sofort die Sitzung, ohne eine BASIC-Taste einzureihen.

Bereich	Rahmenaktion jetzt	Fachaktion im Folgechange
File	New/Open/Save Project, New Form/Module, Add/Remove File, Save File/As, Load/Save Text, Print (UTF-8-Datei), Shell, Exit	—
Edit	Undo, Cut/Copy/Paste/Clear, New Sub/Function	Event Procedures: 05
View	Code/Form-Auswahl, Prozedurauswahl, Included File/Lines, Diagnostics, Designer Menu Bar/Value-Fokus, Output Screen	Grid Lines: 05; Next Statement: 06
Search	Find, Selected Text, Repeat Last Find, Change	—
Run	Start/Restart/Continue/Pause, COMMAND$, wirksame Startdatei und beide Make-Dialoge	Native Erzeugung: Phase 6
Debug	Vollständiges Menü und Kürzelzuordnung, einschließlich F7/F8/F9/F10 und History	Watches, Watchpoints, Trace, History, Breakpoints, Break on Errors, Set Next Statement: 06
Options	Display, Set Paths, Right Mouse, Save, Syntax Checking einschließlich Zeilenprüfung	Kontext-Hilfe: 07
Window	New Window, Arrange All, Calls/Debug/Help/Immediate/Output/Project, aktive Codeliste, alle Fensterkürzel	Debug/Calls/Immediate-Inhalte: 06; Hilfeinhalt: 07
Designer Tools/Window	Tools-Menü, Formliste und gemeinsamer Fenster-/Modusrahmen	Controls/Toolbox, Color Palette, Menu Design Window: 05
Help	Vollständiges Menü, About und Help-Fensterrahmen	Index, Contents, Keyboard, Topic, Using Help, Tutorial: 07

Editor, inkrementelle Übersetzung und Ausführung sind umgesetzt. Die gesamte Phase-5-Abnahme erfolgt in Change 08.

Programme ausführen

Shift+F5/Run → Start kompiliert den aktuellen Projektstand einschließlich ungespeicherter Dokumente und startet eine frische TBVM. F5/Continue startet im Bearbeitungsmodus oder setzt eine Pause fort. Run → Pause und Ctrl+Break unterbrechen auch bei Editorfokus; Ctrl+C unterbricht ausschließlich bei Programmfokus. Die Statusmeldung nennt Quelldatei und Unterbrechungszeile. STOP pausiert. END/SYSTEM beenden die Sitzung, erhalten die letzte Ausgabe und lassen die IDE offen. Natürliches Modulende hält sichtbare Formulare weiter bedienbar. Laufzeitfehler erscheinen als Diagnose mit Fehlernummer und Zeile; Kompilierfehler verhindern einen neuen Lauf.

Nach Quelländerungen während einer Pause verlangt Continue eine Entscheidung: aktuellen Stand neu starten oder das alte Kompilat ausdrücklich fortsetzen. Die zweite Wahl kennzeichnet das Output-Fenster mit ALTES KOMPILAT. Laufender Code wird nicht nachträglich ersetzt. Der Dialog Modify COMMAND$ setzt Argumente für den nächsten Start. Restart und BASIC RUN erzeugen eine neue VM samt Variablen, DATA-Zeiger, Fehlerzustand, Forms, Timern und Dateien. RUN mit Dateiname löst das Ziel relativ zum Ausführungsziel auf; fremde Ziele ersetzen das bearbeitete IDE-Projekt nicht. RUN auf dasselbe Ziel verwendet den aktuellen Editorstand. Fehlende Ziele erhalten die Dokumente.

Eine ausgewählte Startdatei läuft zuerst; die übrigen Modulrümpfe behalten ihre relative Reihenfolge. Ein ausgewähltes FRM wird Startformular, ein ausgewähltes BAS verhindert den automatischen Formularstart allein aufgrund der Projektmitgliedschaft. Ohne Auswahl bleiben Projektreihenfolge und erstes Startformular wie bisher. CLI und gespeichertes TBC verwenden denselben Vertrag.

Window → Output und F4 zeigen denselben TextScreen. Das kleine Fenster schneidet die Ansicht ab, verändert aber weder BASIC-Farben noch logische Bildschirmgröße. Nur ein echtes Terminal-Resize verändert den Laufzeitbildschirm. Auch während INPUT, LINE INPUT, INPUT$, RANDOMIZE ohne Argument, SLEEP und modaler Dialoge bleiben Umschalten und Pausieren möglich; Eingabeteile, Prompt, Fokus und Deadline bleiben erhalten. Eine Pause friert die Hostuhr nicht ein: Eine verstrichene SLEEP-Deadline wird nach Continue sofort erkannt.

File → Shell und BASIC SHELL geben Raw Mode, Maus-/Paste-Erfassung und Alternativschirm an ein Vordergrund-Kindprogramm mit geerbtem Standard-I/O ab. Nach Ende, Fehler oder Ctrl+C werden Terminal und bisheriger IDE-Fokus wiederhergestellt. SHELL als Funktion liefert den Exit-Code (bei unterbrochenem Kind ohne regulären Exit-Code wie bisher: 0); ein fehlgeschlagener Prozessstart wird BASIC-Fehler 53. Die IDE führt während der Übergabe keine VM-Schritte aus.

File → Print ist eine Plattformanpassung: Der Dialog schreibt Auswahl oder Gesamttext als UTF-8 in eine wählbare Druckdatei (Vorgabe LPT1.TXT). Er nutzt dieselben geschützten, atomaren Dateipfade wie Save Text. Überschreiben muss explizit gewählt werden; Projekt-/Quelldateien und originale Binärdateien sind weiter geschützt. Fehler halten den Dialog offen und verändern den Quelltext nicht. Ein Druckertreiber ist dafür nicht erforderlich.

Die VM gibt nach einem festen Instruktionsbudget oder bei ausstehender Eingabe die Kontrolle zurück. Synchrone Betriebssystemoperationen wie Öffnen, Lesen, Schreiben, Datenbank-I/O oder Dateiauswahl lassen sich innerhalb eines laufenden Systemaufrufs nicht unterbrechen. Sie sind keine Eingabewarte-Schleifen; nach Rückkehr gelten wieder die normalen Unterbrechungsgrenzen. Es gibt keinen VM-Hintergrundthread und keine zweite Kopie des Programmbildschirms.

Reproduzierbarer Testpfad

cargo test -p tb-ide prüft denselben App::handle(Event)-Dispatcher und dieselbe App::render-Funktion wie der Terminalprozess mit ratatui::TestBackend. Die Tests bedienen Menü, Tastatur, Dialog und Maus; sie prüfen Fokus, Dokumente, Fenster, sichtbare Texte und Farben. Dieser Pfad steht den Folgechanges zur Verfügung. TerminalGuard prüft zusätzlich Normalende, Fehlerende und teilweise fehlgeschlagene Initialisierung.

Editor, Suche und Quelltextpflege

Einfügen/Überschreiben wechselt mit Insert. Shift mit Pfeilen, Pos1/Ende und Bild auf/ab markiert Text; Ctrl+A markiert alles. Ctrl+Links/Rechts navigiert wortweise, Ctrl+Pos1/Ende zum Dateianfang/-ende. Ctrl+Y löscht die aktuelle Zeile. Unicode-Codepunkte und CRLF-Zeilenumbrüche bleiben unbeschädigt; Tabs und breite Zeichen verwenden Bildschirmspalten für die Vertikalbewegung. Markierungen werden invertiert dargestellt, der Cursor bleibt im sichtbaren Bereich.

Ctrl+C/X/V/Z sowie Ctrl+Insert, Shift+Delete/Insert und Alt+Backspace bedienen Kopieren, Ausschneiden, Einfügen und Undo. Die Zwischenablage ist IDE-intern und funktioniert zwischen Codefenstern. Terminal-Paste wird mit Bracketed Paste als eine Aktion verarbeitet. Paste, Ausschneiden, Ersetzen aller Treffer, Normalisierung und Prozedurerzeugung sind jeweils eine Undo-Einheit. Undo stellt auch Cursor, Markierungen und Lesezeichen der gemeinsamen Ansichten her.

WordStar: Ctrl+Q, dann S/D setzt den Zeilenanfang/-ende, R/C den Dateianfang/-ende. Ctrl+K, dann 0–3 setzt vier Lesezeichen je Ansicht; Ctrl+Q, dann 0–3 springt dorthin. Esc oder eine unbekannte Folgetaste bricht ab, ohne Quelltext einzufügen. Mausaktionen beenden einen begonnenen Chord.

Find und Change bieten Suchtext, Ersetzung, Richtung, Groß-/Kleinschreibung, ganze Wörter und den Bereich „Dokument“ oder „Nur Auswahl“. Das Aktionsfeld wählt Suchen, Einzeln ersetzen oder Alle ersetzen. Eine leere Ersetzung löscht Treffer. Ctrl+Backslash übernimmt die Auswahl als Suchtext, F3 sucht weiter. Am Bereichsende zeigt die Statusmeldung den angebotenen Rücksprung an; erneutes F3 bestätigt ihn. Alle Treffer einer Ersetzungsaktion werden gemeinsam rückgängig gemacht.

Shift+F2 beziehungsweise View → Procedures öffnet Modulrumpf und Prozeduren; Ctrl+F2 kehrt zur vorherigen Codeposition zurück. New Sub/Function prüft Namen auch gegen andere Projektmodule und übernimmt die am Erzeugungsort wirksamen DEFtype-Regeln, einschließlich Includes und des aktuellen Prozedurkontexts.

View → Included File öffnet das Original der Include-Anweisung auf der Cursorzeile. Included Lines zeigt die expandierte Übersetzungseinheit mit Dateinamen und physischen Zeilen als schreibgeschützte Ansicht. Pfeile und Bild auf/ab scrollen; erneuter Aufruf kehrt zum Quelltext zurück. Save File speichert immer das physische Dokument. Eine Expansion wird niemals zur BAS-Datei. View → Diagnostics ist eine ergänzende IDE-Funktion: Die Auswahl springt zur richtigen physischen Datei, Zeile und Spalte, auch bei Includes und FRM-Code.

Syntax Checking prüft beim Verlassen einer geänderten Zeile. Der reguläre Parser unterscheidet fehlende Blockabschlüsse am Dateiende von Syntaxfehlern. Unvollständige Blöcke bleiben ohne modalen Fehlerdialog bearbeitbar. Gültige Zeilen erhalten normalisierte Keywords und zulässige Abstände anhand der Lexerpositionen; Tokenvergleich schützt Strings, Kommentare, DATA und Bezeichner. Abschalten unterbindet automatische Prüfung, Formatierung und Fehlerdialoge. Die explizite Übersetzungs-API prüft unabhängig davon den vollständigen Stand.

Save File/As und Save Project pflegen DECLAREs im kommentierten Bereich ' $IDE DECLARE BEGIN bis ' $IDE DECLARE END unmittelbar vor den Prozeduren. Die Prüfung nutzt den regulären Projektcompiler mit Includes und Forms. Passende Handdeklarationen bleiben erhalten. Bei Konflikten oder unfertigem/fehlerhaftem Projektstand wird die gesamte Pflege übersprungen, der Entwurf unverändert gespeichert und der Grund mit Quellort ausgegeben. Auch FRM-Code benutzt diesen Speicherhook. Wiederholtes Speichern erzeugt keine neuen Deklarationen oder Revisionen.

Übersetzung und Revisionsbindung

App::compile_current lädt den aktuellen Projektstand und verwendet tb_vm::project::ProjectCompiler. CompileStats zählt geparste, übersetzte und wiederverwendete Module. Der Cache liegt nur im Speicher. Sein Verlust führt zur vollständigen Neuübersetzung, ohne das Dateiformat zu ändern.

Die Schlüssel vergleichen Include-Inhalte und Herkunft, Modulidentität, aufgelöste Importverträge und den Forms-Katalog. Private Rumpfänderungen lassen andere Modulprodukte bestehen. Konstante Importwerte werden transitiv neu aufgelöst; unbenutzte importierte Konstanten invalidieren keine unabhängigen Module. Importierte TYPEs und Prozeduren gehören zu den unverketteten Tabellen und damit zum Modulvertrag. Eigene Quellorte bleiben Bestandteil des Schlüssels; verschobene fremde Prozedurzeilen sind keine Signaturänderung. Änderungen an Quelltabellen oder Modulreihenfolge werden konservativ neu geparst. Der bestehende Linker baut sämtliche globalen Tabellen aus unverknüpften Produkten neu auf und prüft COMMON-Kompatibilität. Forms-Anfangswerte werden beim Link frisch eingesetzt.

Erfolge und Diagnosen gehören zu Projektrevision, expandierten Quellen und Forms. current_compilation und current_diagnostics geben nur einen dazu passenden Stand zurück; ein Fehler macht keinen früheren Erfolg aktuell. Geöffnete Include-Puffer bleiben maßgeblich gegenüber externen Dateiänderungen. Noch nicht geöffnete Includes werden erneut vom Loader gelesen und verglichen. Start und Fortsetzen der VM werden in Change 04 an diese Schnittstelle angebunden.

Release-Messungen und Aufruf stehen in tbvm-design.md.

Die Ausführungstests liegen in crates/tb-ide/tests/execution.rs und crates/tb-vm/tests/cooperative.rs. Zusätzlich prüft cargo build -p tb-ide && python3 tests/support/ide-execution-pty.py unter Unix in einem unsichtbaren PTY die echten Shell-/Terminalübergaben und das Fortsetzen nach STOP. Das Skript verwendet ausschließlich temporäre Projekte.