توليد الكود (codegen)
ماذا ستتعلّم: كيف تتحوّل ملفّات YAML إلى كود C++ وتوثيق، وأين المولّدات.
الخطّ
flowchart LR
Y["language-truth/*.yaml"] --> P["scripts/codegen/gen_*.py"]
P --> H["shared/*/generated/*.{h,cpp}"]
P --> D["docs/ (توثيق مُولَّد)"]
H --> B["بناء C++ (CMake)"]
المولّدات (scripts/codegen/)
📏 المقيس على
dev: 79 ملفَّ بايثون فيscripts/codegen/، منها 31 بالبادئةgen_(مولِّد فعليّ) و22 بالبادئةcheck_(حرّاسٌ وفاحصون)، و5 في_lib/(مكتباتٌ مساعدة)، والباقي (21) اختباراتُtest_*وسكربتاتُ ترحيلٍ لمرّةٍ واحدة. الجدولُ أدناه عيّنةٌ تشرح النمط، لا جردًا كاملًا — الجردُ في المجلّد نفسِه.
| المولّد | المصدر → الناتج |
|---|---|
gen_keywords.py | keywords.yaml → keywords_generated.{h,cpp} |
gen_types.py | types.yaml → كود الأنواع المُولَّد |
gen_builtins_registry.py / gen_all_builtins_yaml.py | builtins/ → builtin_registry_generated.h |
gen_error_messages.py | errors/ → رسائل/تشخيص مُولَّد (أداةُ sadinfo ومولِّدُها gen_sadinfo_errors.py تقاعدا في تمّوز ٢٠٢٦ — #144) |
gen_parser_grammar_docs.py | grammar/*.yaml → docs/parser_rule/_generated/ |
check_grammar_conformance.py | يفحص تغطية القواعد وتماسك وسوم الاختبارات |
اكتشف الواجهة بـ
python scripts/codegen/<gen>.py --help. بعضها يعمل عبر CMake عند البناء.
قواعد ذهبيّة
- لا تحرّر
generated/يدويًّا — عدّل YAML ثم أعد التوليد. - ضمّن المُولَّد في الـcommit مع YAML (متطابقين) — هو جزء من «قائمة الملفّات».
- فحص CI: مولّدات
--check(مثلgen_parser_grammar_docs.py --check) تفشل إن تباعد المُولَّد عن المصدر.
نمط مولّد التوثيق (مثال متقدّم)
gen_parser_grammar_docs.py يقرأ قواعد الإنتاج (grammar/*.yaml) ويُنتج لكل قاعدة:
BNF + المسار إلى دالة المحلل (maps_to) ⇒ عقدة AST + مخطّط Mermaid آليّ + روابط
«يستدعي/مُستدعى». ثم --check يضمن بقاء التوثيق محدَّثًا في CI. → قواعد المحلل SoT.
اقرأ بعده: قواعد المحلل كمصدر موحّد.