M-File Help: tb_optparse

M-File Help: tb_optparse | View code for tb_optparse

# tb_optparse

Standard option parser for Toolbox functions

optout = tb_optparse(opt, arglist) is a generalized option parser for Toolbox functions. opt is a structure that contains the names and default values for the options, and arglist is a cell array containing option parameters, typically it comes from VARARGIN. It supports options that have an assigned value, boolean or enumeration types (string or int).

The software pattern is:

    function(a, b, c, varargin)
    opt.foo = false;
    opt.bar = true;
    opt.blah = [];
    opt.choose = {'this', 'that', 'other'};
    opt.select = {'#no', '#yes'};
    opt = tb_optparse(opt, varargin);

Optional arguments to the function behave as follows:

'foo' | sets opt.foo := true
'nobar' | sets opt.foo := false
'blah', 3 | sets opt.blah := 3
'blah', {x,y} | sets opt.blah := {x,y}
'that' | sets opt.choose := 'that'
'yes' | sets opt.select := (the second element)

and can be given in any combination.

If neither of 'this', 'that' or 'other' are specified then opt.choose := 'this'. Alternatively if:

    opt.choose = {[], 'this', 'that', 'other'};

then if neither of 'this', 'that' or 'other' are specified then opt.choose := []

If neither of 'no' or 'yes' are specified then opt.select := 1.

Note:

- That the enumerator names must be distinct from the field names.
- That only one value can be assigned to a field, if multiple values are required they must placed in a cell array.
- To match an option that starts with a digit, prefix it with 'd_', so the field 'd_3d' matches the option '3d'.
- OPT can be an object, rather than a structure, in which case the passed options are assigned to properties.

The return structure is automatically populated with fields: verbose and debug. The following options are automatically parsed:

'verbose' | sets opt.verbose := true
'verbose=2' | sets opt.verbose := 2 (very verbose)
'verbose=3' | sets opt.verbose := 3 (extremeley verbose)
'verbose=4' | sets opt.verbose := 4 (ridiculously verbose)
'debug', N | sets opt.debug := N
'showopt' | displays opt and arglist
'setopt', S | sets opt := S, if S.foo=4, and opt.foo is present, then opt.foo is set to 4.

The allowable options are specified by the names of the fields in the structure opt. By default if an option is given that is not a field of opt an error is declared.

[optout,args] = tb_optparse(opt, arglist) as above but returns all the unassigned options, those that don't match anything in opt, as a cell array of all unassigned arguments in the order given in arglist.

[optout,args,ls] = tb_optparse(opt, arglist) as above but if any unmatched option looks like a MATLAB LineSpec (eg. 'r:') it is placed in ls rather than in args.

© 1990-2014 Peter Corke.