saQut

Programlanabilir, incelenebilir bir derleyici — bir "alet çantası" (toolbox).

saQut'un asıl varlık sebebi dilin kendisinden çok, derleme sürecinin her aşamasının dışarıdan görülebilir ve müdahale edilebilir olmasıdır. Token'lar, AST, sembol tablosu, optimizasyonun öncesi/sonrası ve IR — hepsi ayrı ayrı incelenebilir. Dil, bu aletin üzerinde çalıştığı küçük, prosedürel bir örnektir; vitrin değil, alet.

Uygulama dili C++'tır (header-only eğilimli, bkz. docs/fikirler.md ADR-003).

---

Şu an ne çalışıyor, ne çalışmıyor

Belgeler planlanan ile yapılanı net ayırır. Bugünkü gerçek durum:

✅ Çalışıyor (built)

• Lexer — karakter seviyesi tarama, konum takibi.
• Tokenizer — token üretimi (6 token tipi), yorum satırı desteği.
• Pratt parser — ifade (Pratt) + statement (recursive descent) ayrıştırma.
• AST — fonksiyon, blok, değişken tanımı, if/for/while/do-while/return, ifade node'ları.
• AST'nin JSON serileştirmesi — saqut ast ile incelenebilir.
• CLI komut yapısı — tokens, ast, symbols, run iskeletleri.
• Kaynak konum takibi (SourceLocation) — offset → (satır, sütun).
• Minimal IR deneyi — basit aritmetiği düşürür (örn. 1 + (7/3) → kısa doğrusal komut dizisi). Henüz tam bir backend değil, bir deneydir.

🚧 Henüz yok (planned)

• Sembol tablosu
• Semantik analiz
• Tip sistemi
• Diagnostic (hata raporlama) motoru
• Optimizasyon
• IR + bytecode VM ile çalıştırma

feature/frontend-analysis dalı şu an yalnızca bu yapılmamış işin tasarım belgelerini içerir, kodunu değil.

Birinci kilometre taşı ("bitti" tanımı): derleyici fibonacci'yi (recursive + iterative) ve basit matematik/döngü programlarını derleyip çalıştırabilmeli. Referans program: examples/fibonacci.sqt.

---

Dil kimliği (kilitli)

Prosedürel, C ailesi sözdizimi, value semantics. İlk ifade doğrudan bir işlem/tanım olabilir; zorunlu class/main boilerplate'i yoktur (Java'nın aksine).

Özellik	Karar
Class / OOP / kalıtım	Yok
Closure	Yok
Generic	Yok
Kullanıcıya açık pointer (* / &)	Yok — derleyici/runtime içeride pointer'ı serbestçe kullanır
struct	Var
Tipli fonksiyonlar (dönüş + parametre)	Var
Array (int[])	Var
interface	Ertelendi (v0 değil — gerekçe ADR-018)
auto / tip çıkarımı	Yok
Gizli int↔float dönüşümü	Yok (tek istisna: sabit folding)

Gerekçe: prosedürel tasarım semantik karmaşıklığı en aza indirir ve hedeflerle (fibonacci, matematik, sıralama, ayrıştırma) örtüşür. Standart C'de class yoktur (o C++'tır); C, struct + fonksiyonun yettiğini kanıtlar.

---

Çalıştırma modeli (kilitli): IR + bytecode VM

saQut, kendi IR'sine derler ve bu IR'yi bir yorumlayıcı döngü (bytecode VM) ile çalıştırır.

• Tree-walker DEĞİL (çok yavaş).
• Gerçek makine-kodu JIT DEĞİL. Makine kodu üretimi (register allocation, ABI/çağırma sözleşmeleri, çalıştırılabilir mmap bellek) kapsam dışıdır — tek faydası ham hızdır ve hız burada öncelik değildir. Öncelikler determinizm ve incelenebilirliktir; bytecode VM ikisini de doğrudan sağlar.
• Bellek bu modelde kolaydır: host (C++) heap'i kullanılır; v0 için özel runtime allocator gerekmez.
• C'ye transpile, geçerli bir İKİNCİ backend olarak ileride kalır (frontend backend-bağımsızdır — middle-end ayrımının amacı budur, ADR-006). İleride makine kodu istenirse elle code generator yazmak yerine libgccjit / LLVM'e bağlanılır — ama bu çok uzak gelecektir.

Eski belge/konuşmalarda geçen "JIT" terimi yanlış yönlendiricidir; doğru çerçeve IR + VM'dir.

---

Mimari hatlar

KAYNAK KOD
   │  lexer
   ▼
TOKEN'LAR ──────────────  saqut tokens
   │  parser (Pratt + recursive descent)
   ▼
AST ────────────────────  saqut ast
   │  sembol toplama (iki geçişli)        ┐
   ▼                                       │
SEMBOL TABLOSU ─────────  saqut symbols    │  FRONTEND
   │  semantik analiz (annotation)         │  (yapı + anlam)
   ▼                                       │
ANNOTATE EDİLMİŞ AST ───  saqut ast        ┘
   │  optimizasyon (opsiyonel, klon üstünde)   ── MIDDLE-END
   ▼
IR ─────────────────────  (planlanan)      ┐
   │  bytecode VM / yorumlayıcı döngü       │  BACKEND
   ▼                                        │  (çalıştırma + FFI seam)
ÇALIŞTIRMA / ÇIKTI ─────  saqut run        ┘

• Frontend yapıyı ve anlamı modeller (tip, scope, dataflow).
• "Hangi çekirdek, hangi cihaz, ne zaman, hangi çıktı formatı" runtime/backend meselesidir — frontend'e yüklenmez.

---

CLI (mevcut + planlanan)

# --- çalışıyor ---
saqut tokens   file:kaynak.sqt      # token listesi
saqut ast      file:kaynak.sqt      # AST (JSON)
saqut symbols  file:kaynak.sqt      # sembol tablosu (iskelet)

# --- planlanan ---
saqut run      file:kaynak.sqt      # IR üret + bytecode VM ile çalıştır
saqut ast      file:kaynak.sqt --optimized   # klon, optimize edilmiş AST (öncesi/sonrası)
saqut transpile file:kaynak.sqt -o prog.c    # ikinci backend (ileride)

Tasarım gereği her aşamanın çıktısı erken bir noktada dosyalanabilir/loglanabilir (programlanabilir derleyici). Token, ham AST, optimize AST ve IR ayrı ayrı kaydedilebilir.

---

Batteries / stdlib — kuzey yıldızı, ertelendi

Gerçek bir genel sürüm pil ile gelmeli (sıralama, sıkıştırma, kripto, JSON/XML/HTML ayrıştırma). Ama bu bugünün işi ve v0.1 değildir.

Mimari çerçeve (monolit korkusunu önler): derleyici pilleri çekirdeğine gömmez. Bunun yerine küçük bir gerçek builtin kümesi (print, temel zorunlular) + gerisi kütüphane/FFI ile gelir. "Batteries" sorunu aslında bir sınır (FFI/link seam) sorunudur, "zlib'i yeniden yaz" sorunu değil. Sınır bir kez çizilir, piller üstünde sonsuza dek birikir.

• JSON/XML/HTML ayrıştırıcıları saQut'un kendisinde yazılabilir (string + struct + fonksiyon + kontrol akışı yeter). İlk gerçek demo programları.
• Sıkıştırma/kripto: denenmiş C kütüphanelerine FFI ile bağlan. Kripto asla elle yazılmaz.
• Bugüne tek yansıması: IR/runtime tasarlanırken bilinçli bir FFI seam ("host fonksiyonu çağır" deliği) bırakılır. print bunu zaten zorlar — bunu kaza değil, kasıtlı bir mekanizma yapıyoruz (ADR-016).

---

Belge haritası

Belge	İçerik
docs/fikirler.md	ADR-001…005: backend stratejisi, parser, header-only, token, IR
docs/adr-frontend-analiz.md	ADR-006…019: frontend, analiz/optimizasyon, çalıştırma modeli, FFI, interface, bellek
docs/roadmap-frontend.md	Faz-faz uygulama planı (sembol tablosu → fibonacci)
docs/transkript-frontend-tasarim.md	Tasarım oturumunun transkripti
examples/fibonacci.sqt	Geçerli referans program (semantik + kod üretimi fixture'ı)
examples/parser-stress/	Yalnızca parser'ı zorlayan, geçerli olmayan fixture'lar

---

İlke

Bir şey çalışmadan önce çerçeve inşa etmekten kaçın. Önce uçtan uca tek bir dikey dilim çalıştır (kaynak → IR → çalıştır; tamsayı aritmetiği + değişken + kontrol akışı + tek bir print). Modülerlik bir kuzey yıldızıdır, v0.1 gereksinimi değil; ihtiyaç doğmadan eklenen her soyutlama daha az değil, daha çok karmaşıklıktır.