Mercurial > hg > octave-nkf
changeset 6641:27ec13d8499b
[project @ 2007-05-21 19:53:58 by jwe]
author | jwe |
---|---|
date | Mon, 21 May 2007 19:53:58 +0000 |
parents | 379244420c72 |
children | ffee6a1a10f3 |
files | doc/ChangeLog doc/interpreter/eval.txi |
diffstat | 2 files changed, 106 insertions(+), 10 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,5 +1,9 @@ 2007-05-21 Søren Hauberg <hauberg@gmail.com> + * interpreter/eval.txi: Partition the chapter into sections. + Describe evalin and assignin functions using text from Paul + Kienzle. + * interpreter/func.txi: New section describing load path. Improve 'inline' and 'command' sections.
--- a/doc/interpreter/eval.txi +++ b/doc/interpreter/eval.txi @@ -10,18 +10,28 @@ a file. Sometimes, you may find it necessary to evaluate an expression that has -been computed and stored in a string, or use a string as the name of a -function to call. The @code{eval} and @code{feval} functions allow you -to do just that, and are necessary in order to evaluate commands that -are not known until run time, or to write functions that will need to -call user-supplied functions. +been computed and stored in a string, which is exactly what the +@code{eval} lets you do. @DOCSTRING(eval) -@DOCSTRING(feval) +@menu +* Calling a Function by its Name:: +* Evaluation in a Different Context:: +@end menu + +@node Calling a Function by its Name +@section Calling a Function by its Name -Here is a simple-minded function using @code{feval} that finds the root -of a user-supplied function of one variable using Newton's method. +The @code{feval} function allow you to call a function from a string +containing its name. This is useful when writing a function that need to +call user-supplied functions. The @code{feval} function takes the name +of the function to call as its first argument, and the remaining +arguments are given to the function. + +The following example is a simple-minded function using @code{feval} +that finds the root of a user-supplied function of one variable using +Newton's method. @example @group @@ -59,10 +69,92 @@ functions and should not be taken too seriously. In addition to using a more robust algorithm, any serious code would check the number and type of all the arguments, ensure that the supplied function really was a -function, etc. See @xref{Predicates for Numeric Objects}, for example, -for a list of predicates for numeric objects, and @xref{Status of +function, etc. @xref{Predicates for Numeric Objects}, for example, +for a list of predicates for numeric objects, and see @ref{Status of Variables}, for a description of the @code{exist} function. +@DOCSTRING(feval) + +@node Evaluation in a Different Context +@section Evaluation in a Different Context + +Before you evaluate an expression you need to substitute +the values of the variables used in the expression. These +are stored in the symbol table. Whenever the interpreter +starts a new function it saves the current symbol table +and creates a new one, initializing it with the list of +function parameters and a couple of predefined variables +such as @code{nargin}. Expressions inside the function use the +new symbol table. + +Sometimes you want to write a function so that when you +call it, it modifies variables in your own context. This +allows you to use a pass-by-name style of function, +which is similar to using a pointer in programming languages such +as C. + +Consider how you might write @code{save} and @code{load} as +m-files. For example, + +@example +function create_data + x = linspace (0, 10, 10); + y = sin (x); + save mydata x y +endfunction +@end example + +With @code{evalin}, you could write save as follows: + +@example +function save (file, name1, name2) + f = open_save_file (file); + save_var(f, name1, evalin ("caller", name1)); + save_var(f, name2, evalin ("caller", name2)); +endfunction +@end example + +@noindent +Here, @samp{caller} is the @code{create_data} function and @code{name1} +is the string @code{"x"}, which evaluates simply as the value of @code{x}. + +You later want to load the values back from @code{mydata} +in a different context: + +@example +function process_data + load mydata + @dots{} do work @dots{} +endfunction +@end example + +@noindent +With @code{assignin}, you could write @code{load} as follows: + +@example +function load (file) + f = open_load_file (file); + [name, val] = load_var (f); + assignin ("caller", name, val); + [name, val] = load_var (f); + assignin ("caller", name, val); +endfunction +@end example + +@noindent +Here, @samp{caller} is the @code{process_data} function. + +You can set and use variables at the command prompt +using the context @samp{base} rather than @samp{caller}. + +These functions are rarely used in practice. One +example is the @code{fail (@samp{code}, @samp{pattern})} function +which evaluates @samp{code} in the caller's context and +checks that the error message it produces matches +the given pattern. Other examples such as @code{save} and @code{load} +are written in C++ where all octave variables +are in the @samp{caller} context and @code{evalin} is not needed. + @DOCSTRING(evalin) @DOCSTRING(assignin)