Mercurial > octave
annotate doc/interpreter/eval.txi @ 30564:796f54d4ddbf stable
update Octave Project Developers copyright for the new year
In files that have the "Octave Project Developers" copyright notice,
update for 2021.
In all .txi and .texi files except gpl.txi and gpl.texi in the
doc/liboctave and doc/interpreter directories, change the copyright
to "Octave Project Developers", the same as used for other source
files. Update copyright notices for 2022 (not done since 2019). For
gpl.txi and gpl.texi, change the copyright notice to be "Free Software
Foundation, Inc." and leave the date at 2007 only because this file
only contains the text of the GPL, not anything created by the Octave
Project Developers.
Add Paul Thomas to contributors.in.
| author | John W. Eaton <jwe@octave.org> |
|---|---|
| date | Tue, 28 Dec 2021 18:22:40 -0500 |
| parents | 00f796120a6d |
| children | 597f3ee61a48 |
| rev | line source |
|---|---|
|
30564
796f54d4ddbf
update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents:
26376
diff
changeset
|
1 @c Copyright (C) 1996-2022 The Octave Project Developers |
| 7018 | 2 @c |
| 3 @c This file is part of Octave. | |
| 4 @c | |
|
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
5 @c Octave is free software: you can redistribute it and/or modify it |
|
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
6 @c under the terms of the GNU General Public License as published by |
|
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
7 @c the Free Software Foundation, either version 3 of the License, or |
|
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
8 @c (at your option) any later version. |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
9 @c |
|
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
10 @c Octave is distributed in the hope that it will be useful, but |
|
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
11 @c WITHOUT ANY WARRANTY; without even the implied warranty of |
|
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
12 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
|
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
13 @c GNU General Public License for more details. |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
14 @c |
| 7018 | 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 | |
|
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
17 @c <https://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 |
|
21075
5ed379c8decd
Add new function evalc to core.
Oliver Heimlich <oheim@posteo.de>
parents:
19697
diff
changeset
|
32 The @code{evalc} function additionally captures any console output |
|
5ed379c8decd
Add new function evalc to core.
Oliver Heimlich <oheim@posteo.de>
parents:
19697
diff
changeset
|
33 produced by the evaluated expression. |
|
5ed379c8decd
Add new function evalc to core.
Oliver Heimlich <oheim@posteo.de>
parents:
19697
diff
changeset
|
34 |
|
5ed379c8decd
Add new function evalc to core.
Oliver Heimlich <oheim@posteo.de>
parents:
19697
diff
changeset
|
35 @DOCSTRING(evalc) |
|
5ed379c8decd
Add new function evalc to core.
Oliver Heimlich <oheim@posteo.de>
parents:
19697
diff
changeset
|
36 |
| 6641 | 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 | |
| 3294 | 44 |
| 7001 | 45 The @code{feval} function allows you to call a function from a string |
|
9037
4cb9f994dcec
Documentation cleanup of var.texi, expr.texi, eval.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
46 containing its name. This is useful when writing a function that needs to |
|
4cb9f994dcec
Documentation cleanup of var.texi, expr.texi, eval.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
47 call user-supplied functions. The @code{feval} function takes the name |
|
19593
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
48 of the function to call as its first argument, and the remaining |
| 6641 | 49 arguments are given to the function. |
| 50 | |
| 51 The following example is a simple-minded function using @code{feval} | |
| 52 that finds the root of a user-supplied function of one variable using | |
| 53 Newton's method. | |
| 3294 | 54 |
| 55 @example | |
| 56 function 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 | |
| 80 endfunction | |
| 81 @end example | |
| 82 | |
| 83 Note that this is only meant to be an example of calling user-supplied | |
| 84 functions and should not be taken too seriously. In addition to using a | |
| 85 more robust algorithm, any serious code would check the number and type | |
| 86 of all the arguments, ensure that the supplied function really was a | |
|
17097
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
14856
diff
changeset
|
87 function, etc. @xref{Predicates for Numeric Objects}, |
|
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
14856
diff
changeset
|
88 for a list of predicates for numeric objects, and @pxref{Status of |
| 3294 | 89 Variables}, for a description of the @code{exist} function. |
| 6549 | 90 |
| 6641 | 91 @DOCSTRING(feval) |
| 92 | |
| 6863 | 93 A similar function @code{run} exists for calling user script files, that |
| 94 are not necessarily on the user path | |
| 95 | |
| 96 @DOCSTRING(run) | |
| 97 | |
| 6641 | 98 @node Evaluation in a Different Context |
| 99 @section Evaluation in a Different Context | |
| 100 | |
| 101 Before you evaluate an expression you need to substitute | |
| 102 the values of the variables used in the expression. These | |
| 103 are stored in the symbol table. Whenever the interpreter | |
| 104 starts a new function it saves the current symbol table | |
| 105 and creates a new one, initializing it with the list of | |
| 106 function parameters and a couple of predefined variables | |
| 107 such as @code{nargin}. Expressions inside the function use the | |
| 108 new symbol table. | |
| 109 | |
| 110 Sometimes you want to write a function so that when you | |
| 111 call it, it modifies variables in your own context. This | |
| 112 allows you to use a pass-by-name style of function, | |
| 113 which is similar to using a pointer in programming languages such | |
| 114 as C. | |
| 115 | |
| 116 Consider how you might write @code{save} and @code{load} as | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
9209
diff
changeset
|
117 m-files. For example: |
| 6641 | 118 |
| 119 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
120 @group |
| 6641 | 121 function create_data |
| 122 x = linspace (0, 10, 10); | |
| 123 y = sin (x); | |
| 124 save mydata x y | |
| 125 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
126 @end group |
| 6641 | 127 @end example |
| 128 | |
| 8828 | 129 With @code{evalin}, you could write @code{save} as follows: |
| 6641 | 130 |
| 131 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
132 @group |
| 6641 | 133 function save (file, name1, name2) |
| 134 f = open_save_file (file); | |
|
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
135 save_var (f, name1, evalin ("caller", name1)); |
|
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
136 save_var (f, name2, evalin ("caller", name2)); |
| 6641 | 137 endfunction |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
138 @end group |
| 6641 | 139 @end example |
| 140 | |
| 141 @noindent | |
| 142 Here, @samp{caller} is the @code{create_data} function and @code{name1} | |
|
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
143 is the string @qcode{"x"}, which evaluates simply as the value of @code{x}. |
| 6641 | 144 |
| 145 You later want to load the values back from @code{mydata} | |
| 146 in a different context: | |
| 147 | |
| 148 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
149 @group |
| 6641 | 150 function process_data |
| 151 load mydata | |
| 152 @dots{} do work @dots{} | |
| 153 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
154 @end group |
| 6641 | 155 @end example |
| 156 | |
| 157 @noindent | |
| 158 With @code{assignin}, you could write @code{load} as follows: | |
| 159 | |
| 160 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
161 @group |
| 6641 | 162 function 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); | |
| 168 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
169 @end group |
| 6641 | 170 @end example |
| 171 | |
| 172 @noindent | |
| 173 Here, @samp{caller} is the @code{process_data} function. | |
| 174 | |
| 175 You can set and use variables at the command prompt | |
| 176 using the context @samp{base} rather than @samp{caller}. | |
| 177 | |
| 178 These functions are rarely used in practice. One | |
| 179 example is the @code{fail (@samp{code}, @samp{pattern})} function | |
| 180 which evaluates @samp{code} in the caller's context and | |
| 181 checks that the error message it produces matches | |
| 182 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
|
183 are written in C++ where all Octave variables |
| 6641 | 184 are in the @samp{caller} context and @code{evalin} is not needed. |
| 185 | |
| 6549 | 186 @DOCSTRING(evalin) |
| 187 | |
| 188 @DOCSTRING(assignin) |