Mercurial > jwe > octave
changeset 24510:a2569d574ae5
Add a help entry and documentation for @ character (bug #52771).
expr.txi: Add sub-node "Access via Handle" to the "Calling Functions" node.
Don't indent a paragraph that refers to the previous example. Provide the
body for the "Access via Handle" node and include an '@' opindex entry
qualified by "function handle". Mention that '@' is also used for class
methods and reference the "Object Oriented Programming" chapter.
oop.txi: Add an opindex reference to '@' qualified by "class methods" so a
quick index link is created.
op-kw-docs: Create an operator index entry for '@'. Mention that '@' is also
used for class methods and suggest seeing the "Object Oriented Programming"
chapter of the manual.
octave.texi: Add sub-node "Access via Handle" to sub-menu list.
author | Daniel J Sebald <daniel.sebald@ieee.org> |
---|---|
date | Tue, 02 Jan 2018 15:29:10 -0600 |
parents | d8ed90ecd4fd |
children | 3fc1c8ebe5c3 |
files | doc/interpreter/expr.txi doc/interpreter/octave.texi doc/interpreter/oop.txi libinterp/op-kw-docs |
diffstat | 4 files changed, 70 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/expr.txi Wed Jan 03 22:30:54 2018 -0800 +++ b/doc/interpreter/expr.txi Tue Jan 02 15:29:10 2018 -0600 @@ -388,6 +388,7 @@ @menu * Call by Value:: * Recursion:: +* Access via Handle:: @end menu @node Call by Value @@ -483,6 +484,7 @@ @end group @end example +@noindent This function is recursive because it calls itself directly. It eventually terminates because each time it calls itself, it uses an argument that is one less than was used for the previous call. Once the @@ -494,6 +496,52 @@ @DOCSTRING(max_recursion_depth) +@node Access via Handle +@subsection Access via Handle +@cindex function handle +@cindex indirect function call + +@opindex @@ function handle +A function may be abstracted and referenced via a function handle acquired +using the special operator @samp{@@}. For example, + +@example +@group +f = @@plus; +f (2, 2) +@result{} 4 +@end group +@end example + +@noindent +is equivalent to calling @code{plus (2, 2)} directly. Beyond abstraction for +general programming, function handles find use in callback methods for figures +and graphics by adding listeners to properties or assigning pre-existing +actions, such as in the following example: + +@cindex figure deletefcn +@example +@group +function mydeletefcn (h, ~, msg) + printf (msg); +endfunction +sombrero; +set (gcf, "deletefcn", @{@@mydeletefcn, "Bye!\n"@}); +close; +@end group +@end example + +@noindent +The above will print "Bye!" to the terminal upon the closing (deleting) of the +figure. There are many graphics property actions for which a callback function +may be assigned, including, @code{buttondownfcn}, @code{windowscrollwheelfcn}, +@code{createfcn}, @code{deletefcn}, @code{keypressfcn}, etc. + +Note that the @samp{@@} character also plays a role in defining class +functions, i.e., methods, but not as a syntactical element. Rather it begins a +directory name containing methods for a class that shares the directory name +sans the @samp{@@} character. See @ref{Object Oriented Programming}. + @node Arithmetic Ops @section Arithmetic Operators @cindex arithmetic operators
--- a/doc/interpreter/octave.texi Wed Jan 03 22:30:54 2018 -0800 +++ b/doc/interpreter/octave.texi Tue Jan 02 15:29:10 2018 -0600 @@ -359,6 +359,7 @@ * Call by Value:: * Recursion:: +* Access via Handle:: Boolean Expressions
--- a/doc/interpreter/oop.txi Wed Jan 03 22:30:54 2018 -0800 +++ b/doc/interpreter/oop.txi Tue Jan 02 15:29:10 2018 -0600 @@ -81,6 +81,7 @@ a = [a0, a1, a2, @dots{}, an]; @end example +@opindex @@ class methods This is a sufficient specification to begin writing the constructor for the polynomial class. All object oriented classes in Octave must be located in a directory that is the name of the class prepended with the @samp{@@} symbol.
--- a/libinterp/op-kw-docs Wed Jan 03 22:30:54 2018 -0800 +++ b/libinterp/op-kw-docs Tue Jan 02 15:29:10 2018 -0600 @@ -383,6 +383,26 @@ Logical 'or' (with short-circuit evaluation) operator. @seealso{|, or} @end deftypefn +@ +@c libinterp/parse-tree/oct-parse.in.yy +-*- texinfo -*- +@deftypefn {} {} @@ +Return handle to a function. + +Example: + +@example +@group +f = @@plus; +f (2, 2) +@result{} 4 +@end group +@end example + +(Note: @@ also finds use in creating classes. See manual chapter titled +Object Oriented Programming for detailed description.) +@seealso{function, functions, func2str, str2func} +@end deftypefn break @c libinterp/parse-tree/oct-parse.in.yy -*- texinfo -*-