Mercurial > octave
view doc/doxyhtml/pages/macros.dox @ 33661:4c378dd47cf2 default tip @
command-widget: Use new signal-slot syntax for better compiler diagnostics.
* libgui/src/command-widget.cc (console::console): Use new signal-slot syntax
for better compiler diagnostics.
author | Markus Mützel <markus.muetzel@gmx.de> |
---|---|
date | Wed, 12 Jun 2024 17:24:20 +0200 |
parents | 7aa4d8c049e5 |
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) ``` **/