Mercurial > jwe > octave
view doc/doxyhtml/pages/macros.dox @ 29973:7aa4d8c049e5
eliminate obsolete DEFCONSTFUN and DEFCONSTMETHOD macros
For some time now, DEFCONSTFUN and DEFCONSTMETHOD have been equivalent
to DEFUN and DEFMETHOD so we might as well eliminate them. For now we
will eliminate all handling of them in Octave but leave them as
aliases in defun.h.
* macros.dox: Don't mention DEFCONSTFUN or DEFCONSTMETHOD.
* defun.h (DEFCONSTFUN, DEFCONSTMETHOD): Define as direct aliases of
DEFUN and DEFMETHOD but eliminate documentation for them.
* mk-builtins.pl, mk-doc.pl: Don't handle DEFCONSTFUN or DEFCONSTMETHOD.
* pt-eval.cc (Fend): Define with DEFMETHOD instead of DEFCONSTMETHOD.
author | John W. Eaton <jwe@octave.org> |
---|---|
date | Sun, 15 Aug 2021 15:15:55 -0400 |
parents | b7e5486e7bff |
children |
line wrap: on
line source
/** @page Macros Important Macros @tableofcontents Builtin function and method definition {#macros_defun} ====================================== In Octave a function is called from the interpreter by for example [a, b, c] = foo (d, e); If `foo` should be defined as **builtin function**, it has to have the type `octave_builtin::fcn` or equivalently: ```{.cc} octave_value_list Ffoo (const octave_value_list& args_name, int nargout_name) ``` > Notice the **F** prefix of `foo`! Basically, an `octave_value_list` goes in (referenced within that function by `args_name`) and another `octave_value_list` comes out. The integer `nargout_name` indicates, how many outputs arguments the caller of this functions expects. Thus in the example above, `d` and `e` are available via `args_name` and `nargout_name` takes the value `3`, because three output arguments `a`, `b`, and `c` are expected. Very similar to builtin functions are **builtin methods**. Builtin methods have to have the type `octave_builtin::meth` or equivalently: ```{.cc} octave_value_list Ffoo (octave::interpreter& interp_name, const octave_value_list& args_name, int nargout_name) ``` Notice again the `F` prefix of `foo`. > The difference between builtin functions and builtin methods is, that builtin > methods have access to the `octave::interpreter`, which is referenced by > `interp_name`. To make a builtin function or builtin method available to the interpreter, it is not sufficient to just define them somewhere inside `libinterp`. Octave provides two convenience macros, to define them properly: ```{.cc} DEFUN (foo, args_name, nargout_name, doc) DEFMETHOD (foo, interp_name, args_name, nargout_name, doc) ``` > For a usage example, see the definition of `#Feig`. The last argument of both macros `doc` will not appear in the builtin function or builtin method definition but is further processed. The idea is, that code and documentation should be at one place. The macros #DEFUN or #DEFMETHOD fulfill two tasks: 1. Proper builtin function or builtin method definition. 2. Defining a fixed pattern for further processing by - `mk-builtins.pl` (installation on `octave::symbol_table`) - `mk-doc.pl` (docstring `doc` extraction for the help system) In addition to #DEFUN and #DEFMETHOD, there are two specialized versions of both macros, that should only be used with reason: If the name `foo` cannot be used directly (for example if it is already defined as a macro), one can use instead one of ```{.cc} DEFUNX ("foo", Ffoo, args_name, nargout_name, doc) DEFMETHODX ("foo", Ffoo, interp_name, args_name, nargout_name, doc) ``` where `"foo"` is the name for the interpreter, protected by macro expansion inside a string, and `Ffoo` is the actual builtin function or builtin method name. Last but not least, there is #DEFALIAS. As the name suggests, this macro can be used to define an alias for an existing builtin function. Dynamic builtin function and method definition {#macros_defun_dld} ============================================== When making use of the [OCT-file interface][OCT], it is desired to define functions or methods, than can be loaded dynamically at run time, e.g. those are not loaded at Octave startup. [OCT]: https://www.gnu.org/software/octave/doc/interpreter/Oct_002dFiles.html To achieve this, analog to #DEFUN and #DEFMETHOD, there are: ```{.cc} DEFUN_DLD (name, args_name, nargout_name, doc) DEFMETHOD_DLD (name, interp_name, args_name, nargout_name, doc) ``` **/