TerminalBasic/openspec/specs/konsolen-basisbibliothek/spec.md

# konsolen-basisbibliothek Specification

## Purpose
Die Konsolen-Basisbibliothek ist die in Phase 2 vorgezogene Scheibe der
Laufzeitbibliothek: die Builtin-Aufrufschnittstelle der VM, ein
`Host`-Abstraktion für Konsolen-E/A sowie PRINT-Formatierung und die vom
Testkorpus benötigten Stringfunktionen.

## Requirements

### Requirement: Builtin-Aufrufschnittstelle
Die VM SHALL Bibliotheksfunktionen und -anweisungen über eine indizierte
Dispatch-Tabelle aufrufen (Argumente auf dem Operandenstack, Index im
Opcode); die Tabelle lebt in der Laufzeitbibliothek und ist ohne
Änderung am Opcode-Satz erweiterbar (Phase 3 füllt sie auf).

#### Scenario: Builtin über Tabelle
- **WHEN** `PRINT LEN("abc")` ausgeführt wird
- **THEN** wird `LEN` über seinen Tabellenindex aufgerufen und liefert 3

### Requirement: Host-Abstraktion für Konsolen-E/A
Alle Konsolenwirkungen der Ausführungsschicht SHALL über eine
austauschbare Host-Schnittstelle laufen, die einen Bildschirmzustand
darstellt statt eines Zeichenstroms: Übergabe des Zellenpuffers zur
Anzeige, Abholen von Tastatur- und Größenänderungsereignissen sowie die
Abbruchprüfung (Strg+Untbr). Host-Aufrufe dürfen blockieren.
`tbc run` SHALL einen Konsolen-Host verwenden, der den Puffer im Terminal
darstellt und Tastendrücke liefert. Tests MUST einen Host verwenden
können, der ohne Terminal arbeitet, den Bildschirmzustand nach jedem
Schritt festhält und vorbereitete Tastendrücke einspeist. Eine
Bildschirmwirkung, die nur über einen Zeichenstrom ausdrückbar wäre, MUST
NOT vorkommen: `LOCATE`, `COLOR`, `CSRLIN`, `POS` und die Funktionsform
von `SCREEN` MUST über diese Schnittstelle vollständig abgebildet sein.

#### Scenario: Capture-Host im Test
- **WHEN** ein Korpusprogramm im Test-Harness läuft
- **THEN** entsteht der vollständige Bildschirmzustand im Capture-Host und ist vergleichbar, ohne dass ein Terminal vorhanden ist

#### Scenario: Cursorbewegung über die Schnittstelle
- **WHEN** ein Programm `LOCATE 5, 10 : PRINT "x"` ausführt
- **THEN** meldet der Host-Bildschirmzustand das Zeichen `x` an Position (5, 10)

#### Scenario: Tastendruck aus dem Host
- **WHEN** der Test-Host einen vorbereiteten Tastendruck liefert und das Programm `INKEY$` auswertet
- **THEN** erhält das Programm diese Taste

### Requirement: PRINT-Formatierung
`PRINT` SHALL Zahlen im Format des Vorbilds ausgeben: führendes
Leerzeichen für nicht-negative bzw. `-` für negative Werte,
nachgestelltes Leerzeichen (auch am Zeilenende); Zahlendarstellung je
Typ wie beim Vorbild (u. a. kein Dezimalpunkt bei ganzzahligen Werten,
signifikante Stellen je nach SINGLE/DOUBLE). `;` schließt direkt an,
`,` springt zur nächsten 14-Zeichen-Druckzone (belegt ein Element die
Zone ganz, zur übernächsten); ohne abschließendes `;`/`,` folgt ein
Zeilenumbruch.

#### Scenario: Zahlen mit Vorzeichenspalte
- **WHEN** `PRINT 1; -2; 3.5` ausgeführt wird
- **THEN** lautet die Ausgabe ` 1 -2  3.5 ` mit Zeilenumbruch

#### Scenario: Druckzonen
- **WHEN** `PRINT "12345678901234", "x"` ausgeführt wird
- **THEN** beginnt `x` in Spalte 29 (Zone nach der belegten übersprungen)

### Requirement: Vollständige Stringbibliothek
Die Bibliothek SHALL sämtliche in der Original-Hilfe dokumentierten
Stringfunktionen und -anweisungen mit der Semantik des Vorbilds
bereitstellen — darunter `LEN`, `LEFT$`, `RIGHT$`, `MID$` (Funktion und
Anweisung), `INSTR`, `UCASE$`, `LCASE$`, `LTRIM$`, `RTRIM$`, `STRING$`,
`SPACE$`, `CHR$`, `ASC`, `STR$`, `VAL`, `HEX$`, `OCT$` und `SWAP` für
Strings. Zeichen sind Unicode-Codepoints (dokumentierte Abweichung).
Randfälle folgen dem Vorbild: `VAL` liest das führende Zahlenpräfix und
überspringt Leerraum, `STR$` stellt nicht-negativen Zahlen ein Leerzeichen
voran, `ASC("")` löst Laufzeitfehler 5 aus, eine Startposition kleiner 1
bei `MID$`/`INSTR` ebenso, `LEFT$`/`RIGHT$` mit Länge über der Stringlänge
liefern den ganzen String. Welche Elemente die Liste umfasst, MUST das
Sprachinventar bestimmen; ein dort als `implementiert` geführtes Element
MUST verfügbar sein.

#### Scenario: VAL mit Restzeichen
- **WHEN** `VAL(" 12.5abc")` ausgewertet wird
- **THEN** ist das Ergebnis 12.5

#### Scenario: Länge über Stringende
- **WHEN** `LEFT$("ab", 10)` ausgewertet wird
- **THEN** ist das Ergebnis `ab`

#### Scenario: Ungültige Startposition
- **WHEN** `MID$("abc", 0)` ausgewertet wird
- **THEN** tritt Laufzeitfehler 5 auf

### Requirement: PRINT USING und FORMAT$
`PRINT USING`, `LPRINT USING` und `FORMAT$` SHALL die Formatzeichen des
Vorbilds unterstützen: numerische Platzhalter (`#`), Dezimalpunkt,
Tausendertrennung (`,`), Vorzeichenführung (`+`, `-`), Währungs- und
Füllzeichen (`$$`, `**`, `**$`), Exponentialform (`^^^^`) sowie die
String-Platzhalter `&`, `!` und `\ \`. Literale Zeichen SHALL unverändert
übernommen werden, `_` SHALL das Folgezeichen literal machen. Passt ein
Wert nicht in das Feld, SHALL die Ausgabe mit einem `%`-Präfix erfolgen
und der Wert vollständig dargestellt werden; dieses Überlaufverhalten MUST
in der Sprachreferenz festgehalten sein. Eine Formatzeichenkette ohne
Platzhalter bei vorhandenen Argumenten MUST Laufzeitfehler 5 auslösen.
`SetFormatCC` SHALL das für `$$` verwendete Währungszeichen und die
zugehörige Stellung setzen; ohne Aufruf gilt ein dokumentierter
Vorgabewert.

#### Scenario: Numerisches Feld mit Nachkommastellen
- **WHEN** `PRINT USING "###.##"; 3.14159` ausgeführt wird
- **THEN** lautet die Ausgabe `  3.14`

#### Scenario: Feldüberlauf
- **WHEN** `PRINT USING "##"; 12345` ausgeführt wird
- **THEN** beginnt die Ausgabe mit `%` und enthält den vollständigen Wert

#### Scenario: Formatzeichenkette wird wiederverwendet
- **WHEN** `PRINT USING "## "; 1; 2; 3` ausgeführt wird
- **THEN** wird die Formatzeichenkette für jeden Wert erneut angewandt

### Requirement: Datums- und Zeitbibliothek
Die Bibliothek SHALL die Datums- und Zeitfunktionen des Vorbilds
bereitstellen: `DATE$` und `TIME$` als Funktion und als Anweisung, `TIMER`,
`NOW`, `DATESERIAL`, `TIMESERIAL`, `DATEVALUE`, `TIMEVALUE`, `DAY`,
`MONTH`, `YEAR`, `WEEKDAY`, `HOUR`, `MINUTE`, `SECOND`. Serielle Datumswerte
SHALL der Zählweise des Vorbilds folgen (ganzzahliger Anteil = Tag,
Nachkommaanteil = Tageszeit). `WEEKDAY` SHALL 1 für Sonntag liefern.
Ungültige Datums- oder Zeitangaben MUST Laufzeitfehler 5 auslösen.

#### Scenario: Serienwert und Rückumwandlung
- **WHEN** `d = DATESERIAL(1992, 3, 15)` gebildet und `YEAR(d)`, `MONTH(d)`, `DAY(d)` ausgewertet werden
- **THEN** liefern sie 1992, 3 und 15

#### Scenario: Wochentagszählung
- **WHEN** `WEEKDAY` auf einen Sonntag angewandt wird
- **THEN** ist das Ergebnis 1

#### Scenario: Ungültiges Datum
- **WHEN** `DATESERIAL(1992, 13, 1)` ausgewertet wird
- **THEN** tritt Laufzeitfehler 5 auf

### Requirement: Kompatibler Zufallszahlengenerator
`RND` und `RANDOMIZE` SHALL die Zahlenfolge des Vorbilds reproduzieren:
gleicher Startwert MUST dieselbe Folge liefern. `RND` ohne Argument und
mit positivem Argument SHALL die nächste Zahl liefern, mit Argument 0 die
zuletzt gelieferte wiederholen, mit negativem Argument die Folge auf einen
aus dem Argument abgeleiteten Startwert setzen. `RANDOMIZE` ohne Argument
SHALL einen Startwert erfragen, `RANDOMIZE TIMER` einen zeitabhängigen
setzen. Der verwendete Algorithmus MUST in der Sprachreferenz dokumentiert
sein.

#### Scenario: Reproduzierbare Folge
- **WHEN** zweimal `RANDOMIZE 42` gefolgt von drei `RND`-Aufrufen ausgeführt wird
- **THEN** sind beide Dreierfolgen identisch

#### Scenario: RND(0) wiederholt
- **WHEN** nach einem `RND`-Aufruf `RND(0)` ausgewertet wird
- **THEN** liefert es denselben Wert wie der vorangegangene Aufruf

### Requirement: Mathematikbibliothek mit Überlaufverhalten
Die Bibliothek SHALL die numerischen Funktionen des Vorbilds
bereitstellen (`ABS`, `SGN`, `INT`, `FIX`, `SQR`, `EXP`, `LOG`, `SIN`,
`COS`, `TAN`, `ATN`, `CINT`, `CLNG`, `CSNG`, `CDBL`, `CCUR`). Rundung
SHALL kaufmännisch-symmetrisch zur geraden Zahl erfolgen (Banker's
Rounding). Überschreitet ein Ergebnis den Wertebereich des Zieltyps, MUST
Laufzeitfehler 6 „Overflow" auftreten; `SQR` und `LOG` mit unzulässigem
Argument MUST Laufzeitfehler 5 auslösen, Division durch null Fehler 11.

#### Scenario: Rundung zur geraden Zahl
- **WHEN** `CINT(0.5)` und `CINT(1.5)` ausgewertet werden
- **THEN** liefern sie 0 und 2

#### Scenario: Überlauf bei Konvertierung
- **WHEN** `CINT(40000)` ausgewertet wird
- **THEN** tritt Laufzeitfehler 6 auf

#### Scenario: Wurzel aus negativer Zahl
- **WHEN** `SQR(-1)` ausgewertet wird
- **THEN** tritt Laufzeitfehler 5 auf

### Requirement: Finanzmathematische Funktionen
Die Bibliothek SHALL die finanzmathematischen Funktionen des Vorbilds
bereitstellen: `FV#` (Endwert), `PV#` (Barwert), `Pmt#` (Zahlung),
`IPmt#` (Zinsanteil), `PPmt#` (Tilgungsanteil), `NPer#` (Anzahl
Zahlungsperioden), `Rate#` (Zinssatz), `NPV#` (Kapitalwert), `IRR#`
(interner Zinsfuß), `MIRR#` (modifizierter interner Zinsfuß), `SLN#`
(lineare Abschreibung), `SYD#` (arithmetisch-degressive Abschreibung) und
`DDB#` (geometrisch-degressive Abschreibung). Alle SHALL in DOUBLE
rechnen. Das Argument für die Fälligkeit SHALL zwischen nachschüssiger
und vorschüssiger Zahlung unterscheiden. Ungültige Argumente — etwa ein
Zinssatz von null bei `NPer#` oder eine Periode außerhalb der Laufzeit
bei `IPmt#`/`PPmt#` — MUST Laufzeitfehler 5 auslösen. `Rate#` und `IRR#`
nähern sich iterativ; findet die Näherung keine Lösung, MUST
Laufzeitfehler 5 auftreten statt eines stillen Ersatzwerts. Die
Abbruchbedingung der Näherung MUST in docs/bibliothek.md dokumentiert
sein.

#### Scenario: Endwert einer Rentenzahlung
- **WHEN** `FV#` für 10 Perioden, 5 % Zins und eine Zahlung von 100 nachschüssig ausgewertet wird
- **THEN** entspricht das Ergebnis dem dokumentierten Sollwert der Bibliotheksreferenz

#### Scenario: Zins- und Tilgungsanteil ergänzen sich
- **WHEN** `IPmt#` und `PPmt#` für dieselbe Periode desselben Darlehens ausgewertet werden
- **THEN** ist ihre Summe gleich `Pmt#` für dieses Darlehen

#### Scenario: Näherung ohne Lösung
- **WHEN** `IRR#` mit einer Zahlungsreihe ohne Vorzeichenwechsel ausgewertet wird
- **THEN** tritt Laufzeitfehler 5 auf

### Requirement: System- und Umgebungsanweisungen
`ENVIRON$` SHALL Umgebungsvariablen nach Namen oder Position liefern,
`ENVIRON` sie setzen. `COMMAND$` SHALL die Aufrufargumente ohne
Programmnamen liefern. `FRE` SHALL einen Speicherwert liefern, `CLEAR`
Variablen zurücksetzen, `TRON`/`TROFF` die Ablaufverfolgung schalten.
`STACK` SHALL als Anweisung die Stapelgröße setzen und als Funktion die
verfügbare Stapelgröße liefern. `SYSTEM` SHALL das Programm beenden und
die Kontrolle an das Betriebssystem zurückgeben. `ERDEV` und `ERDEV$`
SHALL den Fehlercode bzw. den Namen des zuletzt meldenden Geräts
liefern. Nicht abbildbare Größen (Speicher- und Stapelwerte, Gerätefehler)
MUST einen definierten, dokumentierten Ersatzwert liefern statt still zu
variieren; der Ersatzwert MUST in docs/sprachreferenz.md unter
„Abweichungen" stehen.

#### Scenario: Umgebungsvariable lesen
- **WHEN** eine Umgebungsvariable gesetzt ist und `ENVIRON$("NAME")` ausgewertet wird
- **THEN** liefert es deren Wert

#### Scenario: SYSTEM beendet das Programm
- **WHEN** ein Programm `SYSTEM` ausführt
- **THEN** endet es mit demselben Beendigungsstatus wie bei `END`

#### Scenario: Unbekannte Umgebungsvariable
- **WHEN** `ENVIRON$` für einen nicht gesetzten Namen ausgewertet wird
- **THEN** ist das Ergebnis der leere String

### Requirement: Zeitfunktionen liefern Ortszeit
`DATE$`, `TIME$`, `TIMER` und `NOW` SHALL den Zeitpunkt in der Zeitzone
des Rechners liefern, nicht in koordinierter Weltzeit. `TIMER` SHALL die
Sekunden seit der **lokalen** Mitternacht zählen. Der maßgebliche Versatz
SHALL für den jeweils abgefragten Zeitpunkt bestimmt werden, nicht einmal
beim Programmstart — ein Programm, das über eine Zeitumstellung hinweg
läuft, folgt ihr. Die Zerlegungsfunktionen (`DAY`, `MONTH`, `YEAR`,
`WEEKDAY`, `HOUR`, `MINUTE`, `SECOND`) arbeiten unverändert auf seriellen
Werten und rechnen selbst nicht um.

#### Scenario: Datum und Uhrzeit stimmen mit der Systemuhr überein
- **WHEN** ein Programm `DATE$` und `TIME$` abfragt
- **THEN** entsprechen sie der Ortszeit des Rechners zum Abfragezeitpunkt

#### Scenario: TIMER zählt ab lokaler Mitternacht
- **WHEN** `TIMER` abgefragt wird
- **THEN** entspricht der Wert den Sekunden seit der letzten lokalen Mitternacht, nicht seit der UTC-Mitternacht

#### Scenario: NOW und die Zerlegungsfunktionen passen zusammen
- **WHEN** `n# = NOW` gebildet und `HOUR(n#)` ausgewertet wird
- **THEN** liefert `HOUR(n#)` dieselbe Stunde, die auch `TIME$` nennt

#### Scenario: Sommerzeit wirkt zum jeweiligen Zeitpunkt
- **WHEN** in einer Zone mit Sommerzeit ein Zeitpunkt vor und einer nach der Umstellung abgefragt wird
- **THEN** unterscheiden sich die beiden Versätze um die Umstellungsspanne

### Requirement: Zonenermittlung mit Rückfallebene
Die Laufzeit SHALL die Zeitzone des Rechners über die
Betriebssystemeinstellung bestimmen. Lässt sie sich nicht ermitteln,
SHALL UTC gelten und das Programm ohne Fehler weiterlaufen. Ob die
Rückfallebene greift, MUST für ein Programm erkennbar sein und in
docs/sprachreferenz.md beschrieben stehen; ein stiller Wechsel auf UTC
MUST NOT vorkommen.

Die parameterlose INTEGER-Funktion TIMEZONEKNOWN SHALL -1 für eine ermittelte Systemzone und 0 für den UTC-Rückfall liefern. Auch eine nach Programmstart scheiternde Zonenermittlung SHALL diesen Zustand sichtbar ändern; die Abfrage SHALL keine Zeitzone oder Systemuhr verstellen.

#### Scenario: Zone nicht ermittelbar
- **WHEN** die Zeitzone des Rechners nicht bestimmt werden kann
- **THEN** rechnen die Zeitfunktionen in UTC und das Programm läuft ohne Fehler weiter

#### Scenario: Rückfallebene ist erkennbar
- **WHEN** ein Programm den Zonenzustand abfragt
- **THEN** unterscheidet die Antwort erkennbar zwischen ermittelter Zone und Rückfall auf UTC

#### Scenario: Rückfall nach Programmstart
- **WHEN** zunächst eine Zone ermittelt wurde, eine spätere Ermittlung aber scheitert
- **THEN** verwenden die Zeitfunktionen UTC und TIMEZONEKNOWN liefert 0

### Requirement: Programmversatz wirkt auf die Ortszeit
`DATE$ = text$` und `TIME$ = text$` SHALL weiterhin nicht die Systemuhr
stellen, sondern einen programmeigenen Versatz setzen. Dieser Versatz
SHALL auf die **Ortszeit** wirken: nach `TIME$ = "10:20:30"` nennt
`TIME$` diese Uhrzeit, und `NOW`, `HOUR` und `TIMER` stimmen damit
überein.

#### Scenario: Gesetzte Uhrzeit wird zurückgelesen
- **WHEN** `TIME$ = "10:20:30"` ausgeführt und danach `TIME$` abgefragt wird
- **THEN** nennt `TIME$` `10:20:30`

#### Scenario: Versatz wirkt auf alle Zeitfunktionen
- **WHEN** `DATE$ = "01-02-1993"` gesetzt und danach `YEAR(NOW)` ausgewertet wird
- **THEN** liefert `YEAR(NOW)` 1993