diff --git "a/text/0000-\330\247\331\204\331\204\331\207\330\254\330\247\330\252-\330\247\331\204\330\243\330\265\331\212\331\204\330\251-\330\247\331\204\331\202\330\247\330\250\331\204\330\251-\331\204\331\204\330\252\331\210\330\263\330\271.md" "b/text/0000-\330\247\331\204\331\204\331\207\330\254\330\247\330\252-\330\247\331\204\330\243\330\265\331\212\331\204\330\251-\330\247\331\204\331\202\330\247\330\250\331\204\330\251-\331\204\331\204\330\252\331\210\330\263\330\271.md" new file mode 100644 index 0000000..af0d7ea --- /dev/null +++ "b/text/0000-\330\247\331\204\331\204\331\207\330\254\330\247\330\252-\330\247\331\204\330\243\330\265\331\212\331\204\330\251-\330\247\331\204\331\202\330\247\330\250\331\204\330\251-\331\204\331\204\330\252\331\210\330\263\330\271.md" @@ -0,0 +1,211 @@ +- **عنوان المقترح:** اللهجات الأصيلة القابلة للتوسّع — المستند والتجميع كبُنى من الدرجة الأولى في لغة ص +- **النطاق:** لغة `text/` +- **تاريخ البدء:** 2026-07-22 +- **رقم الـ RFC:** (يُترك فارغاً حتى الدمج) +- **الحالة:** مقترَح +- **Issue التتبُّع:** (يُترك فارغاً حتى القبول) + +# ملخّص + +نقترح جعل لغة ص **لغةً شاملةً** لا عبر احتضان نصوص أجنبيّة خام، بل عبر **لهجات أصيلة**: لكلّ صنف محتوًى (مستند، تجميع، …) بُنًى عربيّة من الدرجة الأولى في لغة ص نفسها — بعقد AST حقيقيّة وفحوص دلاليّة — بينما تصبح الصيغ الخارجيّة (ماركداون، HTML، ولاحقًا PDF وغيرها) مجرّد **أهداف تصديرٍ** قابلة للإضافة. المبدأ الحاكم: + +> **النموذج الدلاليّ ملك ص، والصيغة الأجنبيّة مجرّد مخرَج.** + +فلهجة «مستند» ليست ماركداون داخل ص، بل نموذج وثائقيّ عربيّ دلالاته **أوسع** من ماركداون (معادلات، مخطّطات، عناصر SadUI تفاعليّة، قيم محسوبة من كود ص حيّ) ويُصدَّر *من بينها* إلى ماركداون لمن يحتاجه. ولهجة «تجميع» ليست سلسلة أسمبلي معتمة، بل تعليمات منظَّمة مفحوصة مربوطة بمتغيّرات ص. وإضافة لهجة أو مُصدِّر جديد لا تتطلّب إلّا تعريفًا في مصدر الحقيقة ومعالجًا واحدًا. + +ويمتدّ المبدأ إلى **صنف ملفّ سياديّ**: امتداد `.مستند` خاصّ بنا يحلّ محلّ `.md` في منظومتنا، يصيّره **عارض مستندات مدمج في محراب** (نظير عارض معاينة ماركداون في VS Code — لكن بقدراتنا الأوسع: تفاعل، قيم حيّة، معادلات، اتّجاه عربيّ أصيل)، ومن أراد `.md` للتوافق الخارجيّ أعطته **الأدوات** (المنسّق/خادم اللغة/`صدّر`) إيّاه كمخرَج تنازليّ — فنتفوّق على ماركداون بدل التقيّد به. + +# الدافع (Motivation) + +- **الأصالة لا التبعيّة:** أيّ تصميم «كتلة ماركداون خام» يسقّف قدرات ص عند قدرات ماركداون، ويجعل التوسّع لميزات متقدّمة (جدول محسوب، مخطّط حيّ، معادلة، عنصر تفاعليّ) مستحيلًا بنيويًّا لأنّ ماركداون نفسه لا يعرفها. المِلكيّة الدلاليّة يجب أن تكون عند ص. +- **نواة النحلة:** `@تجميع("نصّ")` الحاليّ سلسلة معتمة بلا مُعاملات ولا فحص؛ آخر بقايا C (sgdt/sidt، مسبار xmm7) عالقة لهذا السبب تحديدًا. تجميع منظَّم مربوط بمتغيّرات ص يُغلق الباب. +- **التوثيق اليوم مساران متباعدان بفجوات سلوكيّة:** توثيق `##` قائم فعلًا (رمز `DOC_COMMENT` في المعجميّ، بنية `DocComment` بوسوم عربيّة، مستخرج docs في `sad-run`، وتحويم LSP يعرضه ماركداون)، **لكنّ** LSP يستخرجه بمسح نصّيّ مستقلّ متجاهلًا `docComment` المثبَت على AST، والالتصاق فيه عيوب قائمة (تعليق ذيل سطرٍ يلتصق بالتصريح التالي، وينجو عبر الأسطر الفارغة بلا تحذير)، ولا لُحمة بين JSON المستخرج وsadlang-docs، ولا دروس قابلة للتشغيل. اللهجة توحّد هذا كلّه تحت نموذج «مستند» الواحد. +- **كلفة كلّ صنف جديد اليوم تفصيل يدويّ كامل** (lexer+parser+AST+مستهلكين). نموذج اللهجات يجعلها: تعريف SoT + عقد مولَّدة + معالج. +- **السيادة:** مكدّس عربيّ واحد من التعليمة الآليّة حتّى الوثيقة المنشورة، والصيغ الأجنبيّة على الحافّة فقط. + +# الشرح التوجيهي (Guide-level explanation) + +## 1. لهجة «مستند» — نموذج وثائقيّ أصيل يتجاوز ماركداون + +كتلة `مستند … نهاية` محتواها **بُنى ص وثائقيّة حقيقيّة**، لا نصّ خام: + +```sad +مستند دليل_البدء + عنوان(١) «البدء مع لغة ص» + فقرة «أوّل برنامج لك في ثلاث دقائق.» + + قائمة مرقّمة + بند «ثبّت المترجم» + بند «اكتب الملفّ الأوّل» + نهاية + + # ما يعجز عنه ماركداون — قيمة محسوبة من كود ص حيّ: + فقرة «عدد المدمجات الحاليّ: {طول(قائمة_المدمجات())}» + + معادلة «جا²(س) + جتا²(س) = ١» + + مخطّط أعمدة(بيانات_الإصدارات) + + # عنصر تفاعليّ من SadUI داخل الوثيقة نفسها: + عرض_حيّ + زر(«جرّبني»).عند_النقر(شغّل_المثال) + نهاية +نهاية +``` + +لأنّها بُنى حقيقيّة: المحلّل يفحصها، والأخطاء تُشخَّص بكتالوج الأخطاء (`بند` خارج `قائمة` ⇒ خطأ واضح)، والقيم المضمَّنة `{…}` تعابير ص تُقيَّم فعلًا، ومحراب يكمل ويلوّن كأيّ كود ص. + +**التصدير** طبقة منفصلة قابلة للتوسّع: + +```sad +صدّر(دليل_البدء، «ماركداون») # يُسقط ما لا يعرفه ماركداون بتنازل موثَّق +صدّر(دليل_البدء، «HTML») # يحمل المعادلات والمخطّطات والتفاعل كاملة +``` + +فماركداون **أرضيّة تصدير** لا سقف تصميم: الميزات المتقدّمة تعيش كاملةً في نموذج ص، وكلّ مُصدِّر يأخذ منها ما تحمله صيغته. + +**التوثيق الملتصق بالكود** قائم اليوم (`##` + وسوم `@معطى/@أرجع/@مثال…` في بنية `DocComment`، يعرضه تحويم LSP ماركداون) — واللهجة ترقّيه لا تعيد بناءه: محتوى `##` يُعاد تفسيره **بُنى مستند** فوق نظام الوسوم القائم دون تغيير صيغة المصدر، فيكسب الاستيفاء والبُنى الغنيّة، ويتوحّد مساراه المتباعدان (AST مقابل المسح النصّيّ في LSP) على النموذج الواحد. + +## 2. لهجة «تجميع» — أسمبلي عربيّ كامل، لا سلسلة معتمة ولا منمنمات أعجميّة + +**كلّ أوامر الأسمبلي عربيّة**: المنمنمات (mnemonics) نفسها كلمات عربيّة فعل-أوّلًا وفق قواعد العربيّة (امتدادًا لقاعدة مدمجات العتاد القائمة `اقرأ_منفذ/اكتب_ذاكرة`)، والسجلّات لها أسماء عربيّة معتمدة. لا يظهر في المصدر حرف لاتينيّ واحد: + +```sad +دالة اقرأ_جدول_الواصفات(رقم عنوان_المخزن) + تجميع + خزّن_جدول_الواصفات [{عنوان_المخزن}] + يلوّث(الذاكرة) + نهاية +نهاية + +دالة أوقف_المعالج() لا_ترجع + تجميع + عطّل_المقاطعات + حلقة: أوقف # لصيقة قفز عربيّة + اقفز حلقة + نهاية +نهاية +``` + +كلّ تعليمة **بنية مفحوصة**: منمنمة غير معجميّة ⇒ خطأ كتالوج بقائمة الأقرب؛ عدد معاملات خاطئ أو سجلّ لا يقبل هذا العرض ⇒ خطأ دلاليّ قبل llvm أصلًا — تشخيص يستحيل مع السلاسل المعتمة. المُعاملات متغيّرات ص حقيقيّة تُربَط تلقائيًّا (لا حاجة لبنود `مدخلات/مخرجات` اليدويّة إلّا للتخصيص)، والقيود والتلويث يُخفَضان إلى `llvm::InlineAsm` صحيحَين. معجم المنمنمات العربيّة ⇒ تعليمات العتاد يعيش في مصدر الحقيقة **وحده** — وهو الموضع الوحيد في المنظومة الذي تُذكَر فيه الصيغة الأعجميّة، توثيقًا للتقابل. + +`@تجميع("…")` القديم يبقى منفذ هروب متوافقًا خلفيًّا (سلسلة خام لمن يلصق أسمبلي أعجميًّا موروثًا)، ويوثَّق أنّ اللهجة العربيّة هي الصيغة القياسيّة. + +## 3. صنف الملفّ السياديّ `.مستند` — بديلنا عن `.md` + +اللهجة تملك ملفًّا كاملًا بامتداد خاصّ بنا: ملفّ `دليل_البدء.مستند` جذرُه وثيقة خالصة (بُنى لهجة «مستند» مباشرةً، بلا ترويسة كتلة) وله قدرات ص كاملة — استيفاء، عرض_حيّ، معادلات. وهو **بديل `.md` داخل منظومتنا**: + +- **العرض:** محراب يفتح `.مستند` بعارضٍ مدمج يصيّره تصييرًا تفاعليًّا (نظير عارض معاينة ماركداون في VS Code)، بوضعَين: تحرير مصدر بإكمال وتلوين من LSP، ومعاينة حيّة مصيَّرة جنبًا إلى جنب. العارض يبني على بنية webview العربيّة القائمة (AR-01: bidi plaintext + خطّ كوكب مضمَّن). +- **التفوّق على ماركداون:** الوثيقة تعرض قيمًا محسوبةً من كود ص حيّ، وأزرارًا وعناصر SadUI تعمل داخل المعاينة، ومعادلات ومخطّطات — أشياء لا يملك `.md` تمثيلها أصلًا. +- **التوافق اتّجاهُ خروجٍ عبر الأدوات:** من أراد نشر `.md` (README لمستودع GitHub مثلًا) يطلبه من المنسّق/خادم اللغة (أمر «صدّر إلى ماركداون» في محراب أو `sad-fmt --صدّر ماركداون ملف.مستند`) فيولَّد `.md` كمخرَج تنازليّ موثَّق — الملفّ المصدر يبقى دائمًا `.مستند`. + +ويفتح النموذجُ البابَ مستقبلًا لأصناف ملفّات أخرى (`.واجهة` لSadUI تصريحيّ…). الأدوات تعرف الصنف من الامتداد، والقلب يرى لهجةً مسجَّلةً في مصدر الحقيقة. + +# الشرح المرجعي (Reference-level explanation) + +## البنية المعماريّة: ثلاث طبقات متعامدة + +``` +تحليل (لهجات) ⇒ نموذج دلاليّ موحَّد (AST ص) ⇒ تصدير (مُصدِّرات) +``` + +- **اللهجة**: مجموعة بُنى نحويّة تُفتَح بكلمة الكتلة (مستند/تجميع) وتُحلَّل إلى عقد AST حقيقيّة. +- **النموذج**: عقد AST مولَّدة من SoT، تمرّ بالفحص الدلاليّ ككلّ شيء آخر. +- **المُصدِّر**: محوِّل من النموذج إلى صيغة خارجيّة، مسجَّل في SoT، **الإضافة عليه أرخص شيء في النظام** (لا يمسّ اللغة). + +## مصدر الحقيقة (`language-truth/`) + +- `dialects/` جديد + `_schemas/dialect.schema.json`: + - `dialects/document.yaml`: بُنى المستند (عنوان، فقرة، قائمة/بند، جدول، معادلة، مخطّط، عرض_حيّ، رابط، كود) بحقول كلٍّ (الوسائط، التداخل المسموح، إلزاميّة الإغلاق). + - `dialects/assembly.yaml`: بُنى الكتلة (يلوّث، اللصائق، بنود التخصيص مدخلات/مخرجات، +لاحقًا في_سجل). + - `dialects/assembly_mnemonics/<معماريّة>.yaml` (البذرة: `i686.yaml` — **مسودّته المرفقة:** `0000-اللهجات-الأصيلة-معجم-تجميع-i686.yaml`): **معجم المنمنمات العربيّة** — لكلّ تعليمة: الاسم العربيّ فعل-أوّلًا (`انقل`⇒mov، `اجمع`⇒add، `قارن`⇒cmp، `اقفز_إذا_ساوى`⇒je، `عطّل_المقاطعات`⇒cli، `أوقف`⇒hlt، `خزّن_جدول_الواصفات`⇒sgdt…)، عدد المعاملات وأصنافها المسموحة، والمقابل الأعجميّ (توثيقًا وخفضًا). وأسماء السجلّات العربيّة (`المركم`⇒eax…). هذا الملفّ هو **الموضع الوحيد** الذي تظهر فيه المنمنمات اللاتينيّة في المنظومة كلّها. التغطية تدريجيّة بحاجة النحلة الفعليّة (عشرات التعليمات لا الآلاف)، ومنمنمة غير معجميّة خطأٌ لا تمريرٌ صامت. + - لكلّ لهجة: `exporters` المدعومة و`consumers` (sadc/مفسّر/LSP/docgen) و`status`. +- `exporters.yaml`: سجلّ المُصدِّرات (ماركداون، HTML) وقدرات كلٍّ — **مصفوفة تنازل موثَّقة**: أيّ بنية يُسقطها المُصدِّر وكيف (المعادلة في ماركداون ⇒ كود خام + تحذير تصدير). +- `keywords.yaml`: كلمات اللهجات **سياقيّة** (تفعل داخل كتلتها فقط) كي لا تُحجَز «فقرة/بند/تعليمة» عالميًّا على المستخدمين. +- إضافة لهجة أو بنية أو مُصدِّر = قرار لغويّ عبر RFC (قاعدة «الأدوات لا توسّع SoT» القائمة). + +## المحلّل المعجمي/النحوي + +- قاعدة فتح واحدة: `كتلة_لهجة ::= <كلمة اللهجة> [معرّف] … "نهاية"`. داخل الكتلة يُفعَّل جدول بُنى اللهجة (مولَّد من SoT — كما تولَّد قواعد المحلّل اليوم من `grammar/`). +- لا وضع «نصّ خام» إلّا في موضعين معلنَين في SoT: متن `معادلة «…»` ومنفذ الهروب الموروث `@تجميع("…")`؛ كلّ ما عداه — **بما فيه تعليمات التجميع العربيّة** — بُنى مفحوصة معجميًّا ودلاليًّا. +- السلاسل الوثائقيّة تدعم الاستيفاء `{تعبير}` بنفس آليّة سلاسل ص. + +## الشجرة المجرّدة (AST) + +- عقد لهجة مولَّدة من SoT (نمط توليد `prop_keys.h` القائم): `DocHeading، DocParagraph، DocList، DocFormula، DocLiveView، AsmInstruction…` تحت عقدة جذر `DialectBlock{dialect_id}`. +- توثيق `##` مثبَت أصلًا حقلَ `docComment` على قاعدة `ASTNode` ويلتقطه المحلّل لنحو ٣٠ صنف تصريح — يُبنى عليه لا يوازيه، مع إصلاح عيوب الالتصاق القائمة (ذيل السطر، النجاة عبر الأسطر الفارغة) بتحذيرات كتالوج معلَنة. + +## المفسّر + +- «مستند»: القيمة كائن وثيقة من الدرجة الأولى (تُمرَّر، تُصدَّر، تُعرَض في SadUI عبر `عرض_حيّ`). التعابير المستوفاة تُقيَّم كسولًا عند التصدير/العرض. +- «تجميع»: خطأ كتالوج «مترجم فقط» (نمط بوّابة `@غير_آمن`). +- `صدّر(وثيقة، «صيغة»)` مدمج جديد يوجَّه لسجلّ المُصدِّرات؛ صيغة غير مسجَّلة ⇒ خطأ بقائمة المتاح. + +## المترجم (sadc) + +- «تجميع»: التعليمات العربيّة تُخفَض عبر معجم المنمنمات إلى قالب `llvm::InlineAsm` (توليد المنمنمة الأصليّة والقيود آليًّا من الـAST — المستخدم لا يرى هذه الطبقة)، مع اشتقاق القيود من ربط المعاملات ومن مدخلات/مخرجات/يلوّث؛ تكامل مع `عنوان_رمز` و`@رمز` (3.13/3.14)؛ حالة في فحص `--الوضع-الحرّ` التدقيقيّ. +- «مستند»: بنية بيانات ساكنة في `.rodata` (تكامل مع آليّة `بايتات(...)`) + استدعاءات تقييم للتعابير المستوفاة. + +## نظام الأخطاء + +- `SEM0xx` بنية لهجة في غير سياقها («بند» خارج «قائمة»). +- `SEM0xx` لهجة/مُصدِّر غير مسجَّل (مع قائمة المتاح). +- `SEM0xx` لهجة «مترجم فقط» في المفسّر. +- تحذير تصدير: بنية أُسقطت لأنّ الصيغة الهدف لا تحملها (مصفوفة التنازل). + +## الأدوات + +- **LSP/محراب:** تسجيل صنف الملفّ `.مستند` في محراب (لغة + أيقونة)؛ إكمال وتلوين بُنى اللهجات من SoT (لا حقن قواعد أجنبيّة إلّا لمتن `معادلة` ومنفذ الهروب `@تجميع` الموروث)؛ التحويم يعرض توثيق `##` مُصيَّرًا. +- **عارض المستندات في محراب:** إضافة عرضٍ مدمجة تفتح `.مستند` معاينةً حيّةً مصيَّرةً (webview بنية AR-01) جنبًا إلى جنب مع المصدر؛ تقييم الاستيفاء والعناصر التفاعليّة عبر المفسّر؛ أمر «صدّر إلى ماركداون/HTML» من لوحة الأوامر. +- **docgen:** مرجع API من كتل التوثيق مباشرةً إلى sadlang-docs. +- **المنسّق:** ينسّق بُنى اللهجة كبُنى ص (مسافات بادئة، لا مساس بمتون «…» الخام)، ويحمل أمر التصدير `--صدّر <صيغة>` سطريًّا (نفس محرّك المُصدِّرات الذي يستدعيه LSP). + +## التوافق الخلفي + +لا كسر: كلمات اللهجات سياقيّة، `@تجميع` يبقى سكّرًا، و`##` **ميزة قائمة تُرقَّى في محلّها** (نظام الوسوم القائم يبقى مقبولًا؛ التغييران السلوكيّان المعلَنان — قطع الالتصاق بالسطر الفارغ ورفض ذيل السطر — يخرجان بتحذيرات كتالوج لا كسر صامت). داخل كتل اللهجات `##` تعليق عاديّ (يُعزَل `pendingDocComment_` في مسار الكتلة). + +# السلبيات (Drawbacks) + +- أثقل تنفيذًا من «كتلة خام»: بُنى ولهجات وعقد مولَّدة ومُصدِّرات — لذلك التقسيم مراحل (انظر القرارات المحسومة). +- معجم المنمنمات عبء صيانة لكلّ معماريّة، ومن يعرف الأسمبلي التقليديّ سيتعلّم الأسماء العربيّة — يُخفَّف بالتغطية بحاجة النحلة (عشرات لا آلاف)، وبذكر المقابل الأعجميّ في التحويم والتوثيق المولَّد، وبمنفذ الهروب `@تجميع` للموروث. +- من يريد «لصق ماركداون موجود» سيحتاج استيرادًا/تحويلًا بدل اللصق الحرفيّ (يُخفَّف بالمستورِد المقرَّر مع م٣). +- مصفوفة التنازل تحتاج صيانة مع كلّ بنية/مُصدِّر جديدين. + +# المبرّرات والبدائل (Rationale and alternatives) + +- **بديل مرفوض: كتل محتوًى أجنبيّ خام** (النسخة الأولى من هذا المقترح). يجعل ص مضيفًا يتقيّد بسقف الصيغة الأجنبيّة: لا فحص، لا إكمال، لا ميزات فوق ماركداون، وكلّ توسّع مستقبليّ مسدود بنيويًّا. رُفض لأنّ المِلكيّة الدلاليّة يجب أن تكون عند ص. +- **بديل: نظام ماكرو عامّ.** أقوى نظريًّا وأضخم عمليًّا؛ درس 3.14 قائم (الأقوى ≠ الأضخم، لا قوّة بلا مستهلك). اللهجات تغطّي الحاجات الفعليّة الثلاث (نحلة/توثيق/دروس) بكلفة محدودة. +- **بديل: الوثائق ملفّات ماركداون منفصلة كما اليوم.** يُبقي التوثيق ميتًا ومنفصلًا عن الكود ولا يحلّ النحلة أصلًا. +- أثر عدم الفعل: بقايا C في النحلة، توثيق ميت، وكلّ صنف محتوًى قادم يبدأ تفصيلًا يدويًّا من الصفر. + +# أعمال سابقة (Prior art) + +- **Typst وLaTeX**: الوثيقة برنامج بنموذج دلاليّ يملكه النظام، والصيغ (PDF/HTML) مخرَجات — النموذج الأقرب للهجة «مستند»؛ Typst تحديدًا أثبت أنّ نموذجًا حديثًا يتجاوز ماركداون مع بقائه أبسط من LaTeX. +- **Rust `asm!`**: مُعاملات وقيود وclobbers مفحوصة — النموذج الدلاليّ للهجة «تجميع». +- **JSX/Flutter**: شجرة واجهة كبُنى لغة أصيلة لا HTML خام — نفس مبدأ `عرض_حيّ`. +- **rustdoc/doctests**: توثيق من الدرجة الأولى يستهلكه LSP والمولّد والاختبار. +- **Pandoc**: نموذج وسيط واحد ومُصدِّرات كثيرة بمصفوفة قدرات — نموذج طبقة التصدير. + +# قرارات محسومة (قرارات المالك 2026-07-22) + +- **المراحل:** م١ لهجة تجميع (حاجة النحلة الأعجل) ⇒ م٢ توثيق `##` (توحيد المسارين القائمين وسدّ فجواتهما: LSP يقرأ من AST بدل المسح النصّيّ، إصلاح عيوب الالتصاق بتحذيرات، لُحمة JSON⇒sadlang-docs، عزل `##` عن كتل اللهجات) ⇒ م٣ لهجة مستند **مكتملة من البداية** (كلّ البُنى بما فيها معادلة/مخطّط/عرض_حيّ) + صنف الملفّ `.مستند` + عارض محراب + مُصدِّرا ماركداون/HTML + مستورِد من ماركداون إلى مستند. +- **اسم الامتداد: `.مستند`** — صريح يفسّر نفسه بنفسه؛ كون GitHub لا يصيّره مقبول لأنّ التصدير يغطّيه (README تُولَّد `.md`). +- **بُنى البذرة: كلّ شيء من البداية** — اللهجة تُطلق بكامل بُناها لا نواةً تتوسّع؛ التفوّق على ماركداون حاضر من اليوم الأوّل. +- **الترحيل الداخليّ من `.md`: عند المساس** — كلّ وثيقة تُمسّ تُرحَّل عبر المستورِد؛ لا حملة ضخمة تسبق نضج الأدوات، وREADME الموجّهة لGitHub تبقى `.md` مولَّدةً من مصدر `.مستند`. +- **المستورِد يُبنى مع م٣** — شرطُ سياسة الترحيل، والنموذج الأوسع يجعل الاستيراد بلا فقد. +- **معجم الأسمبلي العربيّ:** المسودّة المرفقة مرّت بمراجعة لغويّة (١٣ تصحيحًا ملزمًا طُبِّقت)، وحُسمت أسئلتها الثلاثة: + - **السجلّات دلاليّة لـi686** (المركم/العدّاد/فهرس_الوجهة…) لأنّ أدوار سجلّات x86 محفورة في العتاد فتُقرأ في الكود؛ الترقيم المحايد يُعتمد لاحقًا للمعماريّات المتعامدة (RISC-V `س٠…`) — القرار لكلّ معماريّة في ملفّها. + - **توحيد معجم البتّيّات على أسماء اللهجة** (وافق/ضمّ/خالف/اعكس_البتّات/أزح_يسارًا/أزح_يمينًا): تُرحَّل المدمجات القائمة `بت_و/بت_أو/بت_حصري/بت_نفي/بت_يسار/بت_يمين` إلى هذه الأسماء — يترتّب عليه **دَين ترحيل** في كود النواة المستهلِك (نمط حملة إعادة تسمية مدمجات العتاد السابقة) يُتتبَّع في Issue التنفيذ. + - **المنسّق يطبّع أزواج المرادفات حسب السياق**: بعد «قارن» ⇒ اقفز_إذا_ساوى/لم_يساوِ، وبعد «افحص/أنقص» وأشباهها ⇒ اقفز_إذا_صفر/لم_يصفر — كلّ وجه في موضعه الدلاليّ. + +# أسئلة غير محسومة (Unresolved questions) + +- صياغة توسيع قيود التجميع (`في_سجل`) — تُحسَم بحاجة النحلة الفعليّة أثناء م١. +- خارج النطاق: نظام ماكرو عامّ، تنفيذ لهجات تنفيذيّة جديدة (سيكوَل…)، محرّر WYSIWYG. + +# إمكانات مستقبلية (Future possibilities) + +- doctests: أمثلة الكود داخل التوثيق تُنفَّذ اختباراتٍ في CI. +- مُصدِّر PDF/عرض تقديميّ من لهجة «مستند» نفسها. +- لهجة «واجهة» ملفّيّة لSadUI تصريحيّ خالص. +- مستورِدات صيغ خارجيّة إضافيّة (CSV⇒جدول…) كطبقة أدوات فوق النموذج — مستورِد ماركداون نفسه محسوم ضمن م٣ لا هنا. diff --git "a/text/0000-\330\247\331\204\331\204\331\207\330\254\330\247\330\252-\330\247\331\204\330\243\330\265\331\212\331\204\330\251-\331\205\330\271\330\254\331\205-\330\252\330\254\331\205\331\212\330\271-i686.yaml" "b/text/0000-\330\247\331\204\331\204\331\207\330\254\330\247\330\252-\330\247\331\204\330\243\330\265\331\212\331\204\330\251-\331\205\330\271\330\254\331\205-\330\252\330\254\331\205\331\212\330\271-i686.yaml" new file mode 100644 index 0000000..358a525 --- /dev/null +++ "b/text/0000-\330\247\331\204\331\204\331\207\330\254\330\247\330\252-\330\247\331\204\330\243\330\265\331\212\331\204\330\251-\331\205\330\271\330\254\331\205-\330\252\330\254\331\205\331\212\330\271-i686.yaml" @@ -0,0 +1,148 @@ +# معجم منمنمات التجميع العربيّ — معماريّة i686 (مسودّة مرفقة بـRFC «اللهجات الأصيلة القابلة للتوسّع») +# الوجهة النهائيّة بعد القبول: language-truth/dialects/assembly_mnemonics/i686.yaml +# +# هذا الملفّ هو الموضع الوحيد في المنظومة الذي تُذكَر فيه المنمنمات اللاتينيّة — توثيقًا للتقابل وخفضًا. +# مبادئ التسمية: +# ١. فعل أمر أوّلًا (امتداد قاعدة مدمجات العتاد: اقرأ_منفذ/اكتب_ذاكرة). +# ٢. الصفة تلي الموصوف وتطابقه جنسًا. +# ٣. التغطية بحاجة النحلة الفعليّة (أرضيّة _start/ISR/__divdi3/memset + بقايا sgdt/sidt) لا شموليّة x86. +# ٤. منمنمة غير معجميّة = خطأ كتالوج، لا تمرير صامت. +# ٥. «عُد» لـret (لا «ارجع» — محجوزة للغة ص نفسها)، ولا استعمال لأيّ كلمة ص محجوزة. +# ٦. «اقفز_إذا_…» يليها فعل (ساوى/فاض/حمل) أو اسم بتقدير «كان» يُكتب مجرّدًا في المنمنمة (صفر/أصغر/دون/فوق/سالب) — كلاهما مقبول. +# ٧. الصيغة المعتمدة في SoT مشكولة بالشدّة، والمرادف المجرّد يولَّد آليًّا (المترجم يجرّد الشدّة). + +version: "0.1-draft" +architecture: i686 +status: draft + +# ─── السجلّات ─────────────────────────────────────────────── +# محسوم (2026-07-22): أسماء دلاليّة لـi686 — أدوار سجلّات x86 محفورة في العتاد فتُقرأ في الكود. +# الترقيم المحايد (س٠…) يُعتمد لاحقًا للمعماريّات المتعامدة (RISC-V) كلٌّ في ملفّها. +registers: + general_32: + - { ar: المركم, en: eax, role: "المراكمة ونتائج الضرب/القسمة والعائد" } + - { ar: القاعدة, en: ebx, role: "قاعدة عنونة عامّة" } + - { ar: العدّاد, en: ecx, role: "عدّاد التكرار والإزاحة" } + - { ar: البيانات, en: edx, role: "امتداد المركم في الضرب/القسمة والمنافذ" } + - { ar: فهرس_المصدر, en: esi, role: "فهرس المصدر في عمليّات السلاسل (لا يلتبس بدور المعامل «مصدر»)" } + - { ar: فهرس_الوجهة, en: edi, role: "فهرس الوجهة في عمليّات السلاسل" } + - { ar: قاعدة_الإطار, en: ebp, role: "قاعدة إطار المكدّس الحاليّ" } + - { ar: رأس_المكدّس, en: esp, role: "رأس المكدّس" } + general_16: # النصف الأدنى ١٦ بت: لاحقة _١٦ + - { ar: المركم_١٦, en: ax } + - { ar: العدّاد_١٦, en: cx } + - { ar: البيانات_١٦, en: dx } + general_8: # الثُّمن الأدنى/الأعلى: لاحقتا _الأدنى/_الأعلى + - { ar: المركم_الأدنى, en: al } + - { ar: المركم_الأعلى, en: ah } + - { ar: العدّاد_الأدنى, en: cl, role: "المعامل الوحيد المقبول لمقدار إزاحة/تدوير متغيّر" } + - { ar: البيانات_الأدنى, en: dl } + segment: + - { ar: مقطع_الكود, en: cs } + - { ar: مقطع_البيانات, en: ds } + - { ar: مقطع_المكدّس, en: ss } + - { ar: مقطع_الوجهة, en: es, role: "مقطع وجهة عمليّات السلاسل ES:EDI" } + control: # سجلّات التحكّم تُقرأ/تُكتب بالمدمجات الأصيلة القائمة (اقرأ_سجل_تحكم…)؛ تُذكر هنا للعنونة فقط + - { ar: سجلّ_التحكّم_٠, en: cr0 } + - { ar: سجلّ_التحكّم_٢, en: cr2 } + - { ar: سجلّ_التحكّم_٣, en: cr3 } + +# ─── صيغة العنونة (مسودّة) ───────────────────────────────── +# مباشر: انقل المركم، ٥ +# سجلّ: انقل المركم، القاعدة +# ذاكرة [قاعدة+إزاحة]: انقل المركم، [القاعدة + ٤] +# ذاكرة [قاعدة+فهرس×حجم+إزاحة]: انقل المركم، [القاعدة + العدّاد × ٤ + ٨] +# متغيّر ص: انقل المركم، {عنوان_المخزن} ← ربط تلقائيّ بقيد InlineAsm +addressing_note: "الترتيب: الوجهة أوّلًا ثمّ المصدر (اصطلاح Intel — كترتيب المفعولين في «سلّم فلانًا الشيءَ»)" + +# ─── التعليمات ────────────────────────────────────────────── +instructions: + + نقل_وبيانات: + - { ar: انقل, en: mov, operands: [وجهة, مصدر] } + - { ar: انقل_بتصفير, en: movzx, operands: [وجهة, مصدر], note: "توسيع بلا إشارة" } + - { ar: انقل_بمدّ_الإشارة, en: movsx, operands: [وجهة, مصدر] } + - { ar: بادل, en: xchg, operands: [وجهة, مصدر] } + - { ar: حمّل_عنوان, en: lea, operands: [وجهة, ذاكرة] } + - { ar: ادفع, en: push, operands: [مصدر] } + - { ar: اسحب, en: pop, operands: [وجهة] } + - { ar: ادفع_الكلّ, en: pusha, operands: [] } + - { ar: اسحب_الكلّ, en: popa, operands: [] } + - { ar: ادفع_الأعلام, en: pushf, operands: [] } + - { ar: اسحب_الأعلام, en: popf, operands: [] } + + حساب: + - { ar: اجمع, en: add, operands: [وجهة, مصدر] } + - { ar: اجمع_بالحمل, en: adc, operands: [وجهة, مصدر] } + - { ar: اطرح, en: sub, operands: [وجهة, مصدر] } + - { ar: اطرح_بالاستلاف, en: sbb, operands: [وجهة, مصدر] } + - { ar: اضرب, en: mul, operands: [مصدر], note: "بلا إشارة؛ الناتج البيانات:المركم (الأعلى في البيانات)" } + - { ar: اضرب_بإشارة, en: imul, operands: [وجهة, مصدر], note: "الصيغة الأحاديّة (ناتج البيانات:المركم) تُضاف عند حاجة __muldi3" } + - { ar: اقسم, en: div, operands: [مصدر], note: "بلا إشارة؛ يقسم البيانات:المركم على المصدر — الخارج في المركم والباقي في البيانات؛ صفّر البيانات قبلها وإلا #DE. أساسٌ تُبنى فوقه __divdi3" } + - { ar: اقسم_بإشارة, en: idiv, operands: [مصدر], note: "مدّ الإشارة قبلها بـمدّ_الإشارة_للبيانات" } + - { ar: مدّ_الإشارة_للبيانات, en: cdq, operands: [], note: "يمدّ إشارة المركم إلى البيانات — واجبة قبل اقسم_بإشارة" } + - { ar: زد, en: inc, operands: [وجهة] } + - { ar: أنقص, en: dec, operands: [وجهة] } + - { ar: اعكس_الإشارة, en: neg, operands: [وجهة] } + + منطق_وبتّات: + - { ar: وافق, en: and, operands: [وجهة, مصدر], note: "تبقى البتّات حيث يتوافق المعاملان («طابق» رُفضت — كلمة ص محجوزة). محسوم: معجم البتّيّات موحَّد على أسماء اللهجة — المدمجات بت_و/بت_أو/بت_حصري/بت_نفي تُرحَّل إليها (دَين ترحيل متتبَّع)" } + - { ar: ضمّ, en: or, operands: [وجهة, مصدر], note: "ضمّ البتّات" } + - { ar: خالف, en: xor, operands: [وجهة, مصدر], note: "تُرفع البتّات المختلفة؛ خالف س، س = تصفير" } + - { ar: اعكس_البتّات, en: not, operands: [وجهة] } + - { ar: افحص, en: test, operands: [أ, ب], note: "وافق بلا كتابة — يضبط الأعلام فقط" } + - { ar: قارن, en: cmp, operands: [أ, ب] } + - { ar: أزح_يسارًا, en: shl, operands: [وجهة, مقدار] } + - { ar: أزح_يمينًا, en: shr, operands: [وجهة, مقدار] } + - { ar: أزح_يمينًا_بإشارة, en: sar, operands: [وجهة, مقدار] } + - { ar: دوّر_يسارًا, en: rol, operands: [وجهة, مقدار] } + - { ar: دوّر_يمينًا, en: ror, operands: [وجهة, مقدار] } + + قفز_وتحكّم: + - { ar: اقفز, en: jmp, operands: [لصيقة] } + - { ar: اقفز_إذا_ساوى, en: je, operands: [لصيقة] } + - { ar: اقفز_إذا_لم_يساوِ, en: jne, operands: [لصيقة] } + - { ar: اقفز_إذا_صفر, en: jz, operands: [لصيقة], note: "مرادف اقفز_إذا_ساوى — يُقبل الاسمان؛ محسوم: المنسّق يطبّع حسب السياق (بعد قارن ⇒ ساوى، بعد افحص/أنقص ⇒ صفر)" } + - { ar: اقفز_إذا_لم_يصفر, en: jnz, operands: [لصيقة], note: "مرادف اقفز_إذا_لم_يساوِ — تطبيع سياقيّ كسابقه" } + - { ar: اقفز_إذا_أصغر, en: jl, operands: [لصيقة], note: "مقارنة بإشارة" } + - { ar: اقفز_إذا_أصغر_أو_ساوى, en: jle, operands: [لصيقة] } + - { ar: اقفز_إذا_أكبر, en: jg, operands: [لصيقة] } + - { ar: اقفز_إذا_أكبر_أو_ساوى, en: jge, operands: [لصيقة] } + - { ar: اقفز_إذا_دون, en: jb, operands: [لصيقة], note: "مقارنة بلا إشارة" } + - { ar: اقفز_إذا_دون_أو_ساوى, en: jbe, operands: [لصيقة] } + - { ar: اقفز_إذا_فوق, en: ja, operands: [لصيقة] } + - { ar: اقفز_إذا_فوق_أو_ساوى, en: jae, operands: [لصيقة] } + - { ar: اقفز_إذا_حمل, en: jc, operands: [لصيقة] } + - { ar: اقفز_إذا_فاض, en: jo, operands: [لصيقة] } + - { ar: اقفز_إذا_سالب, en: js, operands: [لصيقة] } + - { ar: أنقص_واقفز_إن_لم_يصفر, en: loop, operands: [لصيقة], note: "يُنقص العدّاد ويقفز ما لم يصفر (لا «كرّر» في الاسم — محجوزة لبادئة rep)" } + - { ar: نادِ, en: call, operands: [هدف] } + - { ar: عُد, en: ret, operands: [], note: "«عُد» لا «ارجع» — الأخيرة كلمة ص محجوزة" } + - { ar: عُد_من_المقاطعة, en: iret, operands: [] } + - { ar: استدعِ_مقاطعة, en: int, operands: [رقم] } + + مقاطعات_ونظام: + - { ar: عطّل_المقاطعات, en: cli, operands: [] } + - { ar: فعّل_المقاطعات, en: sti, operands: [] } + - { ar: أوقف, en: hlt, operands: [] } + - { ar: لا_عمل, en: nop, operands: [] } + - { ar: خزّن_جدول_الواصفات, en: sgdt, operands: [ذاكرة], note: "بقايا C الأخيرة في النحلة — الدافع المباشر للهجة؛ يقابل المدمج القانونيّ القائم حمل_جدول_واصفات" } + - { ar: خزّن_جدول_المقاطعات, en: sidt, operands: [ذاكرة], note: "يقابل المدمج القانونيّ القائم حمل_جدول_مقاطعات" } + - { ar: اقرأ_عدّاد_الدورات, en: rdtsc, operands: [], note: "دورات المعالج لا الزمن؛ الناتج البيانات:المركم — يوائم المدمج القائم عداد_الدورات" } + - { ar: استخبر_المعالج, en: cpuid, operands: [], note: "الدخل الضمنيّ: رقم الورقة في المركم؛ المخرجات في المركم/القاعدة/العدّاد/البيانات" } + + سلاسل_وذاكرة: + - { ar: انقل_بايت, en: movsb, operands: [], note: "من [فهرس_المصدر] إلى [فهرس_الوجهة]" } + - { ar: انقل_مربّعًا, en: movsd, operands: [], note: "٤ بايتات دفعةً — أساس memcpy السريع" } + - { ar: خزّن_بايت, en: stosb, operands: [], note: "أساس memset الأرضيّة" } + - { ar: خزّن_مربّعًا, en: stosd, operands: [], note: "٤ بايتات دفعةً — memset السريع عبر كرّر خزّن_مربّعًا" } + - { ar: كرّر, en: rep, operands: [تعليمة], note: "بادئة تكرار بالعدّاد: كرّر خزّن_بايت. اللبس مع اللصائق محسوم بالنقطتين، والمفضَّل أسلوبيًّا لصائق كـ«حلقة:» لا «كرّر:»" } + +# ─── خارج المعجم عمدًا ───────────────────────────────────── +# lgdt/lidt وCRn وrdmsr/wrmsr وinvlpg وin/out: لها مدمجات ص أصيلة قائمة +# (حمل_جدول_واصفات…/اقرأ_سجل_تحكم/اقرأ_منفذ… بأسمائها القانونيّة في SoT) — المدمج الأصيل مقدَّم على التجميع دائمًا، +# واللهجة لسدّ ما لا مدمج له. +# سجلّات SSE (xmm0–7) وتعليماتها (movd/pxor…): مؤجَّلة عمدًا إلى حاجة فعليّة +# (مسبار xmm7 في أرضيّة النحلة يُقيَّم عندئذٍ)، تُضاف فئةً مستقلّةً حينها. +# صيغة ret imm16 (تنظيف الوسائط): تُضاف عند الحاجة — «عُد» الحاليّة بلا معامل. +# سجلّات ثانوية (bx/bl/bh/ch، fs/gs، cr4): تُضاف بحاجة النحلة وفق المبدأ ٣.