صفحات التوثيق
التشخيصات
تصف هذه الصفحة ما يطبعه السلطان حين يبلغ عن مشكلة: تخطيط الطرفية، ومخطط JSON، والأكواد العامة وشروحها، والاقتراحات والإصلاحات، والضمانات التي يحفظها كل منها. أما كيف تبنى التشخيصات داخل المترجم ففي iSpeak، والمقارنة بالمترجمات الأخرى في مقارنة التشخيصات.
اختيار الإخراج
| الخيار | أثره |
|---|---|
--lang=ar (الافتراضي)، --lang=en، --lang=auto |
لغة كل رسالة |
--diagnostic-format=human (الافتراضي)، short، json |
تخطيط الطرفية، أو سطر لكل تشخيص، أو أسطر JSON |
| `--color=always | never |
sultanc explain CODE، sultanc --explain CODE |
الشرح الطويل لكود عام |
تخطيط الطرفية
خطأ[SULTANC-NAME-UNKNOWN]: الاسم `cuont` غير معروف — الاسم المطلوب مفقود أثناء حل المراجع.
--> main.sn:6:18..6:23
|
6 | let y: i32 = cuont + 1;
| ^^^^^
|
= مساعدة: يوجد هنا اسم مرئي بتهجئة قريبة — البديل المقترح هو `count`.- السطر الأول هو الشدة، ثم الكود العام بين قوسين، ثم الرسالة: عنوان وجملة لكل حقيقة.
- يعطي
-->الملف وسطر البداية وعمودها، والنهاية حين يكون للنطاق نهاية. الأسطر والأعمدة تبدأ من 1، والأعمدة تعد محارف يونيكود (قيما عددية). - يعد سطر العلامات عناقيد المحارف الممتدة (UAX #29)، فالحرف مع حركاته علامة واحدة، وينسخ الجدول جدولا.
- للموقع المرتبط (
:::) مقتطفه وتسميته، وقد يكون في ملف آخر. - تليها أسطر
= ملاحظة:و= مساعدة:. - في الرسائل العربية تحاط كل حقيقة مقتبسة بعازلي اتجاه أول قوي (U+2068 إلى U+2069) لتحفظ الحقيقة ذات الاتجاه من اليسار إلى اليمين ترتيبها داخل الجملة. ولا يحمل JSON هذه العلامات.
المقتطفات الآمنة
يعرض سطر المصدر في المقتطف كما كتب، إلا المحارف التي تغير طريقة عرض السطر أو تؤثر في الطرفية:
- محارف التضمين والتجاوز والعزل ثنائية الاتجاه (U+202A إلى U+202E، وU+2066 إلى U+2069) تعرض بصيغة
\u{202E}، ويرفضها المحلل المعجمي في المصدر أصلا (SULTANC-LEX-INVALID-TOKEN) لأنها قد تعرض الشفرة بترتيب غير الذي تترجم به (CVE-2021-42574)؛ - محارف التحكم الأخرى (C0 عدا الجدول، وDEL، وC1) تعرض بصيغة
\u{001B}؛ - البايت الذي ليس جزءا من محرف يوتيف-8 يعرض بصيغة
\xFF.
وتقع العلامة تحت التهريب.
JSON
يكتب --diagnostic-format=json كائن JSON في كل سطر، بالمخطط 3. حقوله:
| الحقل | معناه |
|---|---|
schema، language |
3، وen أو ar |
id |
الكود العام، مثل SULTANC-NAME-UNKNOWN، ولا يتغير باللغة |
kind |
النوع الآلي، مثل unknown-name |
severity |
error أو warning أو note |
category |
user أو environment أو internal أو unimplemented |
message |
الرسالة كاملة بلغة language |
primary_span، primary_role، primary_label |
الموقع الرئيسي |
arguments |
الحقائق ذات الأنواع: {"key", "type", "value"} (انظر iSpeak) |
related_spans |
{"role", "label", "span"} |
dependencies |
نطاقات أخطاء سابقة يتبعها هذا الخطأ |
notes، help |
{"message", "arguments"} |
fixes |
{"span", "replacement", "message", "applicability", "key", "edits"}، وكل تعديل {"span", "replacement", "range_utf16"} |
trace، trace_count |
مدخلات الأثر المفصل |
النطاق هو {"file", "source_id", "start_byte", "end_byte", "line", "column", "end_line", "end_column", "column_utf16", "end_column_utf16", "snippet"}. البايتات إزاحات داخل الملف، وline
وcolumn وend_column تبدأ من 1 وتعد المحارف. وcolumn_utf16 وend_column_utf16 هما العمودان نفساهما
معدودين بوحدات UTF-16 (من 1)، كمواضع LSP، فيطرح عميل LSP واحدا. ويكونان null حين لا يكون السطر
يوتيف-8. وهما دقيقان عند الطرفين وفي أي سطر للنطاق المبني من مصدره، وإلا اشتقا من السطر المعروض ويكون
end_column_utf16 قيمة null حين ينتهي النطاق في سطر آخر. ولمواقع سي القيمة 4294967295 في source_id
واسم ملف سي.
وkey في الإصلاح هو النوع الآلي الثابت للاقتراح (insert-semicolon، import-module، declare-mutable،
...، وnull لمفتاح بلا نوع). وrange_utf16 في كل تعديل مدى LSP {"start": {"line", "character"}, "end": {"line", "character"}} يبدأ من 0، أو null حين لا يتاح المصدر. وتعديلات الإصلاح الواحد تطبق معا ولا
تتداخل.
قابلية تطبيق الإصلاح:
| القيمة | معناها |
|---|---|
machine-applicable |
التعديل هو المقصود يقينا، ويجوز للأداة تطبيقه |
maybe-incorrect |
التعديل صحيح على الأرجح، لكن ينبغي أن ينظر فيه إنسان (اقتراحات التهجئة) |
has-placeholders |
في التعديل نص يجب ملؤه |
unspecified |
بلا دعوى |
المخطط يكبر ولا يتغير: يضاف الحقل الجديد، ويحفظ الحقل القائم اسمه ونوعه ومعناه.
الأكواد العامة
لكل تشخيص كود عام واحد. الأكواد وصفية (SULTANC-<المجال>-<الشيء>)، ولا يعاد استعمالها ولا ترقيمها.
ويثبت tests/{ar,en}/ispeak/check_public_codes.sn كل كود ونوعه الآلي بترتيب السجل: إعادة تسمية أحدها
أو حذفه أو تغيير ترتيبه تفشل ذلك الاختبار. ويضاف الكود الجديد في آخر السجل وآخر القائمتين في ذلك
الاختبار، مع كلماته العربية والإنجليزية ومجموعة شرحه وقرار قالبه.
الاقتراحات
لا يعطى اقتراح إلا بدليل:
- اسم مشابه. للاسم القيمي غير المعروف يقارن المترجم تهجئته المقننة (الهوية التي يقارنها محلل
الأسماء بعد تقنين المعرفات) بالأسماء المرئية من النطاق نفسه وفي الحيز نفسه: المتغيرات المحلية من
أعمق نطاق إلى أبعده، وتصريحات الوحدة، وبدائيات المترجم، والأسماء العامة للوحدات المستوردة كاملة.
المسافة عدد عمليات الإدراج والحذف والاستبدال لمحرف واحد ومبادلة محرفين متجاورين، ويجب ألا تزيد
على ثلث الطول، ولا اقتراح لاسم أقصر من ثلاثة محارف. وعند تساوي المسافة يفوز الأعمق ثم الأسبق. ويحل
المرشح من جديد من النطاق نفسه قبل عرضه، ولا يقترح المتغير المحلي داخل عبارة تصريحه. ويأتي سطر مساعدة
وإصلاح
maybe-incorrect. - استيراد ناقص. حين تصرح وحدة من المكتبة القياسية حملتها الترجمة بالاسم عاما، يسمي سطر مساعدة تلك
الوحدة، ويدرج إصلاح سطر استيرادها بعد آخر استيراد في الملف (أو قبل أول سطر شفرة فيه) بكلمات الملف
نفسه (
استوردأوimport). ويكون الإصلاحmachine-applicableحين تصرح بالاسم وحدة واحدة، وإلاmaybe-incorrect. ولا يبحث في وحدات لم تحملها الترجمة. متغير. الكتابة إلى ربطدعبلامتغير: سطر مساعدة وإصلاحmachine-applicableيدرجمتغير(mutable) قبل النوع المصرح.&و*. حين يتوقع مرجع إلى نوع القيمة وتكون القيمة اسما أو حقلا، يستعيرها إصلاحmaybe-incorrect(&أو&متغير). وحين تكون القيمة مرجعا إلى النوع المتوقع، يقرأ إصلاح عبره (*):machine-applicableللعدد والمنطقي والحرف، وإلاmaybe-incorrect.مثل. حين يجمع تحويل صريح بين نوعين عدديين، يلف إصلاح القيمة بالصورة(القيمة مثل النوع)بتهجئة الملف. ويكونmachine-applicableحين تكون كل قيمة من النوع الموجود قيمة من النوع المتوقع (عدد صحيح أعرض يحفظ الإشارة، أو عدد بإشارة أعرض)، وإلاmaybe-incorrect.- الكلمات المحجوزة. الكلمة المحجوزة في موضع اسم (حقل أو معامل أو معامل نوع) تأتي معها مساعدة باختيار اسم آخر.
ويفحص كل إصلاح على بايتات المصدر قبل عرضه. ولا تحذير بعد للأسماء غير المستخدمة، فلا إصلاح لها.
والأدوات التي تستورد المترجم (خادم LSP) تقرأ البيانات نفسها التي في JSON من
compiler.diagnostics.suggestions: يعيد اقتراحات_تشخيص(&التشخيص, اللغة) كل اقتراح (اقتراح_تشخيص:
المفتاح والنوع الآلي والكلمات والقابلية والتعديلات) وكل تعديل بإزاحات البايت ومواضع LSP
(تعديل_اقتراح_تشخيص)، ويبقي اقتراحات_آلية_لتشخيص الاقتراحات الآلية وحدها، ويطبق
طبق_اقتراحا_على_نص اقتراحا على نص الملف أو يعيد لا شيء حين يخرج تعديل عن النطاق أو يتداخل تعديلان.
ويطبق tests/{ar,en}/ispeak/check_suggestion_roundtrip.sn كل إصلاح آلي ثم يترجم الناتج.
أخطاء متعددة
يبلغ عن الأسماء غير المعروفة في الوحدة كلها، لكل منها دليله، وأولها هو الخطأ الذي كان المترجم يبلغ عنه
قبل. وحين يلي اسما غير معروف خطأ من نوع آخر لا يبلغ عنه، فقد يكون ناتجا عن الاسم غير المربوط. وتبلغ أخطاء
الملكية والاستعارة (SSF) كلها. أما المحلل المعجمي والمحلل النحوي ومدقق الأنواع فما زالت تقف عند أول خطأ.
وتحمل المجموعة 100 خطأ على الأكثر، ولا تسقط التحذيرات أبدا. والتشخيص الذي يسمي الإخفاق المصدري الذي
يعتمد عليه (dependencies) يسقط حين يكون ذلك الإخفاق قد بلغ.
تشخيصات سي
تستعمل تشخيصات استيرادات سي (SULTANC-C-*) التخطيط وJSON نفسيهما. الموقع هو ملف سي وسطره وعموده،
وتشتق الأعمدة من سطر سي، وتعرض سلسلة #include نطاقات مرتبطة بالدور included-from. وتعرض تحذيرات
استيراد سي حتى حين تنجح الترجمة.
الأخطاء الداخلية
إخفاق المترجم الذي ليس ذنب البرنامج فئته internal وكوده SULTANC-ICE-* أو SULTANC-INTERNAL-*، وتسمي
رسالته مرحلة المترجم، وتطلب مساعدته إعادة التشغيل بتشخيصات JSON والإبلاغ عن الخلل. أما إخفاق البرنامج
نفسه وقت التشغيل فليس تشخيصا من المترجم: انظر الأخطاء.