
 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


* FreeMat_Documentation
* Functions_and_Scripts
* Generated on Thu Jul 25 2013 17:17:14 for FreeMat by
  doxygen_ 1.8.1.1

