1.1.1 parseOptions()

parseOptions() is a general-purpose argument parser for Octave functions. It provides parsing of keyword-value arguments as well as powerful type-checking of argument values. Together with octapps_run, a Unix shell script, Octave functions written using parseOptions may be called directly from the Unix command line with no additional changes.

Consider the following simple function:

function function1(varargin)

  parseOptions(varargin,
               {"message", "char"},
               []);

  printf("%s\n", message);

endfunction

This defines a function called function1(), whose arguments are parsed by parseOptions(). The first argument to parseOptions() are the arguments passed to function1(), which are contained in the cell array varargin. The second and subsequent¹ arguments to parseOptions() define specifications which define which arguments are accepted by parseOptions(). Each specification is given by a cell array { … } with at least two arguments: the first argument is the keyword given to the argument, and the second argument defines the allowed type of the argument.

In this example, function1() takes a single keyword argument, message, whose value must satisfy the type specification ‘char’. The type specifications generally map naturally to Octave functions which test for various types: a type specification ‘<type>’ calls the Octave function is<type>() on the argument value, which must return ‘true’ for the argument value to be accepted. In this case, the type specification ‘char’ calls the Octave function ischar(), which returns ‘true’ only if the argument value is a string.

The function function1() is called from within Octave like this:

octave> function1("message", "Hello world!")
Hello world!

Incorrect calls to function1() are handled with error messages:

octave> function1
error: parseOptions: missing required option 'message'
error: called from
    parseOptions at line 409 column 9
    function1 at line 3 column 3

octave> function1("message")
error: parseOptions: expected 'key',value pairs following regular options in args
error: called from
    parseOptions at line 329 column 5
    function1 at line 3 column 3

octave> function1("message", 1.23)
error: parseOptions: value of 'message' must satisfy ( ischar(x) )
error: called from
    parseOptions at line 379 column 11
    function1 at line 3 column 3

The function function1() can also be called directly from the Unix command line, using the script octapps_run installed by OctApps, like this:

$ source octapps-user-env.sh

$ octapps_run function1 --message "Hello world!"
Hello world!

The "keyword", value syntax used to call function1() from within Octave translates straightforwardly into the usual --keyword value or --keyword=value syntax used by Unix command-line programs.

Now consider a more complicated example:

function function2(varargin)

  parseOptions(varargin,
               {"message", "char"},
               {"count", "integer,strictpos,scalar"},
               {"offset", "integer,scalar", 0},
               {"scale", "real,positive,scalar", 2.34},
               {"direction", "column,rows:2", [1.3; 5.7]},
               {"transform", "matrix,cols:2", eye(2)},
               []);

  printf("%s\n", message);
  printf("count = %i, count + offset = %i, count * scale = %g\n", count, count + offset, count * scale);
  printf("direction = [%g; %g], transform * direction = [%g; %g]\n", direction, transform * direction);

endfunction

This example introduces some new features of parseOptions():

• parseOptions() includes many builtin type specifications:

  ‘bool’

  ‘logical’

  Argument value must be a Boolean/logical value, i.e. true or false or 1 or 0.

  ‘cell’

  Argument value must a cell array.

  ‘function’

  Argument value must be a function handle.

  ‘complex’

  Argument value must be numeric and complex-valued.

  ‘real’

  Argument value must be numeric and real-values.

  ‘integer’

  Argument value must be numeric and integer-valued.

  ‘evenint’

  Argument value must be numeric and an even integer.

  ‘oddint’

  Argument value must be numeric and an odd integer.

  ‘nonzero’

  Argument value must be numeric and non-zero.

  ‘positive’

  Argument value must be numeric and either zero or positively valued.

  ‘negative’

  Argument value must be numeric and either zero or negatively valued.

  ‘strictpos’

  Argument value must be numeric and strictly positive.

  ‘strictneg’

  Argument value must be numeric and strictly negative.

  ‘unit’

  Argument value must be numeric and between 0 and 1 (including 0 and 1).

  ‘strictunit’

  Argument value must be numeric and strictly between 0 and 1 (i.e. not including 0 and 1).

  ‘a:<class>’

  Argument value must be an instance of the Octave class ‘<class>’, as determined by the Octave function isa().

  ‘acell:<class>’

  Argument value must be a cell array whose members are instances of the Octave class ‘<class>’, as determined by the Octave function isa().

  ‘size:<size>’

  The size of the argument value must match ‘<size>’.

  ‘numel:<n>’

  The number of elements of the argument value must match ‘<n>’.

  ‘rows:<n>’

  The number of rows of the argument value must match ‘<n>’.

  ‘cols:<n>’

  The number of columns of the argument value must match ‘<n>’.

• Type specifications can take several requirements separated by commas.
• Argument specifications can include a third argument which gives a default value for the function argument.

Returning to the example function2(), the argument specifications are therefore interpreted as follows:

message

Argument value must be a string.

count

Argument value must be a strictly-positive integer scalar.

offset

Argument value must be a integer scalar; default value is ‘0’.

scale

Argument value must be a positive real scalar; default value is ‘2.34’.

direction

Argument value must be a column vector with 2 rows; default value is ‘[1.3; 5.7]’.

transform

Argument value must be a matrix with 2 columns: default value is eye(2), i.e. the 2-by-2 identity matrix.

The function function2() is called from within Octave like this:

octave> function2("message", "Hello world!", "count", 3)
Hello world!
count = 3, count + offset = 3, count * scale = 7.02
direction = [1.3; 5.7], transform * direction = [1.3; 5.7]

octave> function2("message", "Hello world!", "count", 3, "offset", -7)
Hello world!
count = 3, count + offset = -4, count * scale = 7.02
direction = [1.3; 5.7], transform * direction = [1.3; 5.7]

octave> function2("message", "Hello world!", "count", 3, "scale", 0.35)
Hello world!
count = 3, count + offset = 3, count * scale = 1.05
direction = [1.3; 5.7], transform * direction = [1.3; 5.7]

octave> function2("message", "Hello world!", "count", 3, "transform", [1,2;3,4])
Hello world!
count = 3, count + offset = 3, count * scale = 7.02
direction = [1.3; 5.7], transform * direction = [12.7; 26.7]

or from the Unix command line using octapps_run like this:

$ source octapps-user-env.sh

$ octapps_run function2 --message "Hello world!" --count=3
Hello world!
count = 3, count + offset = 3, count * scale = 7.02
direction = [1.3; 5.7], transform * direction = [1.3; 5.7]

$ octapps_run function2 --message "Hello world!" --count=3 --offset=-7
Hello world!
count = 3, count + offset = -4, count * scale = 7.02
direction = [1.3; 5.7], transform * direction = [1.3; 5.7]

$ octapps_run function2 --message "Hello world!" --count=3 --scale 0.35
Hello world!
count = 3, count + offset = 3, count * scale = 1.05
direction = [1.3; 5.7], transform * direction = [1.3; 5.7]

$ octapps_run function2 --message "Hello world!" --count=3 --transform '[1,2;3,4]'
Hello world!
count = 3, count + offset = 3, count * scale = 7.02
direction = [1.3; 5.7], transform * direction = [12.7; 26.7]