Important Macros

Table of Contents

• Builtin function and method definition
• Dynamic builtin function and method definition

Builtin function and method definition

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:

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:

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:

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:

1. If the name foo cannot be used directly (for example if it is already defined as a macro), one can use instead one of

   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.
2. In case foo may not be hidden by a variable, defined in an Octave interpreter session, one can use instead one of

   DEFCONSTFUN    (foo,              args_name, nargout_name, doc)
   DEFCONSTMETHOD (foo, interp_name, args_name, nargout_name, doc)

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

When making use of the OCT-file interface, 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.

To achieve this, analog to DEFUN and DEFMETHOD, there are:

DEFUN_DLD     (name,              args_name, nargout_name, doc)
DEFMETHOD_DLD (name, interp_name, args_name, nargout_name, doc)