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