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