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