123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187 |
- %parseargs [opts] = parseargs(arguments, pairs, singles, ignore_unknowns)
- %
- % Variable argument parsing-- supersedes parseargs_example. This
- % function is meant to be used in the context of other functions
- % which have variable arguments. Typically, the function using
- % variable argument parsing would be written with the following
- % header:
- %
- % function myfunction(args, ..., varargin)
- %
- % and would define the variables "pairs" and "singles" (in a
- % format described below), and would then include the line
- %
- % parseargs(varargin, pairs, singles);
- %
- % 'pairs' and 'singles' specify how the variable arguments should
- % be parsed; their format is decribed below. It is best
- % understood by looking at the example at the bottom of these help
- % comments.
- %
- % varargin can be of two forms:
- % 1) A cell array where odd entries are variable names and even entries are
- % the corresponding values
- % 2) A struct where the fieldnames are the variable names and the values of
- % the fields are the values (for pairs) or the existence of the field
- % triggers acts as a single.
- %
- % pairs can be of two forms:
- % 1) an n x 2 cell array where the first column are the variable names and
- % the 2nd column are the default values.
- % 2) A struct where the fieldnames are the variable names and the values of
- % the fields are the values.
- %
- % PARSEARGS DOES NOT RETURN ANY VALUES; INSTEAD, IT USES ASSIGNIN
- % COMMANDS TO CHANGE OR SET VALUES OF VARIABLES IN THE CALLING
- % FUNCTION'S SPACE.
- %
- %
- %
- % PARAMETERS:
- % -----------
- %
- % -arguments The varargin list, I.e. a row cell array.
- %
- % -pairs A cell array of all those arguments that are
- % specified by argument-value pairs. First column
- % of this cell array must indicate the variable
- % names; the second column must indicate
- % correponding default values.
- %
- % -singles A cell array of all those arguments that are
- % specified by a single flag. The first column must
- % indicate the flag; the second column must
- % indicate the corresponding variable name that
- % will be affected in the caller's workspace; the
- % third column must indicate the value that that
- % variable will take upon appearance of the flag;
- % and the fourth column must indicate a default
- % value for the variable.
- %
- %
- % Example:
- % --------
- %
- % In "pairs", the first column defines both the variable name and the
- % marker looked for in varargin, and the second column defines that
- % variable's default value:
- %
- % pairs = {'thingy' 20 ; ...
- % 'blob' 'that'};
- %
- % In "singles", the first column is the flag to be looked for in varargin,
- % the second column defines the variable name this flag affects, the third
- % column defines the value the variable will take if the flag was found, and
- % the last column defines the value the variable takes if the flag was NOT
- % found in varargin.
- %
- % singles = {'no_plot' 'plot_fg' '0' '1'; ...
- % {'plot' 'plot_fg' '1' '1'};
- %
- %
- % Now for the function call from the user function:
- %
- % parseargs({'blob', 'fuff!', 'no_plot'}, pairs, singles);
- %
- % This will set, in the caller space, thingy=20, blob='fuff!', and
- % plot_fg=0. Since default values are in the second column of "pairs"
- % and the fourth column of "singles", and in the call to
- % parseargs 'thingy' was not specified, 'thingy' takes on its
- % default value of 20.
- %
- % Note that the arguments to parseargs may be in any order-- the
- % only ordering restriction is that whatever immediately follows
- % pair names (e.g. 'blob') will be interpreted as the value to be
- % assigned to them (e.g. 'blob' takes on the value 'fuff!');
- %
- % If you never use singles, you can just call "parseargs(varargin, pairs)"
- % without the singles argument.
- %
- function [varargout] = parseargs(arguments, pairs, singles,ignore_unknowns)
- if nargin < 3, singles = {}; end;
- if nargin < 4, ignore_unknowns=false; end;
- % This assigns all the default values for pairs.
- if isstruct(pairs)
- out=pairs;
- fn=fieldnames(pairs);
- for fx=1:numel(fn)
- assignin('caller',fn{fx}, pairs.(fn{fx}));
- end
- pairs=fn;
- else
- for i=1:size(pairs,1),
- assignin('caller', pairs{i,1}, pairs{i,2});
- end;
- end
- % This assigns all the default values for singles.
- for i=1:size(singles,1),
- assignin('caller', singles{i,2}, singles{i,4});
- end;
- if isempty(singles), singles = {'', '', [], []}; nosingles=true; else nosingles=false; end;
- if isempty(pairs), pairs = {'', []}; nopairs=true; else nopairs=false; end;
- % Now we assign the value to those passed by arguments.
- if numel(arguments)==1 && isstruct(arguments{1})
- arguments=arguments{1};
- fn=fieldnames(arguments);
- for arg=1:numel(fn)
- switch fn{arg}
- case pairs(:,1)
- assignin('caller',fn{arg}, arguments.(fn{arg}));
- out.(fn{arg})=arguments.(fn{arg});
- case singles(:,1)
- u = find(strcmp(fn{arg}, singles(:,1)));
- out.(fn{arg})=singles(:,1);
- assignin('caller', singles{u,2}, singles{u,3});
- otherwise
- if ~ignore_unknowns
- fn{arg}
-
- mname = evalin('caller', 'mfilename');
- error([mname ' : Didn''t understand above parameter']);
- end
- end
- end
-
- else
- arg = 1; while arg <= length(arguments),
-
- switch arguments{arg},
-
- case pairs(:,1),
- if arg+1 <= length(arguments)
- assignin('caller', arguments{arg}, arguments{arg+1});
- arg = arg+1;
- end;
-
- case singles(:,1),
- u = find(strcmp(arguments{arg}, singles(:,1)));
- assignin('caller', singles{u,2}, singles{u,3});
-
- otherwise
- if ~ignore_unknowns
- arguments{arg}
- mname = evalin('caller', 'mfilename');
- error([mname ' : Didn''t understand above parameter']);
- else
- if nosingles
- arg=arg+1;
- elseif nopairs
- % don't increment args.
- else
- error('Cannot use ignore_unknown and a mix of singles and pairs')
- end
-
- end
- end;
- arg = arg+1; end;
- end
- if nargout>0
- varargout{1}=out;
- end
- return;
|