Az elemző interfésze

Az Exercism weboldalával való minden interakció automatikusan történik. Az elemzőknek egyetlen feladatuk van: átvesznek egy megoldást, majd visszaadnak egy státuszt és az esetleges üzeneteket.

Végrehajtás

• Az elemzőnek biztosítania kell egy futtatható szkriptet. További információkat a docker.md fájlban találsz.
• A szkript három paramétert kap:
  • A feladat slugja (pl. two-fer).
  • Egy elérési út a beküldött fájlt vagy fájlokat tartalmazó könyvtárhoz (záró perjellel).
  • Egy elérési út a kimeneti könyvtárhoz (záró perjellel). Ez a könyvtár írható.
• A szkriptnek egy analysis.json fájlt kell írnia a kimeneti könyvtárba.
• A szkriptnek ajánlott egy tags.json fájlt is írnia a kimeneti könyvtárba.

Engedélyezett futási idő

Az elemző minden megoldás esetén 20 másodpercre a gép erőforrásainak 100%-át kapja. 20 másodperc után a folyamat leáll, és időtúllépést jelez.

Kimeneti formátum

analysis.json

Az analysis.json fájl felépítése a következő:

{
  "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 (opcionális)

A summary mező egy szöveges (nem markdown) mező, amely összegzi a kimenetet. Tartalmazhat például ilyesmit: „A megoldásod már majdnem kész, csak két apró változtatás van hátra.”, vagy azt, hogy „A kód remekül működik, de még egy kis lintelést el kell végezni.”. Ez az összegzés a weboldalon a megjegyzések fölött jelenik meg.

comments

A comments mező olyan megjegyzések tömbje, amelyek a exercism/website-copy Markdown-dokumentumaira mutatnak (további információkat az elemzőmegjegyzések írása szakaszban találsz). A tömbben minden érték vagy egy mutatóstring, vagy egy JSON-objektum a következő formátumban:

comment

A website-copy egyik fájljára mutató string.

params (opcionális)

Egy JSON-objektum, amely azokat a paramétereket tartalmazza, amelyeket a megjelenítés során be kell helyettesíteni. Ha például a markdown-fájlba azt írod, hogy Try %{variable_name} += 1 instead, majd a params értékét { "variable_name": "foo"}-ra állítod, akkor a %{variable_name} helyére az a változó kerül, amelyet a tanuló ténylegesen használt.

Paraméterezett fájlok használatakor a % minden előfordulását escape-elned kell úgy, hogy egy másik % jelet teszel elé. Pl. Try aim aim for 100%% of the tests passing.

type (opcionális)

A következő type értékek érvényesek:

• essential: addig soft-blockoljuk a tanulókat, amíg nem foglalkoztak ezzel a megjegyzéssel
• actionable: bármely megjegyzés, amely konkrét utasítást ad a felhasználónak a megoldása javítására
• informative: olyan megjegyzések, amelyek információt adnak, de nem feltétlenül várják el, hogy a tanulók használják is őket. Ha például valaki Rubyban a String Concatenationt használja a TwoFerben, akkor a String Formattingról is tájékoztatjuk, de nem sugalljuk, hogy az jobb választás lenne.
• celebratory: olyan megjegyzések, amelyek jelzik a felhasználónak, hogy valamit jól csinált, akár a megoldás egészére vonatkozó általános megjegyzésként, akár egy technikára vonatkozóan.

A típusmező nélküli megjegyzések alapértelmezésben informative típusúak.

A weboldalon jelenleg az essential megjegyzéseknél soft-blockolunk, a tanulókat arra biztatjuk, hogy a gyakorlófeladatok elkészültként jelölése előtt foglalkozzanak az actionable megjegyzésekkel (a tanulófeladatoknál viszont nem), az informative és celebratory megjegyzéseknél pedig nem javaslunk semmilyen teendőt. A jövőben azonban előfordulhat, hogy más típusokhoz is adunk emojikat vagy jelzéseket, esetleg külön csoportosítjuk őket.

tags.json

A tags.json fájl felépítése a következő:

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

tags

A tags mező egy stringekből álló tömb. Minden címke formátuma: "<category>:<thing>".

Néhány példa:

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

A címkék segítségével azonosítható, hogy egy megoldás milyen konstrukciókat, technikákat és paradigmákat használ.

További információkat a megoldások címkézése szakaszban találsz.

Hibakeresés

Minden futás stdout és stderr kimenetének tartalma fájlokba kerül, amelyeket később megtekinthetsz.

Írhatsz egy analysis.out fájlt, amely olyan hibakeresési információkat tartalmaz, amelyeket később meg szeretnél nézni.

További olvasnivaló

Mielőtt elemzőt építesz, olvasd el az elemzőkre vonatkozó útmutatónkat.