function blocks

The function command signals the definition of a here-document containing a named block of gnuplot code that can be called as a function. As with data blocks, the name of a function block must begin with a '$'. Up to nine named parameters may be specified as part of the definition. These names may be used inside the function block as local variables. See local and scope.

Once the function block is defined, you can invoke it by name anywhere that a normal function could be used. If the return value is not relevant, the function block may be invoked by an "evaluate" command rather than as part of an assignment expression.

Example:

     function $sinc(arg) << EOF
         if (arg == 0) { return 1.0 }
         return sin(arg) / arg
     EOF

     gnuplot> plot $sinc(x) with lines title "sinc(x) as a function block"

It is not necessary to specify a list of named arguments to a function block at the time it is declared. The number and values of arguments to the function passed from the command line can be be accessed from inside the function block as an integer variable ARGC and a corresponding array ARGV[ARGC]. See ARGV. This allows defining a function block that can operate on a variable number of arguments. Unlike loading a file via a call statement, arguments are not repackaged as string variables (e.g. ARG1).

Example:

     function $max << EOF
         local max = real("-Inf")
         if (ARGC == 0) { return NaN }
         do for [i=1:ARGC] {
             if (max < ARGV[i]) {
                 max = ARGV[i]
             }
         }
         return max
     EOF
     gnuplot> foo = $max( f(A), 2.0, C, Array[3] )
     gnuplot> baz = $max( foo, 100. )

The primary motivation for function block support is to allow definition of complicated functions directly in gnuplot. Execution is of course slower than if the same function were coded in C or Fortran, but this is acceptable for many purposes. If execution speed matters then the function can be implemented later as a plugin instead (see plugins).

A second use for function blocks is to allow execution of gnuplot commands in a context they otherwise could not appear. Suppose for example you want to plot data from two csv files, but one file uses comma-separated fields while the other uses semicolon-separated fields. Normally this property would have been set by a previous set datafile command and would have to match all files used by the plot command. However we can define a function block to invoke as a definition immediately before each file is referenced in the plot.

     function $set_csv(char) << EOF
         set datafile separator char
     EOF
     plot tmp=$set_csv(",") FILE1, tmp=$set_csv(";") FILE2

Limitations:

• Data blocks and function blocks cannot be defined inside a function block.
• Pseudofile '-' cannot be used to read data inside a function block.
• These commands cannot be executed inside a function block: reset, shell, !<shell command>.
• A plot, replot, splot, refresh, stats, vfill, or fit command is accepted in a function block only if none of those commands is already in progress. E.g. you cannot use stats in a function block called by a plot command, you cannot invoke plot from inside a fit command, etc.

A non-trivial example of using function blocks to implement and plot a 15-term Lanczos approximation for the complex lngamma function is provided in the demo collection as function_block.dem The function block implementation is slower by a factor of roughly 25 compared to the built-in lnGamma function using the same algorithm coded directly in C. Nevertheless it is still fast enough for 3D interactive rotation.

Use of function blocks is EXPERIMENTAL. Details may change before inclusion in a release version.