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