\chapter{Liste e stringhe definite dall'utente}
\label{chap-persist}

\section{Liste definite dall'utente}
\label{named-lists}

Molti comandi di \app{gretl} richiedono come argomenti una o più liste di
variabili. Per semplificare la loro gestione negli script di comandi, in
particolare nelle funzioni definite dall'utente, \app{gretl} offre la
possibilità di creare \textit{liste definite dall'utente}.  

\subsection{Creazione e modifica di una lista}

Per creare una lista occorre usare il comando \texttt{list}, seguito dal nome
della lista, un segno di uguale, e, in alternativa, \texttt{null} (per creare
una lista vuota) o il nome di una o più variabili da inserire nella lista. Ad
esempio:
%
\begin{code}
list xlist = 1 2 3 4
list reglist = income price 
list empty_list = null
\end{code}

È disponibile una forma speciale: se si usa la parola chiave \texttt{dataset}
al posto di una lista vera e propria di variabili, verrà costruita una lista che
contiene tutte le serie di dati del dataset in uso (tranne che per la costante
predefinita \texttt{const}).

Il nome della lista deve iniziare con una lettera e deve essere composto
interamente da lettere, numeri o il carattere trattino basso (non da spazi). La
lunghezza massima del nome è di 15 caratteri. Quando si aggiungono variabili a
una lista è possibile riferirsi a essa per nome o per numero identificativo.

Una volta creata, una lista viene ``ricordata'' per l'intera durata della
sessione di \app{gretl} e può essere usata nel contesto di qualsiasi comando
\app{gretl} che accetta liste di variabili. Un semplice esempio è la
specificazione di una lista di regressori:
%
\begin{code}
list xlist = x1 x2 x3 x4
ols y 0 xlist
\end{code}

Le liste possono essere modificate in due modi. Per \textit{ridefinire} una
lista si usa la stessa sintassi usata per crearla. Ad esempio
%
\begin{code}
list xlist = 1 2 3
list xlist = 4 5 6
\end{code}

Dopo il secondo comando, \texttt{xlist} contiene solo le variabili 4,
5 e 6.

Per \textit{accodare} o \textit{premettere} variabili a una lista esistente,
è possibile usare il nome di una lista all'interno del comando di definizione
della lista stessa. Ad esempio, è possibile scrivere
%
\begin{code}
list xlist = xlist 5 6 7
list xlist = 9 10 xlist 11 12
\end{code}
%
Un altro modo per accodare un termine a una lista consiste nell'usare l'operatore \texttt{+=},
come in
%
\begin{code}
list xlist += cpi
\end{code}
%
Per eliminare una variabile da una lista, basta usare l'operatore \texttt{-=}:
%
\begin{code}
list xlist -= cpi
\end{code}
%

\subsection{Interrogazione delle liste}

È possibile determinare se una variabile sconosciuta rappresenta una lista
usando la funzione \texttt{islist()}.
%
\begin{code}
series xl1 = log(x1)
series xl2 = log(x2)
list xlogs = xl1 xl2
genr is1 = islist(xlogs)
genr is2 = islist(xl1)
\end{code}

Il primo comando \texttt{genr} assegnerà il valore 1 a \texttt{is1} visto che
\texttt{xlogs} in effetti è una lista. Il secondo comando genr assegnerà il
valore 0 a \texttt{is2}, visto che \texttt{xl1} è una serie di dati, non una
lista.

È anche possibile determinare il numero di elementi che compongono una lista
usando la funzione \texttt{nelem()}.
%
\begin{code}
list xlist = 1 2 3
genr nl = nelem(xlist)
\end{code}

Lo scalare \texttt{nl} avrà un valore di 3, visto che
\texttt{xlist} contiene 3 membri.

È possibile mostrare i membri di una lista come illustrato in questa sessione
interattiva:
%
\begin{code}
? list xlist = x1 x2 x3
 # list xlist = x1 x2 x3
Added list 'xlist'
? list xlist print
 # list xlist = x1 x2 x3
\end{code}
%
Si noti che \texttt{print xlist} produrrà un effetto diverso, ossia mostrerà i
valori di tutte le variabili contenute in \texttt{xlist} (come ci si può
aspettare).

\subsection{Liste di variabili trasformate}

Data una lista di variabili, è possibile generare liste che contengono
trasformazioni di queste variabili usando una forma speciale dei comandi
\texttt{logs}, \texttt{lags}, \texttt{diff}, \texttt{ldiff},
\texttt{sdiff} o \texttt{square}. In pratica basta far seguire questi comandi
dal nome della lista tra parentesi. Ad esempio:
%
\begin{code}
list xlist = x1 x2 x3
list lxlist = logs(xlist)
list difflist = diff(xlist)
\end{code}

Quando si genera una lista di \textit{ritardi} in questo modo, è possibile
specificare il massimo ordine di ritardi, inserendolo per primo tra parentesi e
separandolo dal nome della lista con una virgola. Ad esempio
%
\begin{code}
list xlist = x1 x2 x3
list laglist = lags(2, xlist)
\end{code}
%
oppure
%
\begin{code}
scalar order = 4
list laglist = lags(order, xlist)
\end{code}

Questi comandi riempiranno \texttt{laglist} col numero specificato di ritardi
delle variabili presenti in \texttt{xlist}. Come avviene per il normale comando
\texttt{lags} è possibile omettere l'ordine, che sarà così determinato
automaticamente a seconda della frequenza dei dati. Un altro modo speciale di
utilizzare questi comandi consiste nell'indicare tra parentesi il nome di una
singola variabile al posto di quello di una lista, come in
%
\begin{code}
series lx = log(x)
list laglist = lags(4, lx)
\end{code}

Si noti che la sintassi normale per questi comandi, ad esempio \texttt{logs},
è semplicemente
%
\begin{code}
logs x1 x2 x3
\end{code}
%
Se \texttt{xlist} è una lista, è anche possibile scrivere
%
\begin{code}
logs xlist
\end{code}
%
ma questo comando non salverà i logaritmi in una lista; per avere questo
risultato occorre usare la sintassi
%
\begin{code}
list loglist = logs(xlist)
\end{code}


\subsection{Controllo dei valori mancanti}

\app{Gretl} offre varie funzioni per riconoscere e gestire i valori mancanti (si
veda la \GCR{} per i dettagli). In questa sede è utile ricordare che la funzione
\texttt{ok()} può essere usata con un argomento lista. Ad esempio:
%
\begin{code}
list xlist = x1 x2 x3
series xok = ok(xlist)
\end{code}
%
Dopo questi comandi, la serie \texttt{xok} avrà valore 1 per le osservazioni in
cui nessuna variabile tra \texttt{x1}, \texttt{x2}, e
\texttt{x3} ha un valore mancante, e valore 0 per le osservazioni che non
soddisfano questa condizione.


\section{Stringhe definite dall'utente}
\label{named-strings}

In alcuni casi può essere utile salvare una stringa (ossia una sequenza di
caratteri) sotto forma di variabile che possa essere riutilizzata.
\app{Gretl} offre questa funzionalità a partire dalla versione 1.6.0, ma alcune
delle caratteristiche mostrate di seguito sono disponibili solo a partire dalla
versione 1.7.2.

Per \textit{definire} una variabile stringa è possibile usare uno dei comandi
seguenti: \texttt{string} o \texttt{sprintf}.  Il comando \texttt{string}
è il più semplice: basta scrivere, ad esempio
%
\begin{code}
string s1 = "Qualcosa da ricordare"
string s2 = getenv("HOME")
string s3 = @pippo + 10
\end{code}
%
Il primo campo dopo \texttt{string} è il nome della variabile che verrà creata,
quindi segue il segno di uguale, infine una specificazione della stringa da salvare.
Quest'ultima può essere la parola chiave \texttt{null}, per produrre una stringa
nulla, oppure può assumere una delle forme seguenti:

\begin{itemize}
\item una stringa letterale (racchiusa tra virgolette doppie)
\item il nome di una variabile stringa esistente, prefissata con \verb|@|
\item una funzione che produce una stringa (si veda oltre)
\item una delle forme viste finora, seguita da \texttt{+} e un valore intero che
  indica una posizione
\item una delle forme viste finora, seguita da uno spazio, seguito da un altro
  campo simile
\end{itemize}

Il ruolo del valore intero di posizione permette di usare una sotto-stringa
dell'elemento precedente, a partire dal carattere specificato. Se il valore
del parametro di posizione è maggiore della lunghezza della stringa in
questione, viene prodotto un messaggio di errore.

Nel caso in cui vengano usate due specificazioni separate da spazio, la stringa
risultante è la concatenazione dei due elementi.

Il comando \texttt{sprintf} è più flessibile. Funziona esattamente come
\texttt{printf} di \app{gretl}, tranne per il fatto che la stringa ``di formato'' deve
essere preceduta dal nome di una variabile stringa. Ad esempio,
%
\begin{code}
scalar x = 8
sprintf pippo "var%d", x
\end{code}

Per \textit{recuperare il valore} di una variabile stringa, basta usare il nome
della variabile preceduto dal carattere ``at'', \verb|@|.

In molti contesti la notazione \verb|@| è trattata come una ``macro'', ossia in
un comando \app{gretl} una sequenza di caratteri che segue il simbolo \verb|@|
viene trattata come il nome di una variabile stringa e il valore della variabile
viene sostituito sulla riga di comando, come avviene in questo esempio di
sessione interattiva:
%
\begin{code}
? scalar x = 8
 scalar x = 8
Generato lo scalare x (ID 2) = 8
? sprintf pippo "var%d", x
Salvata la stringa 'pippo'
? print "@foo"
var8
\end{code}
%
Si noti l'effetto delle virgolette doppie nella riga
\verb|print "@foo"|.  La riga
%
\begin{code}
? print @foo
\end{code}
%
\textit{non} stamperebbe un ``\texttt{var8}'' letteralmente, come visto sopra.
La riga verrebbe processata e letta come
%
\begin{code}
print var8
\end{code}
%
Quindi stamperebbe i valori della variabile \texttt{var8}, se esiste, oppure un
messaggio di errore.

In alcuni contesti specifici, comunque, è naturale trattare le variabili
\verb|@| come variabili a tutti gli effetti, e \app{gretl} si comporta proprio
così. Questo avviene quando le variabili appaiono:
\begin{itemize}
\item come argomenti dei comandi \texttt{printf} e
  \texttt{sprintf}.
\item nella parte destra di un'istruzione \texttt{string}.
\item come argomenti della funzione \texttt{isstring} (si veda sotto).
\end{itemize}

Ecco un esempio di uso delle stringhe come argomenti di
\texttt{printf}:
%
\begin{code}
? string vstr = "varianza"
Salvata stringa 'vstr'
? printf "vstr: %12s\n", @vstr
vstr:     varianza
\end{code}
%
Si noti che \verb|@vstr| non dovrebbe essere messa tra virgolette in questo
contesto. Allo stesso modo con
\begin{code}
? string copy = @vstr
\end{code}

\subsection{Stringhe predefinite}

Oltre alle stringhe definite dall'utente, \app{gretl} contiene alcune variabili
stringa predefinite che possono essere utili per chi scrive funzioni che
includono comandi shell. Le stringhe predefinite sono mostrate nella
Tabella~\ref{tab-strings}.

\begin{table}[htbp]
\centering
\begin{tabular}{ll}
  \verb|@gretldir| & La directory di installazione di \app{gretl} \\
  \verb|@workdir| & La directory di lavoro di \app{gretl} per l'utente \\
  \verb|@gnuplot| & Percorso, o nome, dell'eseguibile \app{gnuplot} \\
  \verb|@tramo| & Percorso, o nome, dell'eseguibile \app{tramo} \\
  \verb|@x12a| & Percorso, o nome, dell'eseguibile \app{x-12-arima} \\
  \verb|@tramodir| & Directory dei dati di \app{tramo} \\
  \verb|@x12adir| & Directory dei dati di \app{x-12-arima} \\
\end{tabular}
\caption{Variabili stringa predefinite}
\label{tab-strings}
\end{table}

\subsection{Lettura delle stringhe dall'ambiente}

In aggiunta, è possibile importare all'interno delle stringhe di \app{gretl}
dei valori che sono definiti nell'ambiente esterno. Per fare questo occorre
usare la funzione \texttt{getenv}, che richiede come argomento il nome di una
variabile di ambiente. Ad esempio:
%
\begin{code}
? string user = getenv("USER")
Salvata la stringa 'user'
? string home = getenv("HOME")
Salvata la stringa 'home'
? print "La home directory di @user è @home"
La home directory di cottrell è /home/cottrell
\end{code}
%
Per controllare se la variabile di ambiente richiamata da \texttt{getenv} è
non-vuota, si può usare la funzione \texttt{isstring}, come in questo esempio
%
\begin{code}
? string temp = getenv("TEMP")
Salvata la stringa vuota 'temp'
? scalar x = isstring(@temp)
Generato lo scalare x (ID 2) = 0
\end{code}
%
Si noti che \texttt{isstring} significa ``è una stringa che contiene
effettivamente qualcosa''.

Al momento la funzione \texttt{getenv} può essere usata solo nella parte destra
di un'istruzione \texttt{string}, come negli esempi visti sopra.

\subsection{Lettura delle stringhe usando la shell}

Se in \app{gretl} sono stati abilitati i comandi shell, è possibile catturare i
risultati dei comandi usando la sintassi

\texttt{string} \textsl{nome-stringa} = \texttt{\$(}\textsl{comando-shell}\texttt{)}

Ossia, si include il comando shell tra parentesi precedute dal carattere
dollaro.

\subsection{Lettura delle stringhe da file}

È possibile leggere il contenuto di un file e scriverlo all'interno di una
variabile stringa usando la sintassi

\texttt{string} \textsl{nome-stringa} = \texttt{readfile(}\textsl{nome-file}\texttt{)}

Il campo \textsl{nome-file} può includere variabili stringa. Ad esempio

\verb|string qnc = readfile(@x12adir/QNC.rts)|

\subsection{La funzione \texttt{strstr}}

Questa funzione viene usata nel modo seguente

\texttt{string} \textsl{nome-stringa} = 
\texttt{strstr(}\textsl{s1}\texttt{,} \textsl{s2}\texttt{)}

L'effetto è quello di cercare all'interno di \textsl{s1} la prima occorrenza di
\textsl{s2}.  Se non viene trovato alcun risultato, viene prodotta una stringa
vuota, altrimenti viene prodotta la porzione di \textsl{s1} che inizia per
\textsl{s2}. Ad esempio:
%
\begin{code}
? string hw = "hello world"
Saved string as 'hw'
? string w = strstr(@hw, "o")
Saved string as 'w'
? print "@w"
o world
\end{code}
%


%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "gretl-guide"
%%% End: 

