"Fossies" - the Fresh Open Source Software Archive

Member "gretl-2020e/doc/tex/functions.tex" (17 May 2020, 31452 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{User-defined functions}
    2 \label{chap:functions}
    3 
    4 \section{Defining a function}
    5 \label{func-define}
    6 
    7 Gretl offers a mechanism for defining functions, which may be
    8 called via the command line, in the context of a script, or (if
    9 packaged appropriately, see section~\ref{sec:func-packages}) via the
   10 program's graphical interface.
   11 
   12 The syntax for defining a function looks like this:
   13 
   14 \begin{raggedright}
   15 \texttt{function} \textsl{type} \textsl{funcname}
   16 \texttt{(}\textsl{parameters}\texttt{)} \\
   17 \qquad  \textsl{function body} \\
   18 \texttt{end function}
   19 \end{raggedright}
   20 
   21 The opening line of a function definition contains these elements, in
   22 strict order:
   23 
   24 \begin{enumerate}
   25 \item The keyword \texttt{function}.
   26 \item \textsl{type}, which states the type of value returned by the
   27   function, if any.  This must be one of \texttt{void} (if the
   28   function does not return anything), \texttt{scalar},
   29   \texttt{series}, \texttt{matrix}, \texttt{list}, \texttt{string},
   30   \texttt{bundle} or one of gretl's array types, \texttt{matrices},
   31   \texttt{bundles}, \texttt{strings} (see section~\ref{sec:arrays}).
   32 \item \textsl{funcname}, the unique identifier for the function.
   33   Function names have a maximum length of 31 characters; they must
   34   start with a letter and can contain only letters, numerals and the
   35   underscore character.  You will get an error if you try to define a
   36   function having the same name as an existing gretl command.
   37 \item The function's \textsl{parameters}, in the form of a
   38   comma-separated list enclosed in parentheses.  This may be run into
   39   the function name, or separated by white space as shown.  In case
   40   the function takes no arguments (unusual, but acceptable) this
   41   should be indicated by placing the keyword \texttt{void} between
   42   the parameter-list parentheses.
   43 \end{enumerate}
   44 
   45 Function parameters can be of any of the types shown
   46 below.\footnote{An additional parameter type is available for GUI use,
   47   namely \texttt{obs}; this is equivalent to \texttt{int} except for
   48   the way it is represented in the graphical interface for calling a
   49   function.}
   50 
   51 \begin{center}
   52 \begin{tabular}{ll}
   53 \multicolumn{1}{c}{Type} & 
   54 \multicolumn{1}{c}{Description} \\ [4pt]
   55 \texttt{bool}   & scalar variable acting as a Boolean switch \\
   56 \texttt{int}    & scalar variable acting as an integer  \\
   57 \texttt{scalar} & scalar variable \\
   58 \texttt{series} & data series \\
   59 \texttt{list}   & named list of series \\
   60 \texttt{matrix} & matrix or vector \\
   61 \texttt{string} & string variable or string literal \\
   62 \texttt{bundle} & all-purpose container (see
   63                   section~\ref{sec:Bundles}) \\
   64 \texttt{matrices} & array of matrices (see
   65                     section~\ref{sec:arrays}) \\
   66 \texttt{bundles}  & array of bundles \\
   67 \texttt{strings}  & array of strings
   68 \end{tabular}
   69 \end{center}
   70 
   71 Each element in the listing of parameters must include two terms: a
   72 type specifier, and the name by which the parameter shall be known
   73 within the function.  An example follows:
   74 %    
   75 \begin{code}
   76 function scalar myfunc (series y, list xvars, bool verbose)
   77 \end{code}
   78 
   79 Each of the type-specifiers, with the exception of \texttt{list} and
   80 \texttt{string}, may be modified by prepending an asterisk to the
   81 associated parameter name, as in
   82 %    
   83 \begin{code}
   84 function scalar myfunc (series *y, scalar *b)
   85 \end{code}
   86 
   87 The meaning of this modification is explained below (see section
   88 \ref{sec:funscope}); it is related to the use of pointer arguments in
   89 the C programming language.
   90 
   91 \subsection{Function parameters: optional refinements}
   92 
   93 Besides the required elements mentioned above, the specification of a
   94 function parameter may include some additional fields, as follows:
   95 \begin{itemize}
   96 \item The \texttt{const} modifier.
   97 \item For \texttt{scalar} or \texttt{int} parameters: minimum, maximum
   98   and/or default values; or for \texttt{bool} parameters, just a
   99   default value.
  100 \item For optional arguments other than \texttt{scalar}, \texttt{int}
  101   and \texttt{bool}, the special default value \texttt{null}.
  102 \item For all parameters, a descriptive string.
  103 \item For \texttt{int} parameters with minimum and maximum values
  104   specified, a set of strings to associate with the allowed numerical
  105   values (value labels).
  106 \end{itemize}
  107 
  108 The first three of these options may be useful in many contexts; the
  109 last two may be helpful if a function is to be packaged for use in
  110 the gretl GUI (but probably not otherwise). We now expand on
  111 each of the options.
  112 
  113 \begin{itemize}
  114 
  115 \item The \texttt{const} modifier: must be given as a prefix to the
  116   basic parameter specification, as in
  117 %    
  118 \begin{code}
  119 const matrix M
  120 \end{code} 
  121 %
  122   This constitutes a promise that the corresponding argument will not
  123   be modified within the function; gretl will flag an error if the
  124   function attempts to modify the argument.
  125 
  126 \item Minimum, maximum and default values for \texttt{scalar} or
  127   \texttt{int} types: These values should directly follow the name of
  128   the parameter, enclosed in square brackets and with the individual
  129   elements separated by colons.  For example, suppose we have an
  130   integer parameter \texttt{order} for which we wish to specify a
  131   minimum of 1, a maximum of 12, and a default of 4.  We can write
  132 %    
  133 \begin{code}
  134 int order[1:12:4]
  135 \end{code} 
  136 %
  137   If you wish to omit any of the three specifiers, leave the
  138   corresponding field empty.  For example \texttt{[1::4]} would
  139   specify a minimum of 1 and a default of 4 while leaving the maximum
  140   unlimited. However, as a special case, it is acceptable to give just
  141   one value, with no colons, in which case the value is interpreted as
  142   a default. So for example
  143 %    
  144 \begin{code}
  145 int k[0]
  146 \end{code}
  147 %
  148   designates a default value of 0 for the parameter \texttt{k}, with
  149   no minimum or maximum specified. If you wished to specify a minimum
  150   of zero with no maximum or default you would have to write
  151 %    
  152 \begin{code}
  153 int k[0::]
  154 \end{code}
  155 
  156   For a parameter of type \texttt{bool} (whose values are just zero or
  157   non-zero), you can specify a default of 1 (true) or 0 (false), as in
  158 %    
  159 \begin{code}
  160 bool verbose[0]
  161 \end{code} 
  162 
  163 \item Descriptive string: This will show up as an aid to the user if
  164   the function is packaged (see section~\ref{sec:func-packages} below)
  165   and called via gretl's graphical interface.  The string should
  166   be enclosed in double quotes and separated from the preceding
  167   elements of the parameter specification with a space, as in
  168 %
  169 \begin{code}
  170 series y "dependent variable"
  171 \end{code} 
  172 
  173 \item Value labels: These may be used only with \texttt{int}
  174   parameters for which minimum and maximum values have been specified
  175   (so that there is a fixed number of admissible values) and the
  176   number of labels must match the number of values. They will show up
  177   in the graphical interface in the form of a drop-down list, making
  178   the function writer's intent clearer when an integer argument
  179   represents a categorical selection. A set of value labels must be
  180   enclosed in braces, and the individual labels must be enclosed in
  181   double quotes and separated by commas or spaces.  For example:
  182 %
  183 \begin{code}
  184 int case[1:3:1] {"Fixed effects", "Between model", "Random effects"}
  185 \end{code} 
  186 
  187 \end{itemize}
  188 
  189 If two or more of the trailing optional fields are given in a
  190 parameter specification, they must be given in the order shown above:
  191 min/max/default, description, value labels. Note that there is no
  192 facility for ``escaping'' characters within descriptive strings or
  193 value labels; these may contain spaces but they cannot contain the
  194 double-quote character.
  195 
  196 Here is an example of a well-formed function specification using all
  197 the elements mentioned above:
  198 %
  199 \begin{code}
  200 function matrix myfunc (series y "dependent variable",
  201                         list X "regressors",
  202                         int p[0::1] "lag order",
  203                         int c[1:2:1] "criterion" {"AIC", "BIC"},
  204                         bool quiet[0])
  205 \end{code} 
  206 
  207 One advantage of specifying default values for parameters, where
  208 applicable, is that in script or command-line mode users may omit
  209 trailing arguments that have defaults. For example, \texttt{myfunc}
  210 above could be invoked with just two arguments, corresponding to
  211 \texttt{y} and \texttt{X}; implicitly \texttt{p} = 1, \texttt{c} = 1
  212 and \texttt{quiet} is false.
  213 
  214 \subsection{Functions taking no parameters}
  215 
  216 You may define a function that has no parameters (these are called
  217 ``routines'' in some programming languages).  In this case,  
  218 use the keyword \texttt{void} in place of the listing of parameters:
  219 %    
  220 \begin{code}
  221 function matrix myfunc2 (void)
  222 \end{code}
  223 
  224 
  225 \subsection{The function body}
  226    
  227 The \textsl{function body} is composed of gretl commands, or
  228 calls to user-defined functions (that is, function calls may be
  229 nested).  A function may call itself (that is, functions may be
  230 recursive). While the function body may contain function calls, it may
  231 not contain function definitions.  That is, you cannot define a
  232 function inside another function.  For further details, see
  233 section~\ref{func-details}.
  234 
  235 
  236 \section{Calling a function}
  237 \label{func-call}
  238 
  239 A user function is called by typing its name followed by zero or more
  240 arguments enclosed in parentheses.  If there are two or more arguments
  241 they must be separated by commas.
  242 
  243 There are automatic checks in place to ensure that the number of
  244 arguments given in a function call matches the number of parameters,
  245 and that the types of the given arguments match the types specified in
  246 the definition of the function.  An error is flagged if either of
  247 these conditions is violated.  One qualification: allowance is made
  248 for omitting arguments at the end of the list, provided that default
  249 values are specified in the function definition.  To be precise, the
  250 check is that the number of arguments is at least equal to the number
  251 of \textit{required} parameters, and is no greater than the total
  252 number of parameters.
  253 
  254 In general, an argument to a function may be given either as the name
  255 of a pre-existing variable or as an expression which evaluates to a
  256 variable of the appropriate type.
  257 
  258 The following trivial example illustrates a function call that
  259 correctly matches the corresponding function definition.
  260     
  261 \begin{code}
  262 # function definition
  263 function scalar ols_ess (series y, list xvars)
  264   ols y 0 xvars --quiet
  265   printf "ESS = %g\n", $ess
  266   return $ess
  267 end function
  268 
  269 # main script
  270 open data4-1
  271 list xlist = 2 3 4
  272 # function call (the return value is ignored here)
  273 ols_ess(price, xlist)
  274 \end{code}
  275 %$
  276 The function call gives two arguments: the first is a data series
  277 specified by name and the second is a named list of regressors.  Note
  278 that while the function offers the Error Sum of Squares as a return
  279 value, it is ignored by the caller in this instance.  (As a side note
  280 here, if you want a function to calculate some value having to do with
  281 a regression, but are not interested in the full results of the
  282 regression, you may wish to use the \option{quiet} flag with the
  283 estimation command as shown above.)
  284     
  285 A second example shows how to write a function call that assigns
  286 a return value to a variable in the caller:
  287     
  288 \begin{code}
  289 # function definition
  290 function series get_uhat (series y, list xvars)
  291   ols y 0 xvars --quiet
  292   return $uhat
  293 end function
  294 
  295 # main script
  296 open data4-1
  297 list xlist = 2 3 4
  298 # function call
  299 series resid = get_uhat(price, xlist)
  300 \end{code}
  301 %$
  302 \section{Deleting a function}
  303 \label{func-del}
  304 
  305 If you have defined a function and subsequently wish to clear it out
  306 of memory, you can do so using the keywords \texttt{delete} or
  307 \texttt{clear}, as in
  308 
  309 \begin{code}
  310 function myfunc delete
  311 function get_uhat clear
  312 \end{code}
  313 
  314 Note, however, that if \texttt{myfunc} is already a defined function,
  315 providing a new definition automatically overwrites the previous one,
  316 so it should rarely be necessary to delete functions explicitly.
  317 
  318 \section{Function programming details}
  319 \label{func-details}
  320 
  321 \subsection{Variables versus pointers}
  322 \label{sec:funscope}
  323 
  324 Most arguments to functions can be passed in two ways: ``as they
  325 are'', or via pointers (the exception is the list type, which cannot
  326 be passed as a pointer). First consider the following rather
  327 artificial example:
  328 \begin{code}
  329 function series triple1 (series x)
  330   return 3*x
  331 end function
  332   
  333 function void triple2 (series *x)
  334   x *= 3
  335 end function
  336 
  337 nulldata 10
  338 series y = normal()
  339 series y3 = triple1(y)
  340 print y3
  341 triple2(&y)
  342 print y
  343 \end{code}
  344 
  345 These two functions produce essentially the same result---the two
  346 \texttt{print} statements in the caller will show the same
  347 values---but in quite different ways. The first explicitly returns a
  348 modified version of its input (which must be a plain series): after
  349 the call to \texttt{triple1}, \texttt{y} is unaltered; it would have
  350 been altered only if the return value were assigned back to \texttt{y}
  351 rather than \texttt{y3}. The second function modifies its input (given
  352 as a pointer to a series) in place without actually \textit{returning}
  353 anything.
  354 
  355 It's worth noting that \texttt{triple2} as it stands would
  356 \textit{not} be considered idiomatic as a gretl function (although
  357 it's formally OK). The point here is just to illustrate the
  358 distinction between passing an argument in the default way and in
  359 pointer form.
  360 
  361 Why make this distinction? There are two main reasons for doing so:
  362 modularity and performance.
  363 
  364 By modularity we mean the insulation of a function from the rest of
  365 the script which calls it.  One of the many benefits of this approach
  366 is that your functions are easily reusable in other contexts.  To
  367 achieve modularity, \emph{variables created within a function are
  368   local to that function, and are destroyed when the function exits},
  369 unless they are made available as return values and these values are
  370 ``picked up'' or assigned by the caller.  In addition, functions do
  371 not have access to variables in ``outer scope'' (that is, variables
  372 that exist in the script from which the function is called) except
  373 insofar as these are explicitly passed to the function as arguments.
  374 
  375 By default, when a variable is passed to a function as an argument,
  376 what the function actually ``gets'' is a \emph{copy} of the outer
  377 variable, which means that the value of the outer variable is not
  378 modified by anything that goes on inside the function. This means that
  379 you can pass arguments to a function without worrying about possible
  380 side effects; at the same time the function writer can use argument
  381 variables as workspace without fear of disruptive effects at the level
  382 of the caller.
  383 
  384 The use of pointers, however, allows a function and its caller to
  385 cooperate such that an outer variable \textit{can} be modified by the
  386 function.  In effect, this allows a function to ``return'' more than
  387 one value (although only one variable can be returned directly---see
  388 below).  To indicate that a particular object is to be passed as a
  389 pointer, the parameter in question is marked with a prefix of
  390 \texttt{*} in the function definition, and the corresponding argument
  391 is marked with the complementary prefix \verb+&+ in the caller.  For
  392 example,
  393 %
  394 \begin{code}
  395 function series get_uhat_and_ess(series y, list xvars, scalar *ess)
  396   ols y 0 xvars --quiet
  397   ess = $ess
  398   series uh = $uhat
  399   return uh
  400 end function
  401 
  402 open data4-1
  403 list xlist = 2 3 4
  404 scalar SSR
  405 series resid = get_uhat_and_ess(price, xlist, &SSR)
  406 \end{code}
  407 %
  408 In the above, we may say that the function is given the \emph{address}
  409 of the scalar variable \texttt{SSR}, and it assigns a value to that
  410 variable (under the local name \texttt{ess}).  (For anyone used to
  411 programming in \textsf{C}: note that it is not necessary, or even
  412 possible, to ``dereference'' the variable in question within the
  413 function using the \texttt{*} operator.  Unadorned use of the name of
  414 the variable is sufficient to access the variable in outer scope.)
  415 
  416 An ``address'' parameter of this sort can be used as a means of
  417 offering optional information to the caller.  (That is, the
  418 corresponding argument is not strictly needed, but will be used if
  419 present).  In that case the parameter should be given a default value
  420 of \texttt{null} and the the function should test to see if the caller
  421 supplied a corresponding argument or not, using the built-in function
  422 \texttt{exists()}.  For example, here is the simple function shown
  423 above, modified to make the filling out of the \texttt{ess} value
  424 optional.
  425 %
  426 \begin{code}
  427 function series get_uhat_and_ess(series y, list xvars, scalar *ess[null])
  428   ols y 0 xvars --quiet
  429   if exists(ess) 
  430      ess = $ess
  431   endif
  432   return $uhat
  433 end function
  434 \end{code}
  435 %
  436 If the caller does not care to get the \texttt{ess} value, it can
  437 use \texttt{null} in place of a real argument:
  438 %
  439 \begin{code}
  440 series resid = get_uhat_and_ess(price, xlist, null)
  441 \end{code}
  442 %
  443 Alternatively, trailing function arguments that have default values 
  444 may be omitted, so the following would also be a valid call:
  445 %
  446 \begin{code}
  447 series resid = get_uhat_and_ess(price, xlist)
  448 \end{code}
  449 
  450 One limitation on the use of pointer-type arguments should be noted:
  451 you cannot supply a given variable as a pointer argument more than
  452 once in any given function call. For example, suppose we have a
  453 function that takes two matrix-pointer arguments,
  454 \begin{code}
  455 function scalar pointfunc (matrix *a, matrix *b)
  456 \end{code}
  457 And suppose we have two matrices, \texttt{x} and \texttt{y}, at the
  458 caller level.  The call
  459 \begin{code}
  460 pointfunc(&x, &y)
  461 \end{code}
  462 is OK, but the call
  463 \begin{code}
  464 pointfunc(&x, &x) # will not work
  465 \end{code}
  466 will generate an error. That's because the situation inside the
  467 function would become too confusing, with what is really the same
  468 object existing under two names.
  469 
  470 \subsection{Const parameters}
  471 \label{sec:const-args}
  472 
  473 Pointer-type arguments may also be useful for optimizing performance.
  474 Even if a variable is not modified inside the function, it may be a
  475 good idea to pass it as a pointer if it occupies a lot of
  476 memory. Otherwise, the time gretl spends transcribing the value of the
  477 variable to the local copy may be non-negligible compared to the time
  478 the function spends doing the job it was written for.
  479 
  480 Listing \ref{ex:perf-pointers} takes this to the extreme.  We define
  481 two functions which return the number of rows of a matrix (a pretty
  482 fast operation).  The first gets a matrix as argument while the second
  483 gets a pointer to a matrix.  The functions are evaluated 500 times on
  484 a matrix with 2000 rows and 2000 columns; on a typical system
  485 floating-point numbers take 8 bytes of memory, so the total size of
  486 the matrix is roughly 32 megabytes.
  487 
  488 Running the code in example \ref{ex:perf-pointers} will produce output
  489 similar to the following (the actual numbers of course depend on the
  490 machine you're using):
  491 \begin{code}
  492 Elapsed time:
  493 without pointers (copy) = 2.47197 seconds,
  494 with pointers (no copy) = 0.00378627 seconds
  495 \end{code}
  496 
  497 \begin{script}[htbp]
  498   \caption{Performance comparison: values versus pointer}
  499   \label{ex:perf-pointers}
  500   \begin{scode}
  501 function scalar rowcount1 (matrix X)
  502   return rows(X)
  503 end function
  504 
  505 function scalar rowcount2 (const matrix *X)
  506   return rows(X)
  507 end function
  508 
  509 set verbose off
  510 X = zeros(2000,2000)
  511 scalar r
  512 
  513 set stopwatch
  514 loop 500
  515   r = rowcount1(X)
  516 endloop
  517 e1 = $stopwatch
  518 
  519 set stopwatch
  520 loop 500
  521   r = rowcount2(&X)
  522 endloop
  523 e2 = $stopwatch
  524 
  525 printf "Elapsed time:\n\
  526 without pointers (copy) = %g seconds,\n \
  527 with pointers (no copy) = %g seconds\n", e1, e2
  528 \end{scode}
  529 %$
  530 \end{script}
  531 
  532 If a pointer argument is used for this sort of purpose---and the
  533 object to which the pointer points is not modified (is treated as
  534 read-only) by the function---one can signal this to the user by adding
  535 the \texttt{const} qualifier, as shown for function \texttt{rowcount2}
  536 in Listing~\ref{ex:perf-pointers}.  When a pointer argument is
  537 qualified in this way, any attempt to modify the object within the
  538 function will generate an error.
  539 
  540 However, combining the \texttt{const} flag with the pointer mechanism
  541 is technically redundant for the following reason: if you mark a
  542 matrix argument as \texttt{const} then gretl will in fact pass it in
  543 pointer mode internally (since it can't be modified within the
  544 function there's no downside to simply making it available to the
  545 function rather than copying it). So in the example above we could
  546 revise the signature of the second function as
  547 \begin{code}
  548 function scalar rowcount2a (const matrix X)
  549 \end{code}
  550 and call it with \texttt{r = rowcount2a(X)}, for the same speed-up
  551 relative to \texttt{rowcount1}.
  552 
  553 From the caller's point of view the second option---using the
  554 \texttt{const} modifier \textit{without} pointer notation---is
  555 preferable, as it allows the caller to pass an object created ``on the
  556 fly''. Suppose the caller has two matrices, \texttt{A} and \texttt{B},
  557 in scope, and wishes to pass their vertical concatenation as an
  558 argument. The following call would work fine:
  559 \begin{code}
  560 r = rowcount2a(A|B)
  561 \end{code}
  562 To use \texttt{rowcount2}, on the other hand, the caller would have to
  563 create a named variable first (since you cannot give the ``address''
  564 of a anonymous object such as \verb+A|B+):
  565 \begin{code}
  566 matrix AB = A|B
  567 r = rowcount2(&AB)
  568 \end{code}
  569 This requires an extra line of code, and leaves \texttt{AB} occupying
  570 memory after the call.
  571 
  572 We have illustrated using a matrix parameter, but the \texttt{const}
  573 modifier may be used with the same effect---namely, the argument is
  574 passed directly, without being copied, but is protected against
  575 modification within the function---for all the types that support
  576 the pointer apparatus.
  577 
  578 \subsection{List arguments}
  579 
  580 The use of a named list as an argument to a function gives a means of
  581 supplying a function with a set of variables whose number is unknown
  582 when the function is written---for example, sets of regressors or
  583 instruments.  Within the function, the list can be passed on to
  584 commands such as \texttt{ols}.
  585 
  586 A list argument can also be ``unpacked'' using a \texttt{foreach} loop
  587 construct, but this requires some care.  For example, suppose you have
  588 a list \texttt{X} and want to calculate the standard deviation of each
  589 variable in the list.  You can do:
  590 %
  591 \begin{code}
  592 loop foreach i X
  593    scalar sd_$i = sd(X.$i)
  594 endloop
  595 \end{code}
  596 
  597 \textit{Please note}: a special piece of syntax is needed in this
  598 context.  If we wanted to perform the above task on a list in a
  599 regular script (not inside a function), we could do
  600 %
  601 \begin{code}
  602 loop foreach i X
  603    scalar sd_$i = sd($i)
  604 endloop
  605 \end{code}
  606 %
  607 where \dollar{i} gets the name of the variable at position $i$ in the
  608 list, and \verb|sd($i)| gets its standard deviation.  But inside a
  609 function, working on a list supplied as an argument, if we want to
  610 reference an individual variable in the list we must use the syntax
  611 \textsl{listname.varname}.  Hence in the example above we write
  612 \verb|sd(X.$i)|.
  613 
  614 This is necessary to avoid possible collisions between the name-space
  615 of the function and the name-space of the caller script.  For example,
  616 suppose we have a function that takes a list argument, and that
  617 defines a local variable called \texttt{y}.  Now suppose that this
  618 function is passed a list containing a variable named \texttt{y}.  If
  619 the two name-spaces were not separated either we'd get an error, or
  620 the external variable \texttt{y} would be silently over-written by the
  621 local one.  It is important, therefore, that list-argument variables
  622 should not be ``visible'' by name within functions.  To ``get hold
  623 of'' such variables you need to use the form of identification just
  624 mentioned: the name of the list, followed by a dot, followed by the
  625 name of the variable.
  626 
  627 \paragraph{Constancy of list arguments} When a named list of
  628 variables is passed to a function, the function is actually provided
  629 with a copy of the list.  The function may modify this copy (for
  630 instance, adding or removing members), but the original list at the
  631 level of the caller is not modified.
  632 
  633 \paragraph{Optional list arguments} If a list argument to a function is
  634 optional, this should be indicated by appending a default value of
  635 \texttt{null}, as in
  636 %
  637 \begin{code}
  638 function scalar myfunc (scalar y, list X[null])
  639 \end{code}
  640 %
  641 In that case, if the caller gives \texttt{null} as the list argument
  642 (or simply omits the last argument) the named list \texttt{X} inside the
  643 function will be empty.  This possibility can be detected using the
  644 \texttt{nelem()} function, which returns 0 for an empty list.
  645 
  646 \subsection{String arguments}
  647 
  648 String arguments can be used, for example, to provide flexibility in
  649 the naming of variables created within a function.  In the following
  650 example the function \texttt{mavg} returns a list containing two
  651 moving averages constructed from an input series, with the names of
  652 the newly created variables governed by the string argument.
  653 %
  654 \begin{code}
  655 function list mavg (series y, string vname)
  656    list retlist = null
  657    string newname = sprintf("%s_2", vname)
  658    retlist += genseries(newname, (y+y(-1)) / 2)
  659    newname = sprintf("%s_4", vname)
  660    retlist += genseries(newname, (y+y(-1)+y(-2)+y(-3)) / 4)
  661    return retlist
  662 end function
  663 
  664 open data9-9
  665 list malist = mavg(nocars, "nocars")
  666 print malist --byobs
  667 \end{code}
  668 %
  669 The last line of the script will print two variables named
  670 \verb|nocars_2| and \verb|nocars_4|.  For details on the handling of
  671 named strings, see chapter~\ref{chap:lists-strings}.
  672 
  673 If a string argument is considered optional, it may be given a
  674 \texttt{null} default value, as in
  675 %
  676 \begin{code}
  677 function scalar foo (series y, string vname[null])
  678 \end{code}
  679 
  680 \subsection{Retrieving the names of arguments}
  681 
  682 The variables given as arguments to a function are known inside the
  683 function by the names of the corresponding parameters.  For example,
  684 within the function whose signature is
  685 %
  686 \begin{code}
  687 function void somefun (series y)
  688 \end{code}
  689 %
  690 we have the series known as \texttt{y}.  It may be useful, however, to
  691 be able to determine the names of the variables provided as arguments.
  692 This can be done using the function \texttt{argname}, which takes the
  693 name of a function parameter as its single argument and returns a
  694 string.  Here is a simple illustration:
  695 %
  696 \begin{code}
  697 function void namefun (series y)
  698   printf "the series given as 'y' was named %s\n", argname(y)
  699 end function
  700 
  701 open data9-7
  702 namefun(QNC)
  703 \end{code}
  704 %
  705 This produces the output
  706 %
  707 \begin{code}
  708 the series given as 'y' was named QNC
  709 \end{code}
  710 
  711 Please note that this will not always work: the arguments given
  712 to functions may be anonymous variables, created on the fly, as in
  713 \texttt{somefun(log(QNC))} or \texttt{somefun(CPI/100)}.  In that case
  714 the \textsf{argname} function returns an empty string.  Function
  715 writers who wish to make use of this facility should check the return
  716 from \texttt{argname} using the \texttt{strlen()} function: if this
  717 returns 0, no name was found.
  718 
  719 \subsection{Return values}
  720 
  721 Functions can return nothing (just printing a result, perhaps), or
  722 they can return a single variable.  The return value, if any, is
  723 specified via a statement within the function body beginning with the
  724 keyword \texttt{return}, followed by either the name of a variable
  725 (which must be of the type announced on the first line of the function
  726 definition) or an expression which produces a value of the correct
  727 type.
  728 
  729 Having a function return a list or bundle is a way of permitting the
  730 ``return'' of more than one variable.  For example, you can define
  731 several series inside a function and package them as a list; in this
  732 case they are not destroyed when the function exits.  Here is a simple
  733 example, which also illustrates the possibility of setting the
  734 descriptive labels for variables generated in a function.
  735 %    
  736 \begin{code}
  737 function list make_cubes (list xlist)
  738    list cubes = null
  739    loop foreach i xlist
  740       series $i3 = (xlist.$i)^3
  741       setinfo $i3 -d "cube of $i"
  742       list cubes += $i3
  743    endloop
  744    return cubes
  745 end function
  746 
  747 open data4-1
  748 list xlist = price sqft
  749 list cubelist = make_cubes(xlist)
  750 print xlist cubelist --byobs
  751 labels
  752 \end{code}
  753 %$
  754 
  755 A \texttt{return} statement causes the function to return (exit) at
  756 the point where it appears within the body of the function.  A
  757 function may also exit when (a) the end of the function code is
  758 reached (in the case of a function with no return value), (b) a
  759 gretl error occurs, or (c) a \verb+funcerr+ statement is
  760 reached.
  761 
  762 The \verb+funcerr+ keyword---which may be followed by a string
  763 enclosed in double quotes, or the name of a string variable, or
  764 nothing---causes a function to exit with an error flagged.  If a
  765 string is provided (either literally or via a variable), this is
  766 printed on exit, otherwise a generic error message is printed.  This
  767 mechanism enables the author of a function to pre-empt an ordinary
  768 execution error and/or offer a more specific and helpful error
  769 message.  For example,
  770 %
  771 \begin{code}
  772 if nelem(xlist) == 0
  773    funcerr "xlist must not be empty"
  774 endif
  775 \end{code}
  776 
  777 A function may contain more than one \texttt{return} statement, as in
  778 %
  779 \begin{code}
  780 function scalar multi (bool s)
  781    if s
  782       return 1000
  783    else
  784       return 10
  785    endif
  786 end function
  787 \end{code}
  788 %
  789 However, it is recommended programming practice to have a single
  790 return point from a function unless this is very inconvenient.  The
  791 simple example above would be better written as
  792 %
  793 \begin{code}
  794 function scalar multi (bool s)
  795    return s ? 1000 : 10
  796 end function
  797 \end{code}
  798     
  799 
  800 \subsection{Error checking}
  801 
  802 When gretl first reads and ``compiles'' a function definition there is
  803 minimal error-checking: the only checks are that the function name is
  804 acceptable, and, so far as the body is concerned, that you are not
  805 trying to define a function inside a function (see Section
  806 \ref{func-define}). Otherwise, if the function body contains invalid
  807 commands this will become apparent only when the function is called
  808 and its commands are executed.
  809 
  810 \subsection{Debugging}
  811 
  812 The usual mechanism whereby gretl echoes commands and reports on
  813 the creation of new variables is by default suppressed when a function
  814 is being executed.  If you want more verbose output from a particular
  815 function you can use either or both of the following commands within
  816 the function:
  817 %
  818 \begin{code}
  819 set echo on
  820 set messages on
  821 \end{code}
  822 
  823 Alternatively, you can achieve this effect for all functions via
  824 the command \texttt{set debug 1}.  Usually when you set the value of a
  825 state variable using the \texttt{set} command, the effect applies only
  826 to the current level of function execution.  For instance, if you do
  827 \texttt{set messages on} within function \texttt{f1}, which in turn
  828 calls function \texttt{f2}, then messages will be printed for
  829 \texttt{f1} but not \texttt{f2}.  The debug variable, however, acts
  830 globally; all functions become verbose regardless of their level.
  831 
  832 Further, you can do \texttt{set debug 2}: in addition to command echo
  833 and the printing of messages, this is equivalent to setting
  834 \verb|max_verbose| (which produces verbose output from the BFGS
  835 maximizer) at all levels of function execution.
  836 
  837 \section{Function packages}
  838 \label{sec:func-packages}
  839 
  840 At various points above we have alluded to function packages, and the
  841 use of these via the gretl GUI. This topic is covered in depth by the
  842 \PKGBOOK. If you're running gretl you can find this under the
  843 \textsf{Help} menu. Alternatively you may download it from
  844 
  845 \url{https://sourceforge.net/projects/gretl/files/manual/}
  846 
  847 %%% Local Variables: 
  848 %%% mode: latex
  849 %%% TeX-master: "gretl-guide"
  850 %%% End: 
  851