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