Sexp Modülü

Sexp alt sistemi şunları sağlar:

• Zig'de hızlı bir S-expression tokenizer/parser/pretty-printer ve
• KiCad formatları (PCB, footprint, netlist, symbol, schematic, fp_lib_table) için yazılı Zig modelleri, pyzig_sexp extension modülü aracılığıyla Python'a açık hale getirilmiş.

Kaynak-of-truth dokümanları ve kod:

• src/faebryk/core/zig/README.md (üst düzey genel bakış)
• src/faebryk/core/zig/src/sexp/* (tokenizer/AST/yapı)
• src/faebryk/core/zig/src/python/sexp/sexp_py.zig (Python API + kritik bellek kuralları)

Hızlı Başlangıç

from pathlib import Path
from faebryk.libs.kicad.fileformats import kicad

pcb = kicad.loads(kicad.pcb.PcbFile, Path("board.kicad_pcb"))
_text = kicad.dumps(pcb)

İlgili Dosyalar

• Zig çekirdeği:
  • src/faebryk/core/zig/src/sexp/tokenizer.zig (tokenization + satır/sütun takibi)
  • src/faebryk/core/zig/src/sexp/ast.zig (SExp ağacı + KiCad pretty formatting)
  • src/faebryk/core/zig/src/sexp/structure.zig (decode/encode + hata bağlamı)
  • src/faebryk/core/zig/src/sexp/kicad/* (yazılı KiCad modelleri)
• Python extension giriş noktası:
  • src/faebryk/core/zig/src/python/sexp/init.zig (PyInit_pyzig_sexp dışa aktarır)
  • src/faebryk/core/zig/src/python/sexp/sexp_py.zig (modül + tür bağlama oluşturma)
• Oluşturulan Python stub'ları (kullanıcıların "gördüğü"):
  • src/faebryk/core/zig/gen/sexp/*.pyi
• Kod tabanı genelinde kullanılan kolaylık sarmalayıcısı:
  • src/faebryk/libs/kicad/fileformats.py (ad alanlarını modüller + önbelleğe alma + loads/dumps)

Bağımlılar (Çağrı Yerleri)

• src/faebryk/libs/kicad/fileformats.py (birincil entegrasyon katmanı)
• KiCad dışa aktarıcıları ve layout senkronizasyonu:
  • src/faebryk/exporters/pcb/kicad/*
  • src/faebryk/exporters/pcb/layout/layout_sync.py
• KiCad plugin iş akışı: src/atopile/kicad_plugin/*

Nasıl Çalışılır / Geliştirme / Test

Temel Kavramlar

• İki seviyeli model:
  • ham SExp parsing/formatting (tokenizer.zig, ast.zig)
  • yazılı KiCad decode/encoding (structure.zig + sexp/kicad/*.zig)
• Python API şekli: extension, format başına modülleri (örneğin pcb, netlist) şu şekilde açığa çıkarır:
  • modül düzeyinde loads(data: str) -> File
  • modül düzeyinde dumps(file: File) -> str
  • Zig'e ait ayırmaları serbest bırakmak için File.free(...)
• Kolaylık sarmalayıcısı: faebryk.libs.kicad.fileformats.kicad bu modülleri sarar ve kicad.loads(...)/kicad.dumps(...) sağlar.

Geliştirme İş Akışı

1. Zig'i değiştir:
   • parsing/formatting: src/faebryk/core/zig/src/sexp/*
   • Python açığa çıkarması: src/faebryk/core/zig/src/python/sexp/sexp_py.zig
2. Yeniden derle:
   • ato dev compile (faebryk.core.zig içe aktarır)
3. API'yi değiştirdiysen:
   • src/faebryk/core/zig/gen/sexp/*.pyi altındaki stub'ların buna göre güncellediğini doğrula
   • gerekirse src/faebryk/libs/kicad/fileformats.py ayarla

Test

• En iyi pratik test round-trip'tir:
  • bilinen bir .kicad_pcb / .kicad_sch yükle, dump et ve KiCad'in bunu kabul ettiğini doğrula (formatting duyarlı).
• Zig unit testleri (mevcut olduğunda):
  • zig test src/faebryk/core/zig/src/sexp/ast.zig
  • zig test src/faebryk/core/zig/src/sexp/structure.zig

En İyi Uygulamalar

• Ham modül API'sine açıkça ihtiyaç duymadığın sürece faebryk.libs.kicad.fileformats.kicad tercih et.
• kicad.loads(...) içindeki shared-object önbelleğe almaya dikkat et: yol tabanlı yüklemeler önbelleğe alınır ve referans olarak döndürülür (mutasyonlar paylaşılır).

Bellek & Yaşam Süresi Değişmezleri (kritik)

Python bağlamaları, ayrıştırılan structs giriş arabelleğine işaretçiler içerdiği için giriş S-expression dizesini kalıcı bir ayırıcıya çoğaltır.

Çıkarımlar:

• Büyük dosyaların tekrarlanan loads(...) işlemleri, döndürülen *File üzerinde hiçbir zaman free(...) çağırmazsanız belleği büyütebilir.
• Kolaylık sarmalayıcısı şu anda yüklenen nesneleri yola göre önbelleğe alır; cache'i de geçersiz kılmadığın sürece önbelleğe alınmış nesneler üzerinde free(...) çağırma.