Skip to content

context.md

Latest commit

 

History

History
184 lines (140 loc) · 7.64 KB

context.md

File metadata and controls

184 lines (140 loc) · 7.64 KB
Raw

Japi Base BASIC (JBB) — context

Dit document is het gedeelde referentiekader voor Jan, Claude en aider+Qwen tijdens de bouw van JBB. Het beschrijft wat we maken, waarom, en welke keuzes al vastliggen.

Voor de publieke beschrijving komt later een README.md; voor gebruikers een MANUAL.md. Voor de Japi Base-platformconventies waarop JBB bouwt: zie /home/jan/Japi/context.md en MANUAL.md van Japi Base.

Wat JBB is

JBB is een BASIC-interpreter die als applicatie draait op het Japi Base- platform. De gebruiker tikt zijn BASIC-programma in de geïntegreerde editor en drukt RUN; JBB voert het uit en toont de output op het Japi Base-scherm.

Architecturaal is JBB een fork van JBE (Japi Base Editor): we erven het volledige editor-apparaat van JBE en bouwen daar de BASIC-interpreter bovenop. Net zoals JBE een fork is van Japi Base, is JBB een fork van JBE.

Relatie tot de Japi Base-familie

  • Japi Base — open platform, publieke repo, GPL-3, in /home/jan/Japi.
  • JBE (Japi Base Editor) — editor-applicatie, private repo, fork van Japi Base. Zie [[project-jbe-roadmap]].
  • JBB (Japi Base BASIC) — deze applicatie, fork van JBE, voor nu privaat (geen GitHub-push tot het op de Pico draait, zoals JBE).

Dialect-keuze

MMBasic-richting, geïnspireerd door Geoff Graham's MMBasic op de PicoMite-familie. Concreet:

  • Geen verplichte regelnummers; labels voor GOTO/GOSUB
  • Lange variabelnamen
  • Declare-first typemodel (besluit Jan 2026-06-16): elke variabele wordt expliciet getypeerd gedeclareerd vóór gebruik, met AS INTEGER/AS FLOAT/ AS STRING. Declareren kan met DIM (globaal/main), LOCAL/STATIC (in een SUB/FUNCTION), een getypeerde parameter, of inline in een FOR (FOR i AS INTEGER = 1 TO 10). Een ongedeclareerde variabele gebruiken is een fout. Het type komt enkel uit de declaratie.
  • De tekens $ en % zijn gewone naamtekens zonder typebetekenis (je mag naam$/count% schrijven, maar het hoeft niet, en een suffix mag het gedeclareerde type niet tegenspreken). Ingebouwde string-functies houden hun $ (LEFT$, STR$, …) als leesbaarheidsconventie. Zie design/type_model_spec.md. (Dit vervangt de oude suffix-als-type-conventie.)

Bewuste keuze: geen 1-op-1 MMBasic-compatibiliteit. We laten ons inspireren door zijn syntax en architectuur maar zijn niet gebonden om elk MMBasic-statement woord-voor-woord over te nemen. MMBasic-documentatie mag als referentie dienen, niet als specificatie.

Filosofie

  • Sim first, Pico last. Alles eerst in de Japi Base-sim ontwikkelen en testen op David. De Pico-port is het sluitstuk, niet het podium waar het werk gebeurt. (Geërfd van JBE.)
  • Consolideren boven splitsen. Liever één goed gestructureerd C-bestand dan tien losse files met elk een handvol regels. (Geërfd van [[project-repo-layout-conventions]].)
  • Geen overklok voor publicatie. Een productiemachine moet bij default-klok werken; alles daarboven is geen verkoopargument maar een loterij. Onze chip is 240 MHz. PicoMite kan tot 396 MHz overklokken, maar dat is geen eerlijke vergelijking voor wat een gebruiker uit de doos krijgt.

Benchmark-positie tegen MMBasic

JBB wordt publiek vergeleken met MMBasic op PicoMite. De afspraak:

  • Gelijke kloksnelheid: beide op 240 MHz, de aanbevolen instelling voor Japi Base én voor de PicoMite-vergelijking.
  • Codekwaliteit is dan de enige variabele. Tree-walking interpreter haalt MMBasic nooit. Tokenize + interpret (wat MMBasic zelf doet) is het minimum architectuur-niveau om eerlijk mee te kunnen.

Klokfrequentie-instelling (later)

Het Japi Base-platform krijgt later de mogelijkheid om de klok te kiezen. Toegelaten waarden, wegens pixelklok-compatibiliteit (65 MHz stappen boven 240):

  • 240 MHz — default, aanbevolen, basis voor MMBasic-vergelijking
  • 305 MHz — eerste optionele stap (240 + 65)
  • 370 MHz — tweede optionele stap (240 + 130)

Alles ≥ 240 MHz blijft beeld-stabiel op Japi Base; of de chip het haalt is silicon-loterij. Deze instelling hoort thuis in Japi Base zelf, niet in JBB.

Mijlpalen

M1 — Strikt minimum (speelbaar prototype)

Genoeg om retro-boekoefeningen 1–20 te kunnen tikken en draaien:

  • PRINT, INPUT, LET/=, REM
  • IF ... THEN ... ELSE ... (éénregelig)
  • FOR ... NEXT
  • GOTO label
  • 1D arrays met DIM
  • Numerieke + string-expressies: + - * /, haakjes, relationals (=, <, >, <=, >=, <>)

Geen GOSUB, geen WHILE, geen functies, geen multi-line IF.

M2 — Structuur

M1 + GOSUB/RETURN + WHILE/WEND + multi-line IF/THEN/ELSE/ENDIF + 2D arrays. Tijdens deze mijlpaal beginnen we de architectuur-migratie van tree-walking naar pure tokenize+ interpret (MMBasic-stijl), zodat we vroeg meten hoe ver we van MMBasic-performance zitten.

M3 — Publicatie-klaar

M2 + SUB + FUNCTION met parameters en lokale variabelen. MMBasic-stijl architectuur volledig op zijn plaats. Performance-pariteit met MMBasic op 240 MHz is het bewuste doel.

Voorbij M3 (niet in MVP-roadmap maar expliciet de richting)

  • Graphics via Japi Base API (pixels, lijnen, vormen)
  • Keyboard-lezen via Japi Base API
  • Audio via Japi Base API
  • Klokfrequentie-keuze in Japi Base zelf

Interpreter-architectuur

M1 — Tokenize + tree-walking executor

Parser leest de bron, tokeniseert per statement, bouwt een compacte AST. De executor wandelt de AST om het programma te draaien.

Voordelen voor M1:

  • Eenvoudig, goed begrepen door Qwen
  • AST is testbaar in chunks (tokenizer, parser, evaluator los)
  • Snel iets werkend om te valideren dat de pijplijn klopt

Beperking: gegarandeerd trager dan MMBasic. Voor M1-spelen geen probleem; voor de benchmark wel.

M2+ — Tokenize + lineaire interpret (MMBasic-stijl)

Bron wordt naar een interne token-stream gezet (geen AST per statement meer). Interpreter loopt die stream lineair door, executes direct. Dit is letterlijk wat MMBasic doet. Verwacht serieuze herwerk-fase in M2.

Werkomgeving

  • Code-locatie: /home/jan/Japi/JapiBaseBasic/ op David (zodra fork gemaakt).
  • Design-docs: tijdelijk /home/jan/Japi/JapiBaseBasic/design/, verhuist later naar de JBB-repo (vermoedelijk basic/design/ of basic/docs/).
  • AI-assist:
    • Claude Opus (deze sessies) — planning, design, specs, tests, review
    • aider + Qwen2.5-coder:14b op Eddy — implementatie per werkpakket
    • Code op David, Qwen op Eddy. Zie [[project-basic-interpreter-workflow]].
  • Talen: publieke teksten (README, MANUAL, code-commentaar) in Engels; conversatie + design-docs (zoals dit) in Nederlands/Vlaams. Zie [[feedback-language-dutch-internal]].
  • Repo-policy: privé op David tot JBB op de Pico draait; daarna publiek als japi-base-basic op GitHub.

Bewust nog open

  • Foutafhandeling-niveau in M1: vermoedelijk gewoon halt met duidelijke melding (regelnummer/positie + uitleg). ON ERROR voor later.
  • Geheugen-budget op Pico 2: 520 KB SRAM totaal. Nu nog niet vastpinnen; sim laat het oneindig lijken. Beslis bij M2.
  • Numerieke precisie: 32-bit vs 64-bit float/int. RP2350 heeft hardware-FPU (single precision). Vermoedelijk 32-bit, beslis bij M2.
  • Bestand-opslag voor .bas programma's: in RAM tijdens bewerken, op LittleFS voor permanente opslag op Pico (Japi Base gebruikt al LFS). Beslis tijdens editor-integratie.
  • Sneltoetsen in editor: F5 = RUN, F9 = STOP, etc. Beslis bij editor-integratie.

Bronnen geraadpleegd voor dit document

  • PicoMite RP2350 klokfrequenties en OPTION CPUSPEED: PicoMite User Manual (geoffg.net), Pimoroni overclocking guide, Raspberry Pi forums.
  • MMBasic referentie-implementatie: geoffg.net/picomitevga.html.