\chapter{Named lists and strings}
\label{chap-persist}

%%% Should this chapter deal with saving models too?

\section{Named lists}
\label{named-lists}

Many \app{gretl} commands take one or more lists of variables as
arguments.  To make this easier to handle in the context of command
scripts, and in particular within user-defined functions, \app{gretl}
offers the possibility of \textit{named lists}.  

\subsection{Creating and modifying named lists}

A named list is created using the keyword \texttt{list}, followed by
the name of the list, an equals sign, and either \texttt{null} (to
create an empty list) or one or more variables to be placed on the
list.  For example,
%
\begin{code}
list xlist = 1 2 3 4
list reglist = income price 
list empty_list = null
\end{code}

The name of the list must start with a letter, and must be composed
entirely of letters, numbers or the underscore character.  The maximum
length of the name is 15 characters; list names cannot contain
spaces.  When adding variables to a list, you can refer to them either
by name or by their ID numbers. 

Once a named list has been created, it will be ``remembered'' for the
duration of the \app{gretl} session, and can be used in the context of
any \app{gretl} command where a list of variables is expected.  One
simple example is the specification of a list of regressors:
%
\begin{code}
list xlist = x1 x2 x3 x4
ols y 0 xlist
\end{code}

Lists can be modified in two ways.  To \textit{redefine} an existing
list altogether, use the same syntax as for creating a list.  For
example
%
\begin{code}
list xlist = 1 2 3
list xlist = 4 5 6
\end{code}

After the second assignment, \texttt{xlist} contains just variables 4,
5 and 6.

To \textit{append} or \textit{prepend} variables to an existing list,
we simply make use of the fact that a named list can stand in for a
``longhand'' list.  For example, we can do
%
\begin{code}
list xlist = xlist 5 6 7
list xlist = 9 10 xlist 11 12
\end{code}

\subsection{Querying a list}

You can determine whether an unknown variable actually represents a list
using the function \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}

The first \texttt{genr} command above will assign a value of 1 to
\texttt{is1} since \texttt{xlogs} is in fact a named list.  The second
genr will assign 0 to \texttt{is2} since \texttt{xl1} is a data
series, not a list.  

You can also determine the number of variables or elements in a list
using the function \texttt{nelem()}.
%
\begin{code}
list xlist = 1 2 3
genr nl = nelem(xlist)
\end{code}

The scalar \texttt{nl} will be assigned a value of 3 since
\texttt{xlist} contains 3 members.

You can display the membership of a named list as illustrated in this
interactive session:
%
\begin{code}
? list xlist = x1 x2 x3
Added list 'xlist'
? list xlist print
 xlist: x1 x2 x3
\end{code}
%
Note that \texttt{print xlist} will do something different, namely
print the values of all the variables in \texttt{xlist} (as should be
expected).

\subsection{Generating lists of transformed variables}

Given a named list of variables, you are able to generate lists of
transformations of these variables using a special form of the
commands \texttt{logs}, \texttt{lags}, \texttt{diff}, \texttt{ldiff},
\texttt{sdiff} or \texttt{square}.  In this context these keywords
must be followed directly by a named list in parentheses.  For example
%
\begin{code}
list xlist = x1 x2 x3
list lxlist = logs(xlist)
list difflist = diff(xlist)
\end{code}

When generating a list of \textit{lags} in this way, you can specify
the maximum lag order inside the parentheses, before the list name and
separated by a comma.  For example
%
\begin{code}
list xlist = x1 x2 x3
list laglist = lags(2, xlist)
\end{code}
%
or
%
\begin{code}
scalar order = 4
list laglist = lags(order, xlist)
\end{code}

These command will populate \texttt{laglist} with the specified number
of lags of the variables in \texttt{xlist}.  (As with the ordinary
\texttt{lags} command, you can omit the order, in which case this is
determined automatically based on the frequency of the data.)  One
further special feature is available when generating lags, namely, you
can give the name of a single variable in place of a named list on the
right-hand side, as in
%
\begin{code}
series lx = log(x)
list laglist = lags(4, lx)
\end{code}

Note that the ordinary syntax for, e.g., \texttt{logs}, is just
%
\begin{code}
logs x1 x2 x3
\end{code}
%
If \texttt{xlist} is a named list, you can also say
%
\begin{code}
logs xlist
\end{code}
%
but this form will not save the logs as a named list; for that you
need the form
%
\begin{code}
list loglist = logs(xlist)
\end{code}


\subsection{Checking for missing values}

\app{Gretl} offers several functions for recognizing and handling
missing values (see the \GCR{} for details). In this context it is
worth remarking that the \texttt{ok()} function can be used with a
list argument.  For example,
%
\begin{code}
list xlist = x1 x2 x3
series xok = ok(xlist)
\end{code}
%
After these commands, the series \texttt{xok} will have value 1 for
observations where none of \texttt{x1}, \texttt{x2}, or
\texttt{x3} has a missing value, and value 0 for any observations
where this condition is not met.


\section{Named strings}
\label{named-strings}

For some purposes it may be useful to save a string (that is, a
sequence of characters) as a named variable that can be reused.
Versions of \app{gretl} higher than 1.6.0 offer this facility, but
some of the refinements noted below are available only in \app{gretl}
1.6.3 and higher.

To \textit{define} a string variable, you can use either of two
commands, \texttt{string} or \texttt{sprintf}.  The \texttt{string}
command is simpler: you just type, for example,
%
\begin{code}
string foo = "some stuff I want to save"
\end{code}
%
The first field after \texttt{string} is the name under which the
string should be saved, then comes an equals sign, then comes the
string to be saved, enclosed in double quotes.  The latter can be
represented as a sequence of sub-strings if need be, as in
%
\begin{code}
string bits = "first " "and" " second"
\end{code}
%
See below for further variants of the string command, including use of
\texttt{getenv}.  

The \texttt{sprintf} command is more flexible.  It works exactly as
\app{gretl}'s \texttt{printf} command except that the ``format''
string must be preceded by the name of a string variable.  For
example,
%
\begin{code}
scalar x = 8
sprintf foo "var%d", x
\end{code}

To \textit{retrieve the value} of a string variable, you give the name
of the variable preceded by the ``at'' sign, \verb|@|.  

In most contexts, the \verb|@| notation is treated as a ``macro''.
That is, if a sequence of characters in a \app{gretl} command
following the symbol \verb|@| is recognized as the name of a string
variable, the value of that variable is sustituted literally into the
command line before the regular parsing of the command is
carried out.  This is illustrated in the following interactive
session:
%
\begin{code}
? scalar x = 8
 scalar x = 8
Generated scalar x (ID 2) = 8
? sprintf foo "var%d", x
Saved string as 'foo'
? print "@foo"
var8
\end{code}
%
Note the effect of the quotation marks in the line 
\verb|print "@foo"|.  The line
%
\begin{code}
? print @foo
\end{code}
%
would \textit{not} print a literal ``\texttt{var8}'' as above.  After
pre-processing the line would read
%
\begin{code}
print var8
\end{code}
%
It would therefore print the value(s) of the variable \texttt{var8},
if such a variable exists, or would generate an error otherwise.

In certain specific contexts, however, it is natural to treat
\verb|@|-variables as variables in their own right, and \app{gretl}
does so.  These contexts are:
\begin{itemize}
\item When they appear among the arguments to the commands \texttt{printf} and
  \texttt{sprintf}.
\item On the right-hand side of a \texttt{string} assignment.
\item When they appear as an argument to the function
  \texttt{isstring} (see below).
\end{itemize}

Here is an illustration of the use of named string arguments with
\texttt{printf}:
%
\begin{code}
? string vstr = "variance"
Saved string as 'vstr'
? printf "vstr: %12s\n", @vstr
vstr:     variance
\end{code}
%
Note that \verb|@vstr| should not be put in quotes in this context.
Similarly with
\begin{code}
? string copy = @vstr
\end{code}

\subsection{Built-in strings}

Apart from any strings that the user may define, some string variables
are defined by \app{gretl} itself.  These may be useful for people
writing functions that include shell commands.  The built-in strings
are as shown in Table~\ref{tab-strings}.

\begin{table}[htbp]
\centering
\begin{tabular}{ll}
  \verb|@gretldir| & the \app{gretl} installation directory \\
  \verb|@userdir| & user's \app{gretl} directory \\
  \verb|@gnuplot| & path to, or name of, the \app{gnuplot} executable \\
  \verb|@tramo|& path to, or name of, the \app{tramo} executable \\
  \verb|@x12a| & path to, or name of, the \app{x-12-arima} executable \\
  \verb|@tramodir| & \app{tramo} data directory \\
  \verb|@x12adir| & \app{x-12-arima} data directory \\
\end{tabular}
\caption{Built-in string variables}
\label{tab-strings}
\end{table}

\subsection{Reading strings from the environment}

In addition, it is possible to read into \app{gretl}'s named strings,
values that are defined in the external environment.  To do this you
use the function \texttt{getenv}, which takes the name of an environment
variable as its argument.  For example:
%
\begin{code}
? string user = getenv("USER")
Saved string as 'user'
? string home = getenv("HOME")
Saved string as 'home'
? print "@user's home directory is @home"
cottrell's home directory is /home/cottrell
\end{code}
%
To check whether you got a non-empty value from a given call to
\texttt{getenv}, you can use the function \texttt{isstring}, as in
%
\begin{code}
? string temp = getenv("TEMP")
Saved empty string as 'temp'
? scalar x = isstring(@temp)
Generated scalar x (ID 2) = 0
\end{code}
%
Note that \texttt{isstring} is really shorthand for ``is a string that
actually contains something''.  

At present the \texttt{getenv} function can only be used on the
right-hand side of a \texttt{string} assignment, as in the above
illustrations.
    
%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "gretl-guide"
%%% End: