Segnalazioni di errore

Gli errori di sintassi, e in alcuni casi anche un uso scorretto delle funzioni di Idra, potranno far apparire una segnalazione di errore sotto forma di un messaggio di Idra o del browser stesso (nel caso che il problema si verifichi già nella fase di avvio). Nel messaggio verrano indicati, oltre al tipo del problema, il file contenente l'errore e la riga incriminata.

Se con Netscape il gioco non dovesse avviarsi o funzionasse in modo anomalo ma non si ricevesse alcuna segnalazione di errore, occorre scrivere nel riquadro dell'indirizzo (Location, URL) la speciale istruzione javascript: per mostrare la finestra della console JavaScript. Differenti browser potranno mostrare le stesse informazioni in diversi modi.

Idra cercherà, se possibile, di intercettare le segnalazioni di errore e di presentarle in una propria finestra informativa, in modo da non dipendere dalle caratteristiche di uno specifico browser; l'aspetto della finestra potrà cambiare, ma le informazioni rimarranno le stesse:
 

In questo caso il termine "Nascondiglio" non è definito: dato che esso inizia con una lettera maiuscola, si tratta probabilmente del nome di una pagina citata in qualche altra pagina, ma la cui funzione non è ancora stata scritta; la descrizione del tipo di errore è in inglese perché proviene da JavaScript stesso.

Se questo stesso messaggio fosse mostrato in una finestra del browser, indicherebbe invece un problema di caricamento iniziale, dovuto ad esempio a una parentesi mancante o a virgolette non chiuse, che impediscono a JavaScript di vedere la funzione Nascondiglio().

Anche quando una segnalazione viene mostrata da Idra, non è detto che la causa dell'errore sia indicata correttamente: può essere invece riportata una delle sue conseguenze (magari in un altro file), dalla quale può essere difficile risalire alla vera causa. Per semplificarsi la vita conviene perciò adottare alcuni accorgimenti durante la scrittura.
 

Come trovare gli errori

In questo modo si ha la certezza che un eventuale errore sia contenuto nelle poche righe che si sono appena scritte; a questo punto la prima cosa da controllare è che non ci siano evidenti errori di sintassi, come ad esempio delle parentesi graffe aperte e mai chiuse (o viceversa).

Se non ci sono errori evidenti, una tecnica molto efficace consiste nel fare in modo che una o più righe vengano ignorate: se la segnalazione sparisce, l'errore si trova con tutta probabilità in una di quelle righe. Un semplice sistema per far ignorare delle righe è quello di trasformarle in commenti:

function Pagina48() {
  titolo("Canile municipale")
//  testo("Sei stato catturato e rinchiuso insieme agli altri randagi.)
//  scelta("Cerchi di attaccare discorso con un bulldog", Pagina12)
//  scelta("Provi a fare amicizia con un dobermann", Pagina65)
  scelta("Ti accucci in un angolo", Pagina83)
}

Occorre naturalmente fare attenzione a non causare errori con i commenti: se ad esempio si mettesse le doppia barra davanti all'ultima riga, quella contenente solo la parentesi graffa, la funzione Pagina48() non sarebbe più terminata correttamente e l'interprete JavaScript segnalerebbe probabilmente un errore in tutt'altro posto.

Errori meno vistosi possono essere individuati semplicemente inserendo dei messaggi nel testo stesso della pagina, ad esempio per verificare se certe istruzioni vengano eseguite o meno:

testo("Il traliccio ondeggia al vento; ti senti in posizione precaria.")
if (condizione_complicata) {
  ...
  testo(" - 1 - ")  //istruzione 'spia'
  ...
}

Il traliccio ondeggia al vento; ti senti in posizione precaria. - 1 -

Questa tecnica, benché semplicissima, è assai versatile e consente di analizzare accuratamente il funzionamento di un programma (non solo in JavaScript); vedremo tra breve che, per quanto riguarda il racconto-gioco vero e proprio, c'è uno strumento che in molti casi consente di risparmiare anche questo lavoro.
 

Alcuni errori comuni

- Sbagliare a scrivere una parola riservata, ad esempio funtion invece di function.
- Dimenticarsi di aprire o chiudere le parentesi graffe, tonde o quadre.
- Non aprire o chiudere virgolette (o apici) o usarle all'interno di una stringa delimitata dagli stessi.
- Scambiare maiuscole e minuscole, ad esempio Vai() invece di vai().
- Scrivere il nome di una pagina, o comunque di una funzione, inesistente.
- Chiamare una funzione col numero sbagliato di argomenti (dati tra parentesi).
- Usare funzioni supportate solo da uno specifico browser.

Alcuni di questi causano un'immediata segnalazione di errore all'avvio, mentre altri (come gli ultimi due) possono accadere durante la lettura, quando viene eseguita l'istruzione sbagliata. Altri errori frequenti riguardano espressamente Idra e le sue convenzioni; alcuni di questi non danno errore ma causano malfunzionamenti del gioco:

- Dimenticare il prefisso v. davanti ai nomi delle varibili di gioco.
- Chiamare una funzione con gli argomenti sbagliati, ad esempio vai("P3") invece che vai(P3).
- Chiamare direttamente una pagina, ad esempio P3() al posto di vai(P3).
- Introdurre dei link nella pagina, ossia usare <a href="...">.
- Usare la funzione Math.random() di JavaScript invece che dado() per i numeri casuali.
- Chiamare funzioni di Idra non documentate nella guida di riferimento dell'appendice A.

Infine vi sono gli errori di gioco: pagine in cui mancano delle scelte o ve ne sono altre che invece dovrebbero essere disattivate, variabili con valori errati, risultati di una scelta che non sono quelli desiderati (magari solo in alcuni casi) e così via. Questi errori si trovano e si eliminano con un'accurata fase di collaudo, prima da parte dell'autore e poi di un ristretto gruppo di giocatori, anche con l'ausilio del sistema descritto di seguito.
 

Il debugger di Idra

Se il nome del file iniziale fosse stato cambiato, ad esempio da Racconto.html in Corsaro.html, lo si deve modificare anche all'interno del corrispondente file di debug, nell'esempio Corsaro-debug.html, nell'unica riga in cui esso è citato. La pagina descritta da questo secondo file deve infatti richiamare l'altra.

Se il racconto viene avviato in questo modo, sul lato sinistro della finestra vi sarà il link "Debug", che normalmente è assente: un clic su questo link attiverà il debugger mostrando le relative informazioni, un secondo clic lo nasconderà nuovamente per non disturbare la visione della pagina. Il debugger presenta le proprie informazioni al termine della pagina stessa, dopo una riga di stacco:

In cartoleria Il negozio è ben fornito, ma in tasca hai solo pochi spiccioli; non puoi acquistare entrambe le cose che ti servono. Compri la matita per 400 lire Compri la gomma per 300 lire pagina=Cartoleria, v.lire=500, v.matita=0, v.gomma=0 Scelta 1: v.matita = 1; v.lire -= 400; vai(Esame) Scelta 2: v.gomma = 1; v.lire -= 300; vai(Esame)

Per prima cosa viene indicato il nome della pagina corrente, in questo caso Cartoleria(), senza le parentesi e seguita dal valore di tutte le variabili di gioco (nell'esempio v.lire, v.matita e v.gomma).

Sotto al campo di input e ai pulsanti, di cui vedremo tra breve la funzione, sono indicate le scelte (compresi eventuali rinvii nel testo stesso) presenti nella pagina, secondo l'ordine in cui si presentano: nell'esempio "Scelta 1" corrisponde a "Compri la matita..." e "Scelta 2" a "Compri la gomma...".

Per ciascuna di esse sono indicate le istruzioni che verrebbero eseguite nel caso di un clic sulla scelta corrispondente; ad esempio, un clic su "Compri la matita..." farebbe eseguire le tre istruzioni JavaScript:

v.matita = 1;
v.lire -= 400;
vai(Esame)

Cambiare pagina

Naturalmente la pagina Esame() verrà presentata in base al valore corrente delle variabili di gioco: sia il testo che le scelte potranno essere diverse da quelle che si avrebbero raggiungendo la pagina stessa nel corso del gioco.

È da notare che richiedendo una seconda volta la stessa pagina (ad esempio scrivendone ancora il nome e premendo "Esegui") essa potrà avere un diverso aspetto: infatti durante la presentazione vengono eseguite le istruzioni JavaScript contenute nella pagina, che possono cambiare il valore di una o più variabili, influenzando la presentazione stessa o quella successiva.

A volte ciò è precisamente quello che si desidera, per esempio nel caso in cui si voglia controllare l'effettiva apparizione di testo o scelte dipendenti da un'estrazione casuale, cioè fatta con la funzione dado(). In questi casi si può far eseguire di nuovo la funzione di pagina premendo il pulsante "Aggiorna" che richiama la corrispondente funzione di Idra, come se nel campo di input fosse stata scritta l'istruzione aggiorna(). Per evitare aggiornamenti accidentali, l'esecuzione di un comando nullo (campo vuoto) non ha invece effetto.

Il tasto "Richiama", infine, serve per riscrivere automaticamente l'ultimo comando dato, nell'esempio Esame, in modo da poterlo eseguire nuovamente o modificare prima di dare la conferma; è particolarmente utile per la correzione di errori di battitura, o per scrivere un comando leggermente diverso da quello precedente.
 

Variabili e istruzioni

il valore contenuto della variabile di gioco v.lire verrà portato a 6000. Poiché la pagina viene ridisegnata dopo l'esecuzione del comando, come se fosse stata eseguita la funzione Aggiorna(), il nuovo valore avrà effetto immediato e sarà anche mostrato nell'elenco delle variabili:

pagina=Cartoleria, v.lire=6000, v.matita=0, v.gomma=0

Questa tecnica consente di verificare il corretto funzionamento del racconto-gioco, modificando le variabili per controllare che il testo venga correttamente cambiato, che siano visibili o invisibili determinate scelte, che queste ultime eseguano le azioni previste, e così via.

Se si scrive il nome di una variabile inesistente, ad esempio v.lir, essa viene creata e appare nell'elenco del debugger (sempre che inizi con il solito v.); ciò non causa inconvenienti, ma la si può comunque eliminare con l'apposita istruzione delete:

pagina=Cartoleria, v.lire=500, v.matita=0, v.gomma=0, v.lir=6000

Come sempre, dopo l'esecuzione delle istruzioni la pagine viene nuovamente mostrata chiamando la funzione aggiorna(); come illustrato in precedenza, ciò esegue le istruzioni contenute nella pagina stessa e può quindi modificarne il contenuto.

Infine, nel campo del debugger si può scrivere qualunque espressione valida in JavaScript, anche se complessa, ricordando che nel caso di più istruzioni di seguito esse vanno separate con un punto e virgola:

Modificare e ricaricare

Pur nella sua semplicità, il debugger è uno strumento piuttosto versatile che consente di mettere a punto ogni dettaglio del racconto-gioco, prima di farlo provare ai collaudatori, e di individuare con relativa facilità le cause dei problemi rilevati da questi ultimi.

Incidentalmente, il debugger consente al lettore di barare andando a modificare le variabili di gioco; ciò è tuttavia inevitabile e, d'altra parte, se qualcuno vuole andare subito all'ultima pagina del giallo per sapere chi è l'assassino... peggio per lui: non fa altro che rovinarsi il divertimento.