رابط تحلیلگر

همه‌ی تعامل‌ها با وب‌سایت Exercism به‌صورت خودکار انجام می‌شود. تحلیلگرها تنها یک وظیفه دارند: گرفتن یک راه‌حل و برگرداندن یک وضعیت به همراه هرگونه پیام.

اجرا

• هر تحلیلگر باید یک اسکریپت اجرایی ارائه کند. اطلاعات بیشتر را می‌توانید در فایل docker.md پیدا کنید.
• این اسکریپت سه پارامتر دریافت می‌کند:
  • اسلاگ تمرین (مثلاً two-fer).
  • مسیری به پوشه‌ای که فایل(های) ارسال‌شده را در خود دارد (با اسلش پایانی).
  • مسیری به پوشه‌ی خروجی (با اسلش پایانی). این پوشه قابل نوشتن است.
• اسکریپت باید یک فایل analysis.json در پوشه‌ی خروجی بنویسد.
• بهتر است اسکریپت یک فایل tags.json در پوشه‌ی خروجی بنویسد.

زمان اجرای مجاز

تحلیلگر برای هر راه‌حل، در یک بازه‌ی ۲۰ ثانیه‌ای ۱۰۰% منابع ماشین را در اختیار دارد. پس از ۲۰ ثانیه، این فرایند متوقف می‌شود و اتمام وقت را گزارش می‌دهد.

قالب خروجی

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 آرایه‌ای از رشته‌هاست. هر برچسب به این شکل قالب‌بندی می‌شود: "<category>:<thing>".

چند نمونه:

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

از برچسب‌ها می‌توان برای شناسایی ساختارها/تکنیک‌ها/الگوهای مورد استفاده‌ی یک راه‌حل استفاده کرد.

برای اطلاعات بیشتر، برچسب‌زدن به راه‌حل‌ها را ببینید.

Debugging

محتوای stdout و stderr در هر اجرا در فایل‌هایی ذخیره می‌شود که بعداً می‌توان آن‌ها را دید.

می‌توانید یک فایل analysis.out بنویسید که حاوی اطلاعات debugging باشد که می‌خواهید بعداً ببینید.

مطالعه‌ی بیشتر

پیش از ساختن یک تحلیلگر، لطفاً راهنمای تحلیلگر را بخوانید.