एनालाइज़र इंटरफेस

Exercism वेबसाइट से होने वाली हर बातचीत अपने आप संभाली जाती है। एनालाइज़र का काम बस इतना है: किसी हल को लेकर उसका स्टेटस और साथ में संदेश लौटाना।

निष्पादन

  • एनालाइज़र को एक एक्ज़ीक्यूटेबल स्क्रिप्ट देनी चाहिए। इस बारे में अधिक जानकारी आप docker.md फाइल में पा सकते हैं।
  • स्क्रिप्ट को तीन पैरामीटर मिलेंगे:
    • अभ्यास का स्लग (जैसे two-fer).
    • जमा की गई फाइलों वाली डायरेक्टरी का पाथ (अंत में स्लैश के साथ)।
    • आउटपुट डायरेक्टरी का पाथ (अंत में स्लैश के साथ)। इस डायरेक्टरी में लिखा जा सकता है।
  • स्क्रिप्ट को आउटपुट डायरेक्टरी में analysis.json फाइल लिखनी ही होगी।
  • स्क्रिप्ट को आउटपुट डायरेक्टरी में tags.json फाइल लिखनी चाहिए।

अनुमत रन समय

हर हल के लिए एनालाइज़र को 20 सेकंड तक मशीन के 100% संसाधन मिलते हैं। 20 सेकंड बाद प्रोसेस रोक दिया जाता है और वह टाइमआउट बताता है।

Note

टाइमआउट की संभावना कम करने के लिए हम परफॉर्मेंस बेस्ट प्रैक्टिसेज़ दस्तावेज़ का पालन करने की पूरी सलाह देते हैं।

आउटपुट फॉर्मैट

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 फील्ड कमेंट का एक ऐरे है, जिनमें से हर कमेंट exercism/website-copy में मौजूद Markdown दस्तावेज़ों से जुड़ा होता है (अधिक जानकारी के लिए एनालाइज़र कमेंट लिखना देखिए)। ऐरे में हर वैल्यू या तो एक पॉइंटर-स्ट्रिंग होती है या फिर नीचे दिए गए फॉर्मैट वाला 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: ऐसे कमेंट जो उपयोगकर्ता को बताते हैं कि उसने कुछ ठीक किया है, चाहे वह हल पर कोई सामान्य टिप्पणी हो या किसी तकनीक पर।

जिन कमेंट में टाइप फील्ड नहीं होती, वे अपने आप 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"

किसी हल में कौन-कौन से कंस्ट्रक्ट, तकनीक या पैराडाइम उपयोग हुए हैं, यह पहचानने के लिए टैग की मदद ली जा सकती है।

अधिक जानकारी के लिए हलों को टैग करना देखिए।

डीबगिंग

हर बार एनालाइज़र चलाने पर stdout और stderr की सामग्री फाइलों में सहेज दी जाती है। इन फाइलों को बाद में देखा जा सकता है।

आप एक analysis.out फाइल लिख सकते हैं, जिसमें वह डीबगिंग जानकारी हो जिसे आप बाद में देखना चाहते हैं।

आगे पढ़ने के लिए

एनालाइज़र बनाने से पहले हमारा एनालाइज़र मार्गदर्शन पढ़ लीजिए।