diff --git a/README.md b/README.md index 7fbbf0a..730aa9f 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ Please see my 2014 write-up __[dealing with variable options (varargin) in matlab](https://bahanonu.com/getOptions)__ ([https://bahanonu.com/getOptions](https://bahanonu.com/getOptions)) for details and reasons behind implementing and using this function. Installation and usage instructions below. +Also find function on MATLAB File Exchange: [![View getOptions on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://www.mathworks.com/matlabcentral/fileexchange/75464-getoptions). + Contact: __Biafra Ahanonu, PhD (bahanonu [at] alum [dot] mit [dot] edu)__. Made in USA.
@@ -18,6 +20,8 @@ Test by running `unitTestGetOptions` unit test. Will print out the modified stru ## Instructions on use There are two ways to have parent functions pass Name-Value pairs to child functions that `getOptions` will parse to update default options in child function. +__Note__ that `getOptions` has a `recursiveStructs` optional Name-Value input argument itself that if enabled (the default), causes `getOptions` to crawl through any options that are structures and replace only fieldnames that are present in the options passed by the parent function. If this is disabled, `getOptions` will replace any options that are structures with the entire structure input by the user regardless of whether the default options had a specific structure. + ### Method #1 Use the `'options', options` [Name-Value](https://www.mathworks.com/help/matlab/ref/varargin.html) pair to input an `options` structure that will overwrite default options in a function. - The name of the `opts` variable does not matter, but have to have the `options` Name input as one of the variable arguments for `getOptions` to recognize using Method #1. diff --git a/getOptions.m b/getOptions.m index c655b2a..d3a8185 100644 --- a/getOptions.m +++ b/getOptions.m @@ -4,27 +4,30 @@ % Started: 2013.11.04. % % inputs - % options - structure with options. + % options - structure passed by parent function with each fieldname containing an option to be used by the parent function. % inputArgs - an even numbered cell array, with {'option','value'} as the ordering. Normally pass varargin. % Outputs - % options - options structure with inputs to function added. + % options - options structure passed back to parent function with modified Name-Value inputs to function added. % NOTE - % use the 'options' name-value pair to input an options structure that will overwrite default options in a function, example below. + % Use the 'options' name-value pair to input an options structure that will overwrite default options in a function, example below. % options.Stargazer = 1; % options.SHH = 0; % getMutations(mutationList,'options',options); - + % % This is in contrast to using name-value pairs, both will produce the same result. % getMutations(mutationList,'Stargazer',1,'SHH',0); - % + % % USAGE % function [input1,input2] = exampleFxn(input1,input2,varargin) % %======================== % % DESCRIPTION % options.Stargazer = ''; + % % DESCRIPTION % options.SHH = ''; + % % DESCRIPTION + % options.Option3 = ''; % % get options - % options = getOptions(options,varargin); + % options = getOptions(options,varargin); % ***HERE IS WHERE getOptions IS USED*** % % display(options) % % unpack options into current workspace % % fn=fieldnames(options); @@ -48,15 +51,17 @@ % 2015.08.24 [23:31:36] - updated comments. - Biafra % 2015.12.03 [13:52:15] - Added recursive aspect to mirrorRightStruct and added support for handling struct name-value inputs. mirrorRightStruct checks that struct options input by the user are struct in the input options. - Biafra % 2016.xx.xx - warnings now show both calling function and it's parent function, improve debug for warnings. Slight refactoring of code to make easier to follow. - Biafra + % 2020.05.10 [18:00:23] - Updates to comments in getOptions and other minor changes. % TODO - % allow input of an option structure - DONE! - % call settings function to have defaults for all functions in a single place - DONE! - % allow recursive overwriting of options structure - DONE! + % Allow input of an option structure - DONE! + % Call settings function to have defaults for all functions in a single place - DONE! + % Allow recursive overwriting of options structure - DONE! % Type checking of all field names input by the user? %======================== - % Options for getOptions. Avoid recursion here, hence don't use getOptions for getOptions's options. + % Options for getOptions. + % Avoid recursion here, hence don't use getOptions for getOptions's options. % Binary: 1 = whether getOptions should use recursive structures or crawl through a structure's field names or just replace the entire structure. For example, if "1" then options that themselves are a structure or contain sub-structures, the fields will be replaced rather than the entire strucutre. goptions.recursiveStructs = 1; % Binary: 1 = show warning if user inputs Name-Value pair option input that is not in original structure. @@ -65,7 +70,7 @@ goptions.nParentStacks = 1; % Binary: 1 = get defaults for a function from getSettings. goptions.getFunctionDefaults = 0; - % Filter through options + % Update getOptions's options based on user input. try for i = 1:2:length(varargin) inputField = varargin{i}; @@ -175,7 +180,7 @@ function localShowWarnings(stackLevel,displayType,toStructName,fromField,val,nPa % Get the entire function-call stack. [ST,~] = dbstack; callingFxn = ST(stackLevel).name; - callingFxnPath=which(ST(stackLevel).file); + callingFxnPath = which(ST(stackLevel).file); callingFxnLine = num2str(ST(stackLevel).line); % Add info about parent function of function that called getOptions.