Home > wafo > misc > parseoptions.m

parseoptions

PURPOSE ^

Create or alter a OPTIONS structure.

SYNOPSIS ^

options = parseoptions(varargin)

DESCRIPTION ^

 PARSEOPTIONS Create or alter a OPTIONS structure. 
  
   CALL:  options = parseoptions(legalFnames,options,funcname,opts1,opts2,..., 
                                 par1,val1,par2,val2,...); 
          options = parseoptions(options,opts1,opts2,..., 
                                 par1,val1,par2,val2,...);   
  
    options    = OUT: options structure in which the named  
                      parameters have the specified values.   
                 IN:  options structure giving the legal names and 
                      default options   
    legalFnames = character array giving the names of functions for 
                  which default values for the options structure could be 
                  extracted. 
    funcname   = string giving the name of the function for which default 
                 values for the options structure should be extracted. 
                 (Must be equal to one of the names in LEGALFNAMES.)   
    opts1, 
    opts2..    = options structures 
    par1,par2..= strings identifying the parameter to alter 
    val1,val2..= corresponding values the parameters are altered to. 
     
    PARSEOPTIONS combines the default options for a function given by 
    FUNCNAME with new options structures (OPTS1,OPTS2,...) and/or with 
    the named parameters (PAR1,PAR2,...) with the corresponding values 
    (VAL1, VAL2,...). 
    The parameters are set in the same order as the input arguments. 
    Any parameters with non-empty values of the options struct overwrite 
    the corresponding old parameters.  
    The input arguments can be given in any order with one exception: 
    PARx and VALx must be given in pairs in that order. 
    Any unspecified parameters for PARx are set to [].  
    Parameters with value [] indicate to use the default value for that 
    parameter when OPTIONS is passed to the function. It is sufficient to 
    type only the first characters that uniquely identify the parameter 
    or function name.  Upper case letters for parameter names and values 
    that are strings are ignored. If an invalid string is provided, the 
    default is used. 
     
    PARSEOPTIONS with no input and no output arguments displays this help  
  
  Examples: 
   defaultoptions = struct('test',[],'integrate',[] ) 
   parseoptions(defaultoptions,'int','yes') 
   opt = defaultoptions; 
   opt.test = 'yes';   
   parseoptions(defaultoptions,'int','yes',opt)

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

001 function options = parseoptionsparseoptions(varargin) 
002 %PARSEOPTIONS Create or alter a OPTIONS structure. 
003 % 
004 %  CALL:  options = parseoptions(legalFnames,options,funcname,opts1,opts2,..., 
005 %                                par1,val1,par2,val2,...); 
006 %         options = parseoptions(options,opts1,opts2,..., 
007 %                                par1,val1,par2,val2,...);   
008 % 
009 %   options    = OUT: options structure in which the named  
010 %                     parameters have the specified values.   
011 %                IN:  options structure giving the legal names and 
012 %                     default options   
013 %   legalFnames = character array giving the names of functions for 
014 %                 which default values for the options structure could be 
015 %                 extracted. 
016 %   funcname   = string giving the name of the function for which default 
017 %                values for the options structure should be extracted. 
018 %                (Must be equal to one of the names in LEGALFNAMES.)   
019 %   opts1, 
020 %   opts2..    = options structures 
021 %   par1,par2..= strings identifying the parameter to alter 
022 %   val1,val2..= corresponding values the parameters are altered to. 
023 %    
024 %   PARSEOPTIONS combines the default options for a function given by 
025 %   FUNCNAME with new options structures (OPTS1,OPTS2,...) and/or with 
026 %   the named parameters (PAR1,PAR2,...) with the corresponding values 
027 %   (VAL1, VAL2,...). 
028 %   The parameters are set in the same order as the input arguments. 
029 %   Any parameters with non-empty values of the options struct overwrite 
030 %   the corresponding old parameters.  
031 %   The input arguments can be given in any order with one exception: 
032 %   PARx and VALx must be given in pairs in that order. 
033 %   Any unspecified parameters for PARx are set to [].  
034 %   Parameters with value [] indicate to use the default value for that 
035 %   parameter when OPTIONS is passed to the function. It is sufficient to 
036 %   type only the first characters that uniquely identify the parameter 
037 %   or function name.  Upper case letters for parameter names and values 
038 %   that are strings are ignored. If an invalid string is provided, the 
039 %   default is used. 
040 %    
041 %   PARSEOPTIONS with no input and no output arguments displays this help  
042 % 
043 % Examples: 
044 %  defaultoptions = struct('test',[],'integrate',[] ) 
045 %  parseoptions(defaultoptions,'int','yes') 
046 %  opt = defaultoptions; 
047 %  opt.test = 'yes';   
048 %  parseoptions(defaultoptions,'int','yes',opt) 
049    
050 % History 
051 % by pab 14.05.2003 
052 % based on MATLAB's optimset 
053  
054 if (nargin == 0)  
055   % Display help 
056   help parseoptions 
057   return; 
058 end 
059  
060 % Initialization 
061 fnames = ''; 
062  
063 % Legal functions names 
064 ix = 1; 
065 if ((ix<=nargin) & (ischar(varargin{ix}))), 
066   fnames = varargin{ix}; 
067   ix = 2; 
068 end 
069 if ((ix<=nargin) & (isstruct(varargin{ix}))), 
070   options = varargin{ix}; 
071   ix = ix + 1; 
072 else 
073   error('Struct expected.') 
074 end 
075  
076 % Legal parameter names 
077 namesc = fieldnames(options); 
078 names  = lower(strvcat(namesc{:})); 
079  
080 expectval = 0;         % start expecting a name or stucture, not a value 
081 while ix <= nargin 
082   arg = varargin{ix}; 
083   if expectval 
084     options   = setfield(options,namesc{iy},arg); 
085     expectval = 0; 
086   else 
087     switch lower(class(arg)) 
088       case 'char', 
089     lowArg = strtok(lower(arg),'.');      % Downcase and strip .m extensions 
090     iy = findlname(lowArg,fnames,0);      % Find legal function name 
091     if length(iy)==1, 
092       opt1    = defaultopt(fnames(iy,:)); % Get default options for function 
093       options = combineopt(options,opt1); % Combine with old options 
094     else,                                 
095       iy = findlname(lowArg,names,1);     % Find legal parameter name 
096       if isempty(iy),                     % Illegal parameter name 
097         ix = ix+1;                        % Skip next input   
098       else 
099         expectval = 1;                    % expect a value next 
100       end 
101     end   
102       case 'struct' 
103     options = combineopt(options,arg); 
104       otherwise 
105     error(sprintf('Expected argument %d to be a string or a struct.', ix)); 
106     end 
107   end 
108   ix=ix+1; 
109 end 
110  
111 if expectval 
112    error(sprintf('Expected value for parameter ''%s''.', arg)); 
113 end 
114 return 
115  
116 function iy = findlname(arg,names,chkempty) 
117 % FINDLNAME find index to legal parameter name   
118  
119 iy = strmatch(arg,names); 
120 %iy = find(strncmp(lowArg,fnames,2)); 
121 Niy = length(iy); 
122 if Niy<1 & chkempty                      % No matches 
123   msg = ['Unrecognized parameter name ' arg '.']; 
124   warning(msg); 
125 elseif Niy > 1      % More than one match 
126   % Find exact matches in case any names are subsets of others 
127   k = strmatch(arg,names,'exact'); 
128   if length(k) == 1 
129     iy = k; 
130   else 
131     msg = ['Ambiguous parameter name ' arg ' (']; 
132     for k = iy' 
133       msg = [msg ', ' deblank(names(k,:))]; 
134     end 
135     msg = [ msg ').'] 
136     error(msg); 
137   end 
138 end 
139 return 
140  
141 function options = combineopt(options,newopts) 
142 %COMBINEOPT combines an existing options structure 
143 %   OPTIONS with a new options structure NEWOPTS.  Any parameters in NEWOPTS 
144 %   with non-empty values overwrite the corresponding old parameters in 
145 %   OPTIONS.  
146  
147 if ~isempty(newopts)                      % [] is a valid options argument 
148   newNames    = fieldnames(newopts); 
149   legalNames  = fieldnames(options); 
150    
151   [commonNames, ia, ib] = intersect(lower(newNames),lower(legalNames)); 
152   if isempty(ia), 
153     return; 
154   end 
155   cval = struct2cell(newopts); 
156   ind  = findNonEmptyCells(cval(ia)); 
157   if any(ind) 
158     val  = struct2cell(options); 
159     val(ib(ind)) = cval(ia(ind)); 
160     options = cell2struct(val,legalNames,1); 
161   end 
162 end 
163 return 
164  
165  
166 function options = defaultopt(fname) 
167 % DEFAULTOPT Get default OPTIONS structure from the function FNAME 
168  
169 fname = deblank(fname); 
170  
171 if ~exist(fname) 
172   msg = ['No default options available: the function ' fname ' does not exist on the path.']; 
173   error(msg) 
174 end 
175 try  
176   options = feval(fname,'defaults'); 
177 catch 
178   msg = ['No default options available for the function ' fname '.']; 
179   error(msg) 
180 end 
181 return 
182  
183 function ind = findNonEmptyCells(carray) 
184   try, % matlab 5.3 or higher 
185     ind = find(~cellfun('isempty',carray)).'; 
186   catch 
187     % Slow  
188     n = length(carray); 
189     ind1 = zeros(1,n); 
190     for ix = 1:n 
191       ind1(ix) = isempty(carray{ix}); 
192     end 
193     ind = find(~ind1); 
194   end 
195   return

Mathematical Statistics
Centre for Mathematical Sciences
Lund University with Lund Institute of Technology

Comments or corrections to the WAFO group


Generated on Thu 06-Oct-2005 02:21:16 for WAFO by m2html © 2003