"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{)} \\
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