KEYWORDS Function Keywords
Section: Functions and Scripts
Usage
A feature of IDL that FreeMat has adopted is a modified form ofkeywords
. 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 ofnargin
,
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/basu/dev/branches/FreeMat4/help/tmp/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