annotate toolboxes/bioakustik_tools/conversion/process_options.m @ 0:e9a9cd732c1e tip

first hg version after svn
author wolffd
date Tue, 10 Feb 2015 15:05:51 +0000
parents
children
rev   line source
wolffd@0 1 % PROCESS_OPTIONS - Processes options passed to a Matlab function.
wolffd@0 2 % This function provides a simple means of
wolffd@0 3 % parsing attribute-value options. Each option is
wolffd@0 4 % named by a unique string and is given a default
wolffd@0 5 % value.
wolffd@0 6 %
wolffd@0 7 % Usage: [var1, var2, ..., varn[, unused]] = ...
wolffd@0 8 % process_options(args, ...
wolffd@0 9 % str1, def1, str2, def2, ..., strn, defn)
wolffd@0 10 %
wolffd@0 11 % Arguments:
wolffd@0 12 % args - a cell array of input arguments, such
wolffd@0 13 % as that provided by VARARGIN. Its contents
wolffd@0 14 % should alternate between strings and
wolffd@0 15 % values.
wolffd@0 16 % str1, ..., strn - Strings that are associated with a
wolffd@0 17 % particular variable
wolffd@0 18 % def1, ..., defn - Default values returned if no option
wolffd@0 19 % is supplied
wolffd@0 20 %
wolffd@0 21 % Returns:
wolffd@0 22 % var1, ..., varn - values to be assigned to variables
wolffd@0 23 % unused - an optional cell array of those
wolffd@0 24 % string-value pairs that were unused;
wolffd@0 25 % if this is not supplied, then a
wolffd@0 26 % warning will be issued for each
wolffd@0 27 % option in args that lacked a match.
wolffd@0 28 %
wolffd@0 29 % Examples:
wolffd@0 30 %
wolffd@0 31 % Suppose we wish to define a Matlab function 'func' that has
wolffd@0 32 % required parameters x and y, and optional arguments 'u' and 'v'.
wolffd@0 33 % With the definition
wolffd@0 34 %
wolffd@0 35 % function y = func(x, y, varargin)
wolffd@0 36 %
wolffd@0 37 % [u, v] = process_options(varargin, 'u', 0, 'v', 1);
wolffd@0 38 %
wolffd@0 39 % calling func(0, 1, 'v', 2) will assign 0 to x, 1 to y, 0 to u, and 2
wolffd@0 40 % to v. The parameter names are insensitive to case; calling
wolffd@0 41 % func(0, 1, 'V', 2) has the same effect. The function call
wolffd@0 42 %
wolffd@0 43 % func(0, 1, 'u', 5, 'z', 2);
wolffd@0 44 %
wolffd@0 45 % will result in u having the value 5 and v having value 1, but
wolffd@0 46 % will issue a warning that the 'z' option has not been used. On
wolffd@0 47 % the other hand, if func is defined as
wolffd@0 48 %
wolffd@0 49 % function y = func(x, y, varargin)
wolffd@0 50 %
wolffd@0 51 % [u, v, unused_args] = process_options(varargin, 'u', 0, 'v', 1);
wolffd@0 52 %
wolffd@0 53 % then the call func(0, 1, 'u', 5, 'z', 2) will yield no warning,
wolffd@0 54 % and unused_args will have the value {'z', 2}. This behaviour is
wolffd@0 55 % useful for functions with options that invoke other functions
wolffd@0 56 % with options; all options can be passed to the outer function and
wolffd@0 57 % its unprocessed arguments can be passed to the inner function.
wolffd@0 58
wolffd@0 59 % Copyright (C) 2002 Mark A. Paskin
wolffd@0 60 %
wolffd@0 61 % This program is free software; you can redistribute it and/or modify
wolffd@0 62 % it under the terms of the GNU General Public License as published by
wolffd@0 63 % the Free Software Foundation; either version 2 of the License, or
wolffd@0 64 % (at your option) any later version.
wolffd@0 65 %
wolffd@0 66 % This program is distributed in the hope that it will be useful, but
wolffd@0 67 % WITHOUT ANY WARRANTY; without even the implied warranty of
wolffd@0 68 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
wolffd@0 69 % General Public License for more details.
wolffd@0 70 %
wolffd@0 71 % You should have received a copy of the GNU General Public License
wolffd@0 72 % along with this program; if not, write to the Free Software
wolffd@0 73 % Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
wolffd@0 74 % USA.
wolffd@0 75 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
wolffd@0 76
wolffd@0 77 function [varargout] = process_options(args, varargin)
wolffd@0 78
wolffd@0 79 % Check the number of input arguments
wolffd@0 80 n = length(varargin);
wolffd@0 81 if (mod(n, 2))
wolffd@0 82 error('Each option must be a string/value pair.');
wolffd@0 83 end
wolffd@0 84
wolffd@0 85 % Check the number of supplied output arguments
wolffd@0 86 if (nargout < (n / 2))
wolffd@0 87 error('Insufficient number of output arguments given');
wolffd@0 88 elseif (nargout == (n / 2))
wolffd@0 89 warn = 1;
wolffd@0 90 nout = n / 2;
wolffd@0 91 else
wolffd@0 92 warn = 0;
wolffd@0 93 nout = n / 2 + 1;
wolffd@0 94 end
wolffd@0 95
wolffd@0 96 % Set outputs to be defaults
wolffd@0 97 varargout = cell(1, nout);
wolffd@0 98 for i=2:2:n
wolffd@0 99 varargout{i/2} = varargin{i};
wolffd@0 100 end
wolffd@0 101
wolffd@0 102 % Now process all arguments
wolffd@0 103 nunused = 0;
wolffd@0 104 for i=1:2:length(args)
wolffd@0 105 found = 0;
wolffd@0 106 for j=1:2:n
wolffd@0 107 if strcmpi(args{i}, varargin{j})
wolffd@0 108 varargout{(j + 1)/2} = args{i + 1};
wolffd@0 109 found = 1;
wolffd@0 110 break;
wolffd@0 111 end
wolffd@0 112 end
wolffd@0 113 if (~found)
wolffd@0 114 if (warn)
wolffd@0 115 warning(sprintf('Option ''%s'' not used.', args{i}));
wolffd@0 116 args{i}
wolffd@0 117 else
wolffd@0 118 nunused = nunused + 1;
wolffd@0 119 unused{2 * nunused - 1} = args{i};
wolffd@0 120 unused{2 * nunused} = args{i + 1};
wolffd@0 121 end
wolffd@0 122 end
wolffd@0 123 end
wolffd@0 124
wolffd@0 125 % Assign the unused arguments
wolffd@0 126 if (~warn)
wolffd@0 127 if (nunused)
wolffd@0 128 varargout{nout} = unused;
wolffd@0 129 else
wolffd@0 130 varargout{nout} = cell(0);
wolffd@0 131 end
wolffd@0 132 end