L'interfaccia dell'analizzatore

Tutte le interazioni con il sito web di Exercism vengono gestite automaticamente. Gli analyzer hanno la sola responsabilità di prendere una soluzione e restituire uno stato ed eventuali messaggi.

Esecuzione

• Un analyzer dovrebbe fornire uno script eseguibile. Puoi trovare maggiori informazioni nel file docker.md.
• Lo script riceverà tre parametri:
  • Lo slug dell'esercizio (ad esempio two-fer).
  • Un percorso verso una directory che contiene i file inviati (con una barra finale).
  • Un percorso verso una directory di output (con una barra finale). Questa directory è scrivibile.
• Lo script deve scrivere un file analysis.json nella directory di output.
• Lo script dovrebbe scrivere un file tags.json nella directory di output.

Tempo di esecuzione consentito

L'analyzer ottiene il 100% delle risorse della macchina per una finestra di 20 secondi per ogni soluzione. Dopo 20 secondi, il processo viene interrotto e segnala un timeout.

Formato dell'output

analysis.json

Il file analysis.json dovrebbe essere strutturato come segue:

{
  "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 (opzionale)

Il campo summary è un campo di testo (non markdown) che riassume l'output. Potrebbe dire qualcosa come «La soluzione è quasi pronta: ci sono solo due piccole modifiche che puoi fare» oppure «Il codice funziona benissimo, ma c'è un po' di linting da fare». Questo riepilogo viene mostrato sul sito sopra i commenti.

comments

Il campo comments è un array di commenti che rimandano a documenti Markdown in exercism/website-copy (per maggiori informazioni, vedi Scrivere i commenti degli analyzer). Ogni valore dell'array è una stringa puntatore oppure un oggetto JSON con il seguente formato:

comment

La stringa puntatore a un file in website-copy.

params (opzionale)

Un oggetto JSON contenente eventuali parametri che devono essere interpolati durante il rendering. Ad esempio, nel file markdown potresti scrivere Try %{variable_name} += 1 instead, e poi impostare params su { "variable_name": "foo"} per sostituire %{variable_name} con la variabile effettiva usata dallo studente.

Quando usi file parametrizzati, assicurati di fare l'escape di tutti gli usi di % anteponendovi un altro %. Ad esempio: Try aim aim for 100%% of the tests passing.

type (opzionale)

I seguenti type sono validi:

• essential: Blocchiamo temporaneamente gli studenti finché non hanno affrontato questo commento
• actionable: Qualsiasi commento che dia a un utente un'istruzione specifica per migliorare la propria soluzione
• informative: Commenti che forniscono informazioni, ma non si aspettano necessariamente che gli studenti le usino. Ad esempio, in Ruby, se qualcuno usa la concatenazione di stringhe in TwoFer, gli parliamo anche della formattazione di stringhe, ma non suggeriamo che sia un'opzione migliore.
• celebratory: Commenti che dicono agli utenti che hanno fatto qualcosa di giusto, sia come commento generale sulla soluzione sia su una tecnica.

I commenti senza un campo type hanno come valore predefinito informative .

Attualmente, nel sito, blocchiamo temporaneamente gli studenti in presenza di commenti essential, incoraggiamo gli studenti a completare i commenti actionable prima di contrassegnare come completato un esercizio di pratica (ma non gli esercizi concettuali), ma non suggeriamo alcuna azione per i commenti informative o celebratory. Tuttavia, in futuro potremmo decidere di aggiungere emoji o indicatori ad altri tipi, oppure di raggrupparli separatamente.

tags.json

Il file tags.json dovrebbe essere strutturato come segue:

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

tags

Il campo tags è un array di stringhe. Ogni tag è formattato così: "<category>:<thing>".

Alcuni esempi:

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

I tag possono essere usati per identificare quali costrutti, tecniche o paradigmi usa una soluzione.

Per maggiori informazioni, vedi Taggare le soluzioni.

Debug

Il contenuto di stdout e stderr di ogni esecuzione viene salvato in file che potrai consultare in seguito.

Puoi scrivere un file analysis.out contenente le informazioni di debug che vuoi consultare in seguito.

Per approfondire

Prima di costruire un analyzer, ti consigliamo di leggere le nostre Linee guida per gli analyzer.