"Fossies" - the Fresh Open Source Software Archive

Member "gretl-2020e/doc/tex_it/functions.tex" (2 Oct 2015, 29170 Bytes) of package /linux/misc/gretl-2020e.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 \chapter{Funzioni definite dall'utente}
    2 \label{chap:functions}
    3 
    4 \section{Definizione di una funzione}
    5 \label{func-define}
    6 
    7 A partire dalla versione 1.3.3, \app{gretl} contiene un meccanismo per definire
    8 funzioni all'interno di uno script. Questa funzionalità ha subito alcune
    9 modifiche prima di raggiungere un assetto stabile ed estensibile, ma pensiamo che
   10 la versione presente in \app{gretl} 1.6.1 costituisca una solida base per gli
   11 sviluppi futuri.
   12 
   13 Occorre definire una funzione prima di poterla utilizzare. La sintassi
   14 per farlo è la seguente:
   15 
   16 \begin{code}
   17 function nome-funzione(parametri)
   18    corpo della funzione
   19 end function
   20 \end{code}
   21 
   22 Il \textsl{nome-funzione} identifica la funzione in modo univoco: deve
   23 iniziare con una lettera, può essere lungo al massimo 31 caratteri
   24 (eventuali caratteri in più verranno troncati) e non può contenere
   25 spazi. Se si tenta di definire una funzione con lo stesso nome di un
   26 comando di \app{gretl}.
   27 
   28 I \textsl{parametri} di una funzione vanno indicati sotto forma di lista
   29 separata da virgole. I parametri possono essere di uno dei seguenti tipi:
   30 
   31 \begin{center}
   32 \begin{tabular}{ll}
   33 \multicolumn{1}{c}{Tipo} &
   34 \multicolumn{1}{c}{Descrizione} \\ [4pt]
   35 \texttt{bool}   & variabile scalare usata come interruttore Booleano \\
   36 \texttt{int}    & variabile scalare usata come numero intero \\
   37 \texttt{scalar} & variabile scalare \\
   38 \texttt{series} & serie di dati \\
   39 \texttt{list}   & lista di serie \\
   40 \texttt{matrix} & matrice o vettore \\
   41 \texttt{string} & variabile stringa o stringa letterale
   42 \end{tabular}
   43 \end{center}
   44 
   45 Ogni elemento della lista di parametri deve includere due termini: per prima
   46 cosa un indicatore di tipo, quindi il nome con cui il parametro verrà
   47 riconosciuto all'interno della funzione. Ecco un esempio:
   48     
   49 \begin{code}
   50 function funzione(series y, list xvars, bool verboso)
   51 \end{code}
   52 
   53 Ognuno di questi indicatori di tipo, con l'eccezione di \texttt{list} e \texttt{string},
   54 può essere modificato facendo precedere da un asterisco il parametro ad esso
   55 associato, come in questo esempio
   56 %    
   57 \begin{code}
   58 function funzione(series *y, scalar *b)
   59 \end{code}
   60 
   61 Il significato di questa modifica è spiegato nella sezione
   62 \ref{funscope} e ha a che fare con l'uso dei puntatori nel linguaggio di
   63 programmazione C. Inoltre, i parametri possono essere modificati con il tag
   64 \texttt{const} (anche in questo caso, si veda la sezione \ref{funscope}).
   65 
   66 Oltre a questi elementi richiesti, la specificazione di un parametro
   67 \texttt{scalare} può includere fino a tre ulteriori informazioni: un valore
   68 minimo, uno massimo e un valore predefinito. Questi valori aggiuntivi devono
   69 seguire direttamente il nome del parametro, devono essere racchiusi tra
   70 parentesi quadre e i singoli elementi devono essere separati dal carattere due
   71 punti. Ad esempio, ipotizzando di avere un parametro intero chiamato
   72 \texttt{ordine} per cui si vuole specificare un valore minimo di 1, un massimo
   73 di 12 e un valore predefinito di 4, si può scrivere
   74 %    
   75 \begin{code}
   76 int ordine[1:12:4]
   77 \end{code} 
   78 %
   79 Per omettere uno dei tre valori aggiuntivi, basta lasciare vuoto il campo
   80 corrispondente. Ad esempio, \texttt{[1::4]} specifica un minimo di 1 e un valore
   81 predefinito di 4, senza porre limiti al valore massimo.
   82 
   83 Per parametri di tipo \texttt{bool} è possibile specificare come valori predefiniti 
   84 1 (vero) o 0 (falso), come in questo esempio:
   85 %    
   86 \begin{code}
   87 bool verboso[0]
   88 \end{code} 
   89 %
   90 
   91 È possibile definire funzioni che non hanno parametri (quelle che in alcuni
   92 linguaggi di programmazione vengono chiamate ``routine''). In questo caso,
   93 occorre usare la parola chiave \texttt{void} al posto dell'elenco dei
   94 parametri:
   95 %    
   96 \begin{code}
   97 function funzione2(void)
   98 \end{code}
   99 
  100 Quando una funzione viene chiamata, i parametri vengono istanziati
  101 usando gli argomenti indicati nella chiamata della funzione. Vengono
  102 fatti dei controlli automatici per assicurarsi che il numero degli
  103 argomenti contenuti in una chiamata di funzione corrisponda al numero
  104 di parametri, e che i tipi degli argomenti corrispondano ai tipi
  105 specificati nella definizione della funzione; se qualcuna di queste
  106 condizioni è violata, viene segnalato un errore. Una precisazione: è consentito
  107 omettere degli argomenti alla fine della lista, a patto che i valori predefiniti
  108 siano specificati nella definizione della funzione. Più precisamente: il
  109 controllo consiste nell'assicurarsi che il numero degli argomenti sia almeno
  110 uguale al numero dei parametri \textit{richiesti} e non superiore al numero
  111 totale dei parametri.
  112 
  113 È possibile indicare uno scalare, una serie, o una matrice come argomento
  114 di una funzione, sia specificando il nome di una variabile preesistente,
  115 oppure utilizzando un'espressione che, valutata, restituisce una variabile del
  116 tipo appropriato.  Gli scalari possono essere indicati anche sotto forma di
  117 valori numerici, mentre le liste devono essere indicate per nome.
  118 
  119 Il \textsl{corpo della funzione} è composto da comandi \app{gretl} o
  120 funzioni definite dall'utente (ossia, le funzioni possono essere
  121 nidificate). Una funzione può chiamare sé stessa (ossia, le funzioni possono
  122 essere ricorsive).  Se il corpo della funzione può contenere chiamate ad altre
  123 funzioni non può però contenere definizioni di altre funzioni, ossia non è
  124 possibile definire una funzione all'interno di un'altra funzione.
  125 
  126 \section{Chiamata di una funzione}
  127 \label{func-call}
  128 
  129 Una funzione utente viene chiamata, o invocata, usando il suo nome,
  130 eventualmente seguito da argomenti tra parentesi; se si usano due o più argomenti,
  131 vanno separati da virgole. L'esempio seguente mostra una chiamata di
  132 funzione che rispetta la definizione della funzione stessa.
  133     
  134 \begin{code}
  135 # Definizione della funzione
  136 function ols_ess(series y, list xvars)
  137   ols y 0 xvars --quiet
  138   scalar myess = $ess
  139   printf "ESS = %g\n", myess
  140   return scalar myess
  141 end function
  142 # Script principale
  143 open data4-1
  144 list xlist = 2 3 4
  145 # Chiamata della funzione (il valore restituito viene qui ignorato)
  146 ols_ess(price, xlist)
  147 \end{code}
  148 
  149 La chiamata della funzione contiene due argomenti: il primo è una
  150 serie di dati specificata per nome, e il secondo è una lista di
  151 regressori. Si noti che la funzione produce la variabile \verb+myess+
  152 come risultato, ma in questo esempio esso è ignorato. Una nota a
  153 margine: se si desidera che una funzione calcoli alcuni valori che
  154 hanno a che fare con una regressione, ma non si è interessati ai
  155 risultati completi della regressione, è possibile usare l'opzione
  156 \verb+--quiet+ con il comando di stima, come visto sopra.
  157     
  158 Un secondo esempio mostra una chiamata di funzione che assegna il
  159 valore prodotto dalla funzione ad alcune variabili:
  160     
  161 \begin{code}
  162 # Definizione di funzione
  163 function get_uhat(series y, list xvars)
  164   ols y 0 xvars --quiet
  165   series uh = $uhat
  166   return series uh
  167 end function
  168 # Script principale
  169 open data4-1
  170 list xlist = 2 3 4
  171 # Chiamata di funzione
  172 series resids = get_uhat(price, xlist)
  173 \end{code}
  174 
  175 \section{Cancellazione di una funzione}
  176 \label{func-del}
  177 
  178 Se si vuole cancellare dalla memoria una funzione definita in precedenza, è
  179 possibile usare le parole chiave \texttt{delete} o \texttt{clear}, come in
  180 
  181 \begin{code}
  182 function myfunc delete
  183 function get_uhat clear
  184 \end{code}
  185 
  186 Si noti che ridefinendo una funzione, la vecchia funzione viene automaticamente
  187 sovrascritta, quindi raramente è necessario cancellare una funzione in modo
  188 esplicito.
  189 
  190 \section{Programmazione delle funzioni}
  191 \label{func-details}
  192  
  193 \subsection{Variabili o puntatori}
  194 \label{funscope}
  195 
  196 Le serie, gli scalari, e le matrici che sono argomenti di una funzione possono
  197 essere passati alla funzione in due modi: ``così come sono'', oppure come puntatori.
  198 Si consideri l'esempio seguente:
  199 \begin{code}
  200 function triplo1(series x)
  201   series ret = 3*x
  202   return series ret
  203 end function
  204   
  205 function triplo2(series *x)
  206   series ret = 3*x
  207   return series ret
  208 end function
  209 \end{code}
  210 
  211 Queste due funzioni sono quasi identiche (e producono lo stesso risultato):
  212 l'unica differenza sta nel fatto che \texttt{triplo1} richiede una serie come
  213 argomento, come in \texttt{triplo1(serie)}, mentre \texttt{triplo2} richiede un
  214 \emph{puntatore} a una serie, come in \texttt{triplo2(\&serie)}. 
  215 
  216 Perché questa distinzione? Ci sono due motivi principali: il più importante è
  217 la modularità, il secondo le prestazioni.
  218 
  219 L'idea di modularità nasce dal fatto che isolare le funzioni dal resto di uno
  220 script è di solito una buona idea. Uno dei tanti benefici di questo approccio
  221 consiste nel fatto che le funzioni sono facilmente riutilizzabili in altri
  222 contesti. Per ottenere la modularità, \emph{le variabili create in una funzione
  223 sono locali a quella funzione, e vengono distrutte quando la funzione termina la
  224 sua esecuzione}, a meno che esse siano rese disponibili come valori di ritorno,
  225 e che questi siano ``raccolti'' o assegnati nella chiamata della funzione.
  226 
  227 Inoltre, le funzioni non hanno accesso alle variabili dell'``ambiente esterno''
  228 (ossia le variabili che esistono nello script da cui la funzione è
  229 chiamata), a meno che queste siano passate esplicitamente alla
  230 funzione come argomenti.
  231 
  232 Nel caso predefinito, quando una variabile viene passata a una funzione come
  233 argomento, la funzione ottiene una \emph{copia} della variabile esterna, quindi il
  234 valore della variabile nell'ambiente esterno non viene modificato dalle
  235 operazioni che avvengono all'interno della funzione. Invece, l'uso dei puntatori
  236 consente a una funzione e all'ambiente di ``cooperare'' in modo
  237 che una variabile esterna possa essere modificata dalla funzione. Questo
  238 meccanismo consente a una funzione di restituire più di un valore (anche se una
  239 funzione può restituire direttamente al massimo una variabile, come spiegato in
  240 seguito).  Il parametro in questione viene contrassegnato col prefisso
  241 \texttt{*} nella definizione della funzione, mentre l'argomento corrispondente
  242 viene contrassegnato col prefisso complementare \verb+&+ nella chiamata. Ad
  243 esempio:
  244 %
  245 \begin{code}
  246 function get_uhat_and_ess(series y, list xvars, scalar *ess)
  247   ols y 0 xvars --quiet
  248   ess = $ess
  249   series uh = $uhat
  250   return series uh
  251 end function
  252 # Script principale
  253 open data4-1
  254 list xlist = 2 3 4
  255 # Chiamata di funzione
  256 scalar SSR
  257 series resid = get_uhat_and_ess(price, xlist, &SSR)
  258 \end{code}
  259 %
  260 In questo caso, alla funzione viene passato l'\emph{indirizzo} della variabile scalare
  261 \texttt{SSR} a cui viene assegnato un valore (usando il nome \texttt{ess}).
  262 Per chi ha familiarità con la programmazione in C, si noti che non è necessario
  263 (né possibile) ``dereferenziare'' la variabile in questione nella funzione
  264 usando l'operatore \texttt{*}. Per accedere al contenuto della variabile
  265 nell'ambiente esterno è sufficiente usare il nome della variabile senza
  266 prefissi.
  267 
  268 Un parametro di ``indirizzo'' di questo tipo può essere utile per offrire
  269 informazioni opzionali alla chiamata (ossia, l'argomento corrispondente non è
  270 strettamente necessario, ma sarà usato se presente). In questo caso, al
  271 parametro andrà assegnato un valore predefinito \texttt{null} e la funzione
  272 dovrebbe controllare se alla chiamata è stato fornito un argomento
  273 corrispondente, usando la funzione \texttt{isnull()}.  Ad esempio, ecco la
  274 funzione vista in precedenza, modificata in modo da rendere opzionale
  275 l'indicazione del valore di \texttt{ess}.
  276 %
  277 \begin{code}
  278 function get_uhat_and_ess(series y, list xvars, scalar *ess[null])
  279   ols y 0 xvars --quiet
  280   if !isnull(ess) 
  281      ess = $ess
  282   endif
  283   series uh = $uhat
  284   return series uh
  285 end function
  286 \end{code}
  287 %
  288 Se alla chiamata non si ha interesse per il valore di \texttt{ess}, occorre usare
  289 \texttt{null} al posto di un vero argomento:
  290 %
  291 \begin{code}
  292 series resid = get_uhat_and_ess(price, xlist, null)
  293 \end{code}
  294 
  295 Usare i puntatori può essere utile anche per ottimizzare le prestazioni:
  296 anche se una variabile non viene modificata all'interno della funzione, può
  297 essere una buona idea passarla come puntatore se occupa molta memoria.
  298 Altrimenti, il tempo impiegato da \app{gretl} per trascrivere il valore della
  299 variabile nella copia locale potrebbe influire sostanzialmente sul tempo di
  300 esecuzione dell'intera funzione.
  301 
  302 L'esempio \ref{ex:perf-pointers} mostra un caso estremo. Definiamo due funzioni
  303 che producono il numero di righe di una matrice (un'operazione abbastanza
  304 veloce). La prima funzione accetta la matrice come argomento, la seconda come
  305 puntatore alla matrice. Valutiamo le due funzioni usando una matrice con 2000
  306 righe e 2000 colonne; su un sistema tipico, i valori a virgola mobile occupano 8
  307 byte di memoria, quindi lo spazio occupato dalla matrice è di circa 32 megabyte.
  308 
  309 Eseguendo il codice dell'esempio \ref{ex:perf-pointers} verrà prodotto un
  310 risultato simile al seguente (i numeri esatti dipenderano dalla macchina su cui
  311 si esegue il codice):
  312 \begin{code}
  313 Tempo impiegato:
  314     senza puntatori (copia) = 3.66 secondi,
  315     con puntatori (non copia) = 0.01 secondi.
  316 \end{code}
  317 
  318 \begin{script}[htbp]
  319   \caption{Confronto di prestazioni: valori contro puntatori}
  320   \label{ex:perf-pointers}
  321   \begin{scode}
  322 function a(matrix X)
  323   r = rows(X)
  324   return scalar r
  325 end function
  326 
  327 function b(matrix *X)
  328   r = rows(X)
  329   return scalar r
  330 end function
  331 
  332 nulldata 10
  333 set echo off
  334 set messages off
  335 X = zeros(2000,2000)
  336 r = 0
  337 
  338 set stopwatch
  339 loop 100
  340   r = a(X)
  341 end loop
  342 fa = $stopwatch
  343 
  344 set stopwatch
  345 loop 100
  346   r = b(&X)
  347 end loop
  348 fb = $stopwatch
  349 
  350 printf "Tempo impiegato:\n\
  351 \tsenza puntatori (copia) = %g secondi,\n\
  352 \tcon puntatori (non copia) = %g secondi.\n", fa, fb 
  353 \end{scode}
  354 %$
  355 \end{script}
  356 
  357 \subsection{Argomenti lista}
  358 
  359 L'uso di una lista come argomento di una funzione dà modo di fornire a una
  360 funzione un gruppo di argomenti il cui numero non è noto al momento della scrittura della
  361 funzione, ad esempio un insieme di regressori o di strumenti. All'interno della
  362 funzione, la lista può essere passata a comandi come
  363 \texttt{ols}, oppure può essere ``espansa'' usando un costrutto loop
  364 \texttt{foreach}. Ad esempio, si supponga di avere una lista
  365 \texttt{X} e di voler calcolare lo scarto quadratico medio di ogni variabile della
  366 lista:
  367 %
  368 \begin{code}
  369 loop foreach i X
  370    scalar sd_$i = sd($i)
  371 end loop
  372 \end{code}
  373 
  374 Quando a una funzione viene passata una lista di variabili, in realtà riceve
  375 una copia della lista; al contrario, le variabili referenziate dalla lista sono
  376 direttamente accessibili dalla funzione, in modo simile a quando si passa
  377 uno scalare o una serie come ``puntatore'', come descritto in precedenza.
  378 Passare una lista a una funzione è quindi un altro modo per consentire a una
  379 funzione di modificare i dati quando questa viene chiamata, piuttosto che
  380 produrre semplicemente un valore di uscita. Se le variabili \textit{non} verranno
  381 modificate nella funzione, è una buona idea sottolineare questo fatto usando
  382 l'identificatore \texttt{const} nella lista dei parametri, come in questo
  383 esempio:
  384 %
  385 \begin{code}
  386 function funzione (scalar y, const list X)
  387 \end{code}
  388 %
  389 Quando una lista è marcata come \texttt{const}, ogni tentativo di rinominare,
  390 cancellare o sovrascrivere i valori originali delle variabili nella lista
  391 produrrà un errore.
  392  
  393 Se un argomento lista per una funzione è opzionale, esso va indicato facendolo
  394 seguire da un valore predefinito \texttt{null}, nel modo seguente:
  395 %
  396 \begin{code}
  397 function myfunc (scalar y, list X[null])
  398 \end{code}
  399 %
  400 In questo caso, se la chiamata passa \texttt{null} come argomento di lista, la
  401 lista \texttt{X} all'interno della funzione sarà vuota. Questa condizione può
  402 essere riconosciuta usando la funzione \texttt{nelem()}, che restituisce il
  403 valore 0 se una lista è vuota (questo meccanismo può essere usato anche per
  404 controllare se è stata fornita una lista vuota come argomento).
  405 
  406 \subsection{Argomenti stringa}
  407 
  408 È possibile usare stringhe come argomenti, ad esempio per gestire in
  409 modo flessibile i nomi di variabili create all'interno di una funzione.
  410 Nell'esempio che segue, la funzione \texttt{movavg} produce una lista
  411 che contiene due medie mobili costruite a partire da una serie iniziale,
  412 con i nomi delle nuove variabili formati usando l'argomento stringa.
  413 %
  414 \begin{code}
  415 function movavg (series y, string vname)
  416    series @vname_2 = (y+y(-1)) / 2
  417    series @vname_4 = (y+y(-1)+y(-2)+y(-3)) / 4
  418    list retlist = @vname_2 @vname_4
  419    return list retlist
  420 end function
  421 
  422 open data9-9
  423 list malist = movavg(nocars, "nocars")
  424 print malist --byobs
  425 \end{code}
  426 %
  427 L'ultima riga dello script stamperà due variabili chiamate
  428 \verb|nocars_2| e \verb|nocars_4|.  Per i dettagli sulla gestione delle
  429 stringhe, si veda il capitolo~\ref{chap-persist}.
  430 
  431 \subsection{Recuperare il nome degli argomenti}
  432 
  433 Le variabili passate come argomenti a una funzione vengono chiamate all'interno
  434 della funzione col nome dei parametri corrispondenti. Ad esempio, all'interno di
  435 questa funzione:
  436 %
  437 \begin{code}
  438 function somefun (series y)
  439 \end{code}
  440 %
  441 abbiamo la serie chiamata \texttt{y}. In alcuni casi può però essere utile
  442 disporre del nome delle variabili che sono state passate come argomenti.
  443 Questo risultato si ottiene usando la funzione \texttt{argname}, che accetta
  444 come unico argomento il nome di un parametro della funzione e restituisce una
  445 stringa. Ecco un esempio:
  446 %
  447 \begin{code}
  448 function namefun (series y)
  449   printf "La serie passata come 'y' si chiamava %s\n", argname(y)
  450 end function
  451 
  452 open data9-7
  453 namefun(QNC)
  454 \end{code}
  455 %
  456 L'output è il seguente:
  457 %
  458 \begin{code}
  459 La serie passata come 'y' si chiamava QNC
  460 \end{code}
  461 
  462 Occorre notare che questo meccanismo non funziona sempre: gli argomenti di una
  463 funzione possono essere variabili senza nome, create al volo, come in
  464 \texttt{somefun(log(QNC))} o \texttt{somefun(CPI/100)}.  In questo caso, la
  465 funzione \textsf{argname} produce una stringa vuota. Quando si usa questo
  466 meccanismo all'interno di una funzione occorre quindi controllare il valore
  467 prodotto da \texttt{argname} usando la funzione \texttt{isstring()}, che produce
  468 1 per una stringa non vuota, o 0 altrimenti.
  469 
  470 \subsection{Valori di uscita}
  471 
  472 Le funzioni possono non produrre alcun valore (limitandosi ad esempio
  473 a stampare un risultato), oppure possono produrre una singola variabile:
  474 una scalare, una serie, una lista o una matrice (al momento le funzioni non
  475 possono produrre stringhe).  Il valore di uscita è specificato
  476 con una dichiarazione all'interno del corpo della funzione
  477 che comincia con la parola chiave \verb+return+, seguita dall'indicatore del
  478 tipo e dal nome della variabile (in modo analogo a quanto avviene per la lista
  479 dei parametri di una funzione).  All'interno di una funzione può esserci solo
  480 una di queste dichiarazioni. Ecco un esempio di dichiarazione return valida:
  481 %
  482 \begin{code}
  483 return scalar SSR
  484 \end{code}
  485 %
  486 Per fare in modo che una funzione produca più di una variabile in uscita, è
  487 possibile farle produrre una lista, ossia è possibile definire alcune variabili
  488 all'interno della funzione e accorparle in una lista; in questo caso esse non
  489 vengono distrutte all'uscita della funzione. Ecco un semplice esempio, che
  490 illustra anche la possibilità di impostare delle etichette descrittive per le
  491 variabili generate in una funzione.
  492 %    
  493 \begin{code}
  494 function make_cubes (list xlist)
  495    list cubes = null
  496    loop foreach i xlist --quiet
  497       series $i3 = $i^3
  498       setinfo $i3 -d "cube of $i"
  499       list cubes += $i3
  500     end loop
  501     return list cubes
  502 end function
  503 
  504 open data4-1
  505 list xlist = price sqft
  506 list cubelist = make_cubes(xlist)
  507 print xlist cubelist --byobs
  508 labels
  509 \end{code}
  510 %
  511 Si noti che la dichiarazione \verb+return+ \emph{non} indica alla
  512 funzione di produrre il valore (terminare) nel punto in cui essa
  513 appare nel corpo della funzione. Piuttosto, essa specifica quale
  514 variabile è disponibile per l'assegnazione quando la funzione
  515 terminerà, cosa che può avvenire solo quando: a) viene raggiunta la
  516 fine del codice che definisce la funzione, oppure b) \app{gretl} produce
  517 un errore, o c) si incontra una dichiarazione \verb+funcerr+.
  518  
  519 La parola chiave \verb+funcerr+, che può essere seguita da una stringa
  520 contenuta fra virgolette doppie, fa terminare una funzione con un
  521 messaggio di errore. Se si fornisce una stringa, questa viene stampata
  522 all'uscita, altrimenti viene mostrato un messaggio di errore generico.
  523 Questo meccanismo consente all'autore di una funzione di anticipare un possibile
  524 errore di esecuzione e/o di offrire un messaggio di errore più specifico. Ad
  525 esempio:
  526 %
  527 \begin{code}
  528 if nelem(xlist) = 0
  529    funcerr "xlist non può essere vuota"
  530 end if
  531 \end{code}
  532 
  533 \subsection{Controllo degli errori}
  534 
  535 Quando gretl legge e ``compila'' una definizione di funzione, esegue
  536 un controllo degli errori minimale: controlla che il nome della
  537 funzione sia accettabile e che non si tenti di definire una funzione
  538 all'interno di una funzione (si veda la sezione~\ref{func-define}). Se
  539 il corpo della funzione contiene comandi non validi, verrà segnalato
  540 solo quando la funzione viene chiamata.
  541 
  542 \subsection{Stampa dei risultati}
  543 
  544 Durante l'esecuzione di una funzione, il meccanismo con cui \app{gretl} mostra i
  545 comandi e i risultati delle operazioni di creazione di nuove variabili, viene
  546 disattivato. Per riattivarlo (ad esempio se si vuole fare il debug del codice di
  547 una nuova funzione), basta usare uno dei seguenti comandi (o entrambi)
  548 all'interno nella funzione:
  549 %
  550 \begin{code}
  551 set echo on
  552 set messages on
  553 \end{code}
  554 
  555 \section{Pacchetti di funzioni}
  556 \label{sec:func-packages}
  557 
  558 A partire dalla versione 1.6.0, \app{gretl} contiene un meccanismo per creare
  559 pacchetti di funzioni e renderli disponibili agli altri utenti. Questa
  560 funzionalità è ancora sperimentale, ma è già utilizzabile seguendo
  561 le istruzioni contenute in questa sezione.
  562 
  563 \subsection{Caricamento in memoria di una funzione}
  564 
  565 Ci sono vari modi per caricare una funzione in memoria:
  566 
  567 \begin{itemize}
  568 \item Se si ha un file script che contiene definizioni di funzioni, aprendo
  569   il file ed eseguendolo;
  570 \item Creando un file script da zero, includendo almeno una definizione di
  571   funzione ed eseguendo lo script;
  572 \item Aprendo il terminale di gretl e inserendo una definizione di funzione in
  573   modalità interattiva. Questo metodo non è particolarmente raccomandato: è
  574   probabilmente più comodo definire una funzione in modalità non interattiva.
  575 \end{itemize}
  576 
  577 Ad esempio, si supponga di voler creare un pacchetto con una funzione che
  578 produce l'incremento percentuale di una serie storica. Basta aprire un file
  579 script e digitare
  580 
  581 \begin{code}
  582 function pc(series y)
  583   series foo = diff(y)/y(-1)
  584   return series foo
  585 end function
  586 \end{code}
  587 
  588 \begin{figure}[htbp]
  589   \centering
  590   \includegraphics[scale=0.5]{figures/func_check}
  591   \caption{Controllo del funzionamento di una funzione}
  592   \label{fig:func_check}
  593 \end{figure}
  594 
  595 Ora si può eseguire la funzione e controllare che funzioni correttamente,
  596 facendo alcuni test; ad esempio si può aprire il terminale e digitare:
  597 
  598 \begin{code}
  599 genr x = uniform()
  600 genr dpcx = pc(x)
  601 print x dpcx --byobs
  602 \end{code}
  603 
  604 Si dovrebbe vedere qualcosa di simile alla figura \ref{fig:func_check}. La
  605 funzione sembra essere corretta, quindi è possibile procedere al passo
  606 successivo.
  607 
  608 \subsection{Creazione di un pacchetto}
  609 
  610 Usando l'interfaccia grafica del programma, nel menù ``File, Funzioni'', si trovano
  611 quattro voci: ``Sul sistema locale'', ``Sul server di gretl'', ``Modifica
  612 pacchetto'', ``Nuovo pacchetto''.
  613 
  614 Selezionare il comando ``Nuovo pacchetto'' (il comando funziona solo quando è
  615 stata caricata in memoria almeno una funzione definita dall'utente); nella prima
  616 finestra di dialogo occorre selezionare:
  617 
  618 \begin{itemize}
  619 \item Una funzione pubblica da impacchettare;
  620 \item Zero o più funzioni ausiliarie ``private''.
  621 \end{itemize}
  622 
  623 Le funzioni pubbliche sono direttamente disponibili per gli utenti, quelle private
  624 fanno parte del meccanismo che lavora ``dietro le quinte'' in un pacchetto di funzioni.
  625 
  626 \begin{figure}[htbp]
  627   \centering
  628   \includegraphics[scale=0.5]{figures/package_editor}
  629   \caption{La finestra di modifica di un pacchetto}
  630   \label{fig:package_editor}
  631 \end{figure}
  632 
  633 Facendo clic su ``OK'' apparirà una seconda finestra di dialogo (si veda la
  634 figura \ref{fig:package_editor}), in cui occorre
  635 inserire le informazioni sul pacchetto (al momento: l'autore, la versione, la
  636 data e una breve descrizione), oltre che un testo di aiuto che descrive
  637 l'interfaccia pubblica della funzione. Si ha l'opportunità di modificare il
  638 codice delle funzioni, selezionandole dal menù e facendo clic su ``Modifica
  639 codice della funzione''.  Infine, è possibile scegliere di caricare il pacchetto
  640 sul server di gretl appena lo si salva, selezionando l'apposita casella.
  641 
  642 Facendo clic su ``OK'', si otterrà una finestra di salvataggio del file, che
  643 suggerirà di salvare il file in una directory chiamata \texttt{functions}, collocata
  644 sotto la directory di sistema di \app{gretl} (se si ha il permesso di scrittura
  645 su di essa), oppure nella directory utente di \app{gretl}. Questo è il posto
  646 suggerito per salvare i pacchetti di funzioni, visto che il programma li
  647 cercherà automaticamente qui, al momento di aprire questo tipo di file.
  648 
  649 Ovviamente, il comando ``File, Funzioni, Modifica pacchetto'' permette di
  650 modificare un pacchetto precedentemente salvato.
  651 
  652 \vspace{6pt}
  653 
  654 Qualche informazione sui file dei pacchetti di funzioni: per impostazione
  655 predefinita essi hanno l'estensione \texttt{.gfn}, e, a differenza dei file di
  656 comandi di \app{gretl}, sono file in formato XML che contengono il codice delle
  657 funzioni e le informazioni aggiunte dal creatore del pacchetto. Gli utenti
  658 esperti possono anche scrivere questi file da zero, invece di usare l'editor di
  659 pacchetti, ma la maggior parte delle persone troverà più comodo usare
  660 quest'ultimo. Si noti che i caratteri speciali XML nel codice della funzione
  661 vanno commentati, ad esempio \texttt{\&} va rappresentato come \texttt{\&}.
  662 Inoltre, alcuni elementi della sintassi delle funzioni differiscono dalla loro
  663 rappresentazione standard all'interno degli script di comandi: i parametri e i
  664 valori di uscita (se esistono) vanno rappresentati in XML. Sostanzialmente, la
  665 funzione viene analizzata e caricata in modo veloce usando la \textsf{libxml}.
  666 
  667 \vspace{6pt}
  668 
  669 \subsection{Caricamento di un pacchetto}
  670 
  671 Perché impacchettare le funzioni in questo modo? Per scoprirlo, proviamo a
  672 chiudere gretl, a riaprirlo, e ad andare nel menù ``File, Funzioni, Sul sistema
  673 locale''. Se le operazioni precedenti sono andate a buon fine, troveremo il
  674 pacchetto che avevamo creato, insieme alla sua breve descrizione. Facendo clic
  675 su ``Info'', si ottiene una finestra con tutte le informazioni disponibili sul
  676 pacchetto; facendo clic sull'icona ``Visualizza codice'' della barra degli
  677 strumenti di questa nuova finestra, si aprirà una finestra che mostra il codice
  678 delle funzioni contenute nel pacchetto. Tornando alla finestra ``Pacchetti funzioni'',
  679 facendo clic sul nome di un pacchetto, le funzioni verranno caricate, pronte per
  680 essere eseguite, usando il pulsante ``Chiama''.
  681 
  682 Dopo aver caricato le funzioni contenute nel pacchetto, aprendo il terminale di
  683 gretl, sarà possibile richiamare il testo di aiuto relativo ad una delle nuove
  684 funzioni caricate, se esso esiste, con il comando \texttt{help funzione},
  685 dove \texttt{funzione} è il nome della funzione pubblica del pacchetto caricato.
  686 
  687 In modo simile, è possibile consultare e caricare i pacchetti di funzioni
  688 disponibili sul server di \app{gretl}, selezionando ``File, Funzioni, Sul server
  689 di gretl''.
  690 
  691 Una volta che un pacchetto è installato sulla macchina locale, è possibile usare
  692 le funzioni contenute attraverso l'interfaccia grafica, come descritto sopra, o
  693 quella a riga di comando (in uno script o nel terminale), caricando la funzione
  694 con il comando \texttt{include} e specificando come argomento il nome del
  695 pacchetto, compresa l'estensione \texttt{.gfn}.
  696 
  697 \begin{figure}[htbp]
  698   \centering
  699   \includegraphics[scale=0.5]{figures/function_call}
  700   \caption{Uso di un pacchetto}
  701   \label{fig:function_call}
  702 \end{figure}
  703 
  704 Per continuare con l'esempio, caricare il file \texttt{np.gdt} (uno dei dataset
  705 di esempio forniti con \app{gretl}). Si supponga di voler calcolare il tasso di
  706 crescita per la variabile \texttt{iprod} usando la funzione appena creata e di
  707 salvare il risultato in una serie chiamata \texttt{pippo}.
  708 
  709 Basta selezionare ``File, Funzioni, Sul sistema locale'' e comparirà un elenco
  710 dei pacchetti installati, compreso quello appena creato. Selezionandolo e
  711 facendo clic su ``Esegui'' (o facendo doppio clic sul nome del pacchetto),
  712 apparirà una finestra simile a quella della figura \ref{fig:function_call}.
  713 Facendo clic su ``Ok'', la serie \texttt{pippo} verrà generata (si veda la
  714 figura \ref{fig:iprod_pc}). Per fare in modo che la nuova variabile compaia
  715 nell'elenco delle variabili nella finestra principale, può essere necessario
  716 usare il comando ``Dati, Aggiorna finestra'' (o semplicemente premere il tasto
  717 ``r'').
  718 
  719 \begin{figure}[htbp]
  720   \centering
  721   \includegraphics[scale=0.5]{figures/iprod_pc}
  722   \caption{Incremento percentuale della produzione industriale}
  723   \label{fig:iprod_pc}
  724 \end{figure}
  725 
  726 In alternativa, lo stesso risultato si ottiene con lo script
  727 \begin{code}
  728 include pc.gfn
  729 open np
  730 pippo = pc(iprod)
  731 \end{code}
  732 
  733 %%% Local Variables: 
  734 %%% mode: latex
  735 %%% TeX-master: "gretl-guide-it"
  736 %%% End: 
  737