واجهة المحلّل

تتم كل التفاعلات مع موقع Exercism تلقائيًا. وتقع على المحلّل مسؤولية واحدة: أن يأخذ حلًا ويُرجع حالة وأي رسائل.

التنفيذ

• ينبغي أن يوفّر المحلّل سكربتًا قابلًا للتنفيذ. يمكنك العثور على مزيد من المعلومات في ملف docker.md.
• سيستقبل السكربت ثلاث معاملات:
  • المعرّف المختصر للتمرين (مثل two-fer).
  • مسار إلى مجلد يحتوي على الملف (الملفات) المُرسَلة (مع شرطة مائلة في النهاية).
  • مسار إلى مجلد الإخراج (مع شرطة مائلة في النهاية). هذا المجلد قابل للكتابة.
• يجب أن يكتب السكربت ملف analysis.json في مجلد الإخراج.
• ينبغي أن يكتب السكربت ملف tags.json في مجلد الإخراج.

زمن التشغيل المسموح

يحصل المحلّل على كامل موارد الجهاز بنسبة 100% خلال نافذة مدتها 20 ثانية لكل حل. وبعد 20 ثانية، تُوقف العملية ويُبلَّغ عن انتهاء المهلة.

صيغة الإخراج

analysis.json

ينبغي أن يكون ملف analysis.json مُهيكلًا على النحو التالي:

{
  "summary": "This solution looks good but has a few points to address",
  "comments": [
    {
      "comment": "ruby.general.some_parameterised_message",
      "params": { "foo": "param1", "bar": "param2" },
      "type": "essential"
    },
    {
      "comment": "ruby.general.some_unparameterised_message",
      "params": {},
      "type": "actionable"
    },
    {
      "comment": "ruby.general.some_unparameterised_message"
    },
    "ruby.general.some_unparameterised_message"
  ]
}

summary (اختياري)

حقل summary حقل نصي (وليس Markdown) يلخّص الإخراج. قد يقول شيئًا مثل: «حلك على وشك أن يكتمل، لم يتبقّ سوى تغييرين صغيرين يمكنك إجراؤهما.» أو «الكود يعمل بشكل رائع، لكن هناك القليل من التدقيق المطلوب.». تُعرض هذه الخلاصة على الموقع فوق التعليقات.

comments

حقل comments مصفوفة من التعليقات التي تشير إلى مستندات Markdown في exercism/website-copy (انظر كتابة تعليقات المحلّل لمزيد من المعلومات). وكل قيمة في المصفوفة إما سلسلة نصية تشير إلى ملف، أو كائن JSON بالصيغة التالية:

comment

السلسلة النصية التي تشير إلى ملف في website-copy.

params (اختياري)

كائن JSON يحتوي على أي معاملات ينبغي إدراجها أثناء العرض. على سبيل المثال، في ملف Markdown يمكنك أن تكتب Try %{variable_name} += 1 instead، ثم تضبط params على { "variable_name": "foo"} لاستبدال %{variable_name} بالمتغير الفعلي الذي استخدمه الطالب.

عند استخدام ملفات ذات معاملات، احرص على تهريب كل استخدامات % بوضع % أخرى أمامها. مثل: Try aim aim for 100%% of the tests passing.

type (اختياري)

القيم التالية لـ type صالحة:

• essential: سنضع حجبًا مرنًا أمام الطلاب إلى أن يعالجوا هذا التعليق
• actionable: أي تعليق يقدّم للمستخدم تعليمات محددة لتحسين حله
• informative: تعليقات تقدّم معلومات، لكنها لا تتوقع بالضرورة أن يستخدمها الطلاب. على سبيل المثال، في Ruby إذا استخدم أحدهم دمج السلاسل النصية في TwoFer، فإننا نخبره أيضًا بتنسيق السلاسل النصية، لكننا لا نقترح أنه خيار أفضل.
• celebratory: تعليقات تخبر المستخدمين أنهم أحسنوا صنعًا، سواء كتعليق عام على الحل أو على تقنية معيّنة.

التعليقات التي لا تحتوي على حقل النوع (type) يُفترض فيها informative .

حاليًا في الموقع، نطبّق الحجب المرن على التعليقات من النوع essential، ونشجّع الطلاب على إكمال التعليقات من النوع actionable قبل وضع علامة الاكتمال في تمارين التدريب (وليس في تمارين المفاهيم)، لكننا لا نقترح أي إجراء على التعليقات من النوع informative أو celebratory. ومع ذلك، قد نختار في المستقبل إضافة رموز تعبيرية أو مؤشرات إلى أنواع أخرى، أو تجميعها بشكل منفصل.

tags.json

ينبغي أن يكون ملف tags.json مُهيكلًا على النحو التالي:

{
  "tags": [
    "construct:list",
    "paradigm:functional",
    "technique:higher-order-functions",
    "uses:List.unfold"
  ]
}

tags

حقل tags مصفوفة من السلاسل النصية. وتُنسَّق كل وسم (tag) بالشكل التالي: "<category>:<thing>".

ومن الأمثلة على ذلك:

• "paradigm:functional"
• "technique:recursion"
• "construct:bitwise-and"
• "uses:DateTime.add_seconds"

يمكن استخدام الوسوم لتحديد البُنى والتقنيات والنماذج البرمجية التي يستخدمها الحل.

لمزيد من المعلومات، انظر وسم الحلول.

تصحيح الأخطاء

يُحفظ محتوى stdout وstderr من كل تشغيل في ملفات يمكن عرضها لاحقًا.

يمكنك كتابة ملف analysis.out يحتوي على معلومات التصحيح التي تريد عرضها لاحقًا.

قراءات إضافية

قبل الشروع في بناء محلّل، يُرجى قراءة إرشادات المحلّل.