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