GetCustomDefaults

GetCustomDefaults - Get custom default value for a given function property.

  This is an 'internal' function used by FMAToolbox. You should not need
  to use it, unless you are developping new functions for this toolbox.

  See Example below.

  WARNING

    Custom defaults should be allowed with great care, because they *implicitly*
    change the default behavior of functions: because the actual function call
    does not make it explicit that default values are being overriden, the same
    code can yield different results for different users, or even for the same
    user before and after she/he changes the custom defaults.

  USAGE

    output = GetCustomDefaults(current,property,value)

    current        current value
    property       property name
    value          default value if custom default value is undefined

  EXAMPLE

    The function GetPositions has optional property-value pairs, including:

     - 'mode' (default value 'clean')
     - 'coordinates' (default value 'normalized')
     - 'pixel' (no default value)
     - 'distances' (default value [0 Inf])

    Users may want to change default values, e.g. have 'coordinates'
    set to 'video' whenever they call GetPositions without an explicit
    value. GetPositions therefore includes the following code:

      % Default values (customizable defaults must be empty at this point)
      c = '';

      % Parse parameters
      (possibly set a value for c, if supplied among optional input parameters)

      % Customizable defaults
      c = GetCustomDefaults(c,'coordinates','normalized');

    GetCustomDefaults will first test if c was already set (non-empty), in which
    case c will remain unaltered. Otherwise, it will test if there is a user-defined
    default value for 'coordinates', and issue a warning and set c to this value if
    it exists, or set it to 'normalized' otherwise.

    To define a custom default value, users would have to e.g. add the following
    lines to their startup.m file:

     global SETTINGS;
     SETTINGS.GetPositions.coordinates = 'video';

  NOTE

    Do not forget to document when the default value for a property can be customized.
    See the code for GetPositions for an example.

0001 function output = GetCustomDefaults(current,property,value)
0002 
0003 %GetCustomDefaults - Get custom default value for a given function property.
0004 %
0005 %  This is an 'internal' function used by FMAToolbox. You should not need
0006 %  to use it, unless you are developping new functions for this toolbox.
0007 %
0008 %  See Example below.
0009 %
0010 %  WARNING
0011 %
0012 %    Custom defaults should be allowed with great care, because they *implicitly*
0013 %    change the default behavior of functions: because the actual function call
0014 %    does not make it explicit that default values are being overriden, the same
0015 %    code can yield different results for different users, or even for the same
0016 %    user before and after she/he changes the custom defaults.
0017 %
0018 %  USAGE
0019 %
0020 %    output = GetCustomDefaults(current,property,value)
0021 %
0022 %    current        current value
0023 %    property       property name
0024 %    value          default value if custom default value is undefined
0025 %
0026 %  EXAMPLE
0027 %
0028 %    The function GetPositions has optional property-value pairs, including:
0029 %
0030 %     - 'mode' (default value 'clean')
0031 %     - 'coordinates' (default value 'normalized')
0032 %     - 'pixel' (no default value)
0033 %     - 'distances' (default value [0 Inf])
0034 %
0035 %    Users may want to change default values, e.g. have 'coordinates'
0036 %    set to 'video' whenever they call GetPositions without an explicit
0037 %    value. GetPositions therefore includes the following code:
0038 %
0039 %      % Default values (customizable defaults must be empty at this point)
0040 %      c = '';
0041 %
0042 %      % Parse parameters
0043 %      (possibly set a value for c, if supplied among optional input parameters)
0044 %
0045 %      % Customizable defaults
0046 %      c = GetCustomDefaults(c,'coordinates','normalized');
0047 %
0048 %    GetCustomDefaults will first test if c was already set (non-empty), in which
0049 %    case c will remain unaltered. Otherwise, it will test if there is a user-defined
0050 %    default value for 'coordinates', and issue a warning and set c to this value if
0051 %    it exists, or set it to 'normalized' otherwise.
0052 %
0053 %    To define a custom default value, users would have to e.g. add the following
0054 %    lines to their startup.m file:
0055 %
0056 %     global SETTINGS;
0057 %     SETTINGS.GetPositions.coordinates = 'video';
0058 %
0059 %  NOTE
0060 %
0061 %    Do not forget to document when the default value for a property can be customized.
0062 %    See the code for GetPositions for an example.
0063 
0064 
0065 % Copyright (C) 2010-2016 by Michaël Zugaro
0066 %
0067 % This program is free software; you can redistribute it and/or modify
0068 % it under the terms of the GNU General Public License as published by
0069 % the Free Software Foundation; either version 3 of the License, or
0070 % (at your option) any later version.
0071 
0072 if nargin == 2,
0073     % Backward compatibility for former usage: output = GetCustomDefaults(property,value)
0074     value = property;
0075     property = current;
0076     warning('Deprecated usage (type ''help <a href="matlab:help GetCustomDefaults">GetCustomDefaults</a>'' for details).');
0077 else
0078     % Non-empty input
0079     if ~isempty(current),
0080         output = current;
0081         return
0082     end
0083 end
0084 
0085 % Default value
0086 output = value;
0087 
0088 % Find out calling function name
0089 stack = dbstack;
0090 if length(stack) < 2, error('Stack error (sorry, cannot be more explicit)'); end
0091 functionName = stack(2).name;
0092 
0093 % Look for custom default
0094 global SETTINGS;
0095 if ~exist('SETTINGS'), return; end
0096 if ~isfield(SETTINGS,functionName), return; end
0097 p = getfield(SETTINGS,functionName);
0098 if ~isfield(p,property), return; end
0099 output = getfield(p,property);
0100 
0101 % Warn user
0102 if isdvector(output),
0103     d =  sprintf('%g ',output);
0104     d = d(1:end-1);
0105     if length(output) ~= 1,
0106         d = ['[' d '] '];
0107     else
0108         d = [d ' '];
0109     end
0110 elseif isastring(output),
0111     d = ['''' output ''' '];
0112 else
0113     d = '';
0114 end
0115 warning('FMAToolbox:GetCustomDefaults:UsingCustomDefaults',['Using custom default value ' d 'for ''' property ''' in function ''' functionName '''.']);
0116