1@c Copyright (C) 1996-2019 John W. Eaton
2@c
3@c This file is part of Octave.
4@c
5@c Octave is free software: you can redistribute it and/or modify it
6@c under the terms of the GNU General Public License as published by
7@c the Free Software Foundation, either version 3 of the License, or
8@c (at your option) any later version.
9@c
10@c Octave is distributed in the hope that it will be useful, but
11@c WITHOUT ANY WARRANTY; without even the implied warranty of
12@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13@c GNU General Public License for more details.
14@c
15@c You should have received a copy of the GNU General Public License
16@c along with Octave; see the file COPYING.  If not, see
17@c <https://www.gnu.org/licenses/>.
18
19@node Evaluation
20@chapter Evaluation
21
22Normally, you evaluate expressions simply by typing them at the Octave
23prompt, or by asking Octave to interpret commands that you have saved in
24a file.
25
26Sometimes, you may find it necessary to evaluate an expression that has
27been computed and stored in a string, which is exactly what the
28@code{eval} function lets you do.
29
30@DOCSTRING(eval)
31
32The @code{evalc} function additionally captures any console output
33produced by the evaluated expression.
34
35@DOCSTRING(evalc)
36
37@menu
38* Calling a Function by its Name::
39* Evaluation in a Different Context::
40@end menu
41
42@node Calling a Function by its Name
43@section Calling a Function by its Name
44
45The @code{feval} function allows you to call a function from a string
46containing its name.  This is useful when writing a function that needs to
47call user-supplied functions.  The @code{feval} function takes the name
48of the function to call as its first argument, and the remaining
49arguments are given to the function.
50
51The following example is a simple-minded function using @code{feval}
52that finds the root of a user-supplied function of one variable using
53Newton's method.
54
55@example
56function result = newtroot (fname, x)
57
58# usage: newtroot (fname, x)
59#
60#   fname : a string naming a function f(x).
61#   x     : initial guess
62
63  delta = tol = sqrt (eps);
64  maxit = 200;
65  fx = feval (fname, x);
66  for i = 1:maxit
67    if (abs (fx) < tol)
68      result = x;
69      return;
70    else
71      fx_new = feval (fname, x + delta);
72      deriv = (fx_new - fx) / delta;
73      x = x - fx / deriv;
74      fx = fx_new;
75    endif
76  endfor
77
78  result = x;
79
80endfunction
81@end example
82
83Note that this is only meant to be an example of calling user-supplied
84functions and should not be taken too seriously.  In addition to using a
85more robust algorithm, any serious code would check the number and type
86of all the arguments, ensure that the supplied function really was a
87function, etc.  @xref{Predicates for Numeric Objects},
88for a list of predicates for numeric objects, and @pxref{Status of
89Variables}, for a description of the @code{exist} function.
90
91@DOCSTRING(feval)
92
93A similar function @code{run} exists for calling user script files, that
94are not necessarily on the user path
95
96@DOCSTRING(run)
97
98@node Evaluation in a Different Context
99@section Evaluation in a Different Context
100
101Before you evaluate an expression you need to substitute
102the values of the variables used in the expression.  These
103are stored in the symbol table.  Whenever the interpreter
104starts a new function it saves the current symbol table
105and creates a new one, initializing it with the list of
106function parameters and a couple of predefined variables
107such as @code{nargin}.  Expressions inside the function use the
108new symbol table.
109
110Sometimes you want to write a function so that when you
111call it, it modifies variables in your own context.  This
112allows you to use a pass-by-name style of function,
113which is similar to using a pointer in programming languages such
114as C.
115
116Consider how you might write @code{save} and @code{load} as
117m-files.  For example:
118
119@example
120@group
121function create_data
122  x = linspace (0, 10, 10);
123  y = sin (x);
124  save mydata x y
125endfunction
126@end group
127@end example
128
129With @code{evalin}, you could write @code{save} as follows:
130
131@example
132@group
133function save (file, name1, name2)
134  f = open_save_file (file);
135  save_var (f, name1, evalin ("caller", name1));
136  save_var (f, name2, evalin ("caller", name2));
137endfunction
138@end group
139@end example
140
141@noindent
142Here, @samp{caller} is the @code{create_data} function and @code{name1}
143is the string @qcode{"x"}, which evaluates simply as the value of @code{x}.
144
145You later want to load the values back from @code{mydata}
146in a different context:
147
148@example
149@group
150function process_data
151  load mydata
152  @dots{} do work @dots{}
153endfunction
154@end group
155@end example
156
157@noindent
158With @code{assignin}, you could write @code{load} as follows:
159
160@example
161@group
162function load (file)
163  f = open_load_file (file);
164  [name, val] = load_var (f);
165  assignin ("caller", name, val);
166  [name, val] = load_var (f);
167  assignin ("caller", name, val);
168endfunction
169@end group
170@end example
171
172@noindent
173Here, @samp{caller} is the @code{process_data} function.
174
175You can set and use variables at the command prompt
176using the context @samp{base} rather than @samp{caller}.
177
178These functions are rarely used in practice.  One
179example is the @code{fail (@samp{code}, @samp{pattern})} function
180which evaluates @samp{code} in the caller's context and
181checks that the error message it produces matches
182the given pattern.  Other examples such as @code{save} and @code{load}
183are written in C++ where all Octave variables
184are in the @samp{caller} context and @code{evalin} is not needed.
185
186@DOCSTRING(evalin)
187
188@DOCSTRING(assignin)
189