wolffd@0: % PROCESS_OPTIONS - Processes options passed to a Matlab function.
wolffd@0: %                   This function provides a simple means of
wolffd@0: %                   parsing attribute-value options.  Each option is
wolffd@0: %                   named by a unique string and is given a default
wolffd@0: %                   value.
wolffd@0: %
wolffd@0: % Usage:  [var1, var2, ..., varn[, unused]] = ...
wolffd@0: %           process_options(args, ...
wolffd@0: %                           str1, def1, str2, def2, ..., strn, defn)
wolffd@0: %
wolffd@0: % Arguments:   
wolffd@0: %            args            - a cell array of input arguments, such
wolffd@0: %                              as that provided by VARARGIN.  Its contents
wolffd@0: %                              should alternate between strings and
wolffd@0: %                              values.
wolffd@0: %            str1, ..., strn - Strings that are associated with a 
wolffd@0: %                              particular variable
wolffd@0: %            def1, ..., defn - Default values returned if no option
wolffd@0: %                              is supplied
wolffd@0: %
wolffd@0: % Returns:
wolffd@0: %            var1, ..., varn - values to be assigned to variables
wolffd@0: %            unused          - an optional cell array of those 
wolffd@0: %                              string-value pairs that were unused;
wolffd@0: %                              if this is not supplied, then a
wolffd@0: %                              warning will be issued for each
wolffd@0: %                              option in args that lacked a match.
wolffd@0: %
wolffd@0: % Examples:
wolffd@0: %
wolffd@0: % Suppose we wish to define a Matlab function 'func' that has
wolffd@0: % required parameters x and y, and optional arguments 'u' and 'v'.
wolffd@0: % With the definition
wolffd@0: %
wolffd@0: %   function y = func(x, y, varargin)
wolffd@0: %
wolffd@0: %     [u, v] = process_options(varargin, 'u', 0, 'v', 1);
wolffd@0: %
wolffd@0: % calling func(0, 1, 'v', 2) will assign 0 to x, 1 to y, 0 to u, and 2
wolffd@0: % to v.  The parameter names are insensitive to case; calling 
wolffd@0: % func(0, 1, 'V', 2) has the same effect.  The function call
wolffd@0: % 
wolffd@0: %   func(0, 1, 'u', 5, 'z', 2);
wolffd@0: %
wolffd@0: % will result in u having the value 5 and v having value 1, but
wolffd@0: % will issue a warning that the 'z' option has not been used.  On
wolffd@0: % the other hand, if func is defined as
wolffd@0: %
wolffd@0: %   function y = func(x, y, varargin)
wolffd@0: %
wolffd@0: %     [u, v, unused_args] = process_options(varargin, 'u', 0, 'v', 1);
wolffd@0: %
wolffd@0: % then the call func(0, 1, 'u', 5, 'z', 2) will yield no warning,
wolffd@0: % and unused_args will have the value {'z', 2}.  This behaviour is
wolffd@0: % useful for functions with options that invoke other functions
wolffd@0: % with options; all options can be passed to the outer function and
wolffd@0: % its unprocessed arguments can be passed to the inner function.
wolffd@0: 
wolffd@0: % Copyright (C) 2002 Mark A. Paskin
wolffd@0: %
wolffd@0: % This program is free software; you can redistribute it and/or modify
wolffd@0: % it under the terms of the GNU General Public License as published by
wolffd@0: % the Free Software Foundation; either version 2 of the License, or
wolffd@0: % (at your option) any later version.
wolffd@0: %
wolffd@0: % This program is distributed in the hope that it will be useful, but
wolffd@0: % WITHOUT ANY WARRANTY; without even the implied warranty of
wolffd@0: % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
wolffd@0: % General Public License for more details.
wolffd@0: %
wolffd@0: % You should have received a copy of the GNU General Public License
wolffd@0: % along with this program; if not, write to the Free Software
wolffd@0: % Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
wolffd@0: % USA.
wolffd@0: %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0: 
wolffd@0: function [varargout] = process_options(args, varargin)
wolffd@0: 
wolffd@0: % Check the number of input arguments
wolffd@0: n = length(varargin);
wolffd@0: if (mod(n, 2))
wolffd@0:   error('Each option must be a string/value pair.');
wolffd@0: end
wolffd@0: 
wolffd@0: % Check the number of supplied output arguments
wolffd@0: if (nargout < (n / 2))
wolffd@0:   error('Insufficient number of output arguments given');
wolffd@0: elseif (nargout == (n / 2))
wolffd@0:   warn = 1;
wolffd@0:   nout = n / 2;
wolffd@0: else
wolffd@0:   warn = 0;
wolffd@0:   nout = n / 2 + 1;
wolffd@0: end
wolffd@0: 
wolffd@0: % Set outputs to be defaults
wolffd@0: varargout = cell(1, nout);
wolffd@0: for i=2:2:n
wolffd@0:   varargout{i/2} = varargin{i};
wolffd@0: end
wolffd@0: 
wolffd@0: % Now process all arguments
wolffd@0: nunused = 0;
wolffd@0: for i=1:2:length(args)
wolffd@0:   found = 0;
wolffd@0:   for j=1:2:n
wolffd@0:     if strcmpi(args{i}, varargin{j})
wolffd@0:       varargout{(j + 1)/2} = args{i + 1};
wolffd@0:       found = 1;
wolffd@0:       break;
wolffd@0:     end
wolffd@0:   end
wolffd@0:   if (~found)
wolffd@0:     if (warn)
wolffd@0:       warning(sprintf('Option ''%s'' not used.', args{i}));
wolffd@0:       args{i}
wolffd@0:     else
wolffd@0:       nunused = nunused + 1;
wolffd@0:       unused{2 * nunused - 1} = args{i};
wolffd@0:       unused{2 * nunused} = args{i + 1};
wolffd@0:     end
wolffd@0:   end
wolffd@0: end
wolffd@0: 
wolffd@0: % Assign the unused arguments
wolffd@0: if (~warn)
wolffd@0:   if (nunused)
wolffd@0:     varargout{nout} = unused;
wolffd@0:   else
wolffd@0:     varargout{nout} = cell(0);
wolffd@0:   end
wolffd@0: end