FreeMat: KEYWORDS Function Keywords

FreeMat

- Main Page
- Related Pages

KEYWORDS Function Keywords

Section: Functions and Scripts

# Usage

A feature of IDL that FreeMat has adopted is a modified form of `keywords`. The purpose of `keywords` is to allow you to call a function with the arguments to the function specified in an arbitrary order. To specify the syntax of `keywords`, suppose there is a function with prototype

      function [out_1,...,out_M] = foo(in_1,...,in_N)

Then the general syntax for calling function `foo` using keywords is

      foo(val_1, val_2, /in_k=3)

which is exactly equivalent to

      foo(val_1, val_2, [], [], ..., [], 3),

where the 3 is passed as the k-th argument, or alternately,

      foo(val_1, val_2, /in_k)

which is exactly equivalent to

      foo(val_1, val_2, [], [], ..., [], logical(1)),

Note that you can even pass reference arguments using keywords.

# Example

The most common use of keywords is in controlling options for functions. For example, the following function takes a number of binary options that control its behavior. For example, consider the following function with two arguments and two options. The function has been written to properly use and handle keywords. The result is much cleaner than the MATLAB approach involving testing all possible values of `nargin`, and forcing explicit empty brackets for don't care parameters.

         keyfunc.m

    function c = keyfunc(a,b,operation,printit)
      if (~isset('a') | ~isset('b'))
        error('keyfunc requires at least the first two 2 arguments');
      end;
      if (~isset('operation'))
        % user did not define the operation, default to '+'
        operation = '+';
      end
      if (~isset('printit'))
        % user did not specify the printit flag, default is false
        printit = 0;
      end
      % simple operation...
      eval(['c = a ' operation ' b;']);
      if (printit)
        printf('%f %s %f = %f\n',a,operation,b,c);
      end

Now some examples of how this function can be called using `keywords`.

    --> keyfunc(1,3)                % specify a and b, defaults for the others

    ans =
     4

    --> keyfunc(1,3,/printit)       % specify printit is true
    1.000000 + 3.000000 = 4.000000

    ans =
     4

    --> keyfunc(/operation='-',2,3) % assigns a=2, b=3

    ans =
     -1

    --> keyfunc(4,/operation='*',/printit) % error as b is unspecified
    In /home/sbasu/Devel/FreeMat4/doc/fragments/keyfunc.m(keyfunc) at line 3
        In scratch() at line 1
        In base(base)
        In base()
        In global()
    Error: keyfunc requires at least the first two 2 arguments