CachedLoadParameters(ScriptFile,CacheOption)

function CachedLoadParameters(ScriptFile,CacheOption)
% CachedLoadParameters - Load model parameters using MAT file cache
% -------------------------------------------------------------------------
% Abstract: This function loads parameters to the base workspace from the
%           specified M-script using a cached MAT file.  If the MAT file is
%           newer than this M-file, then the cached MAT file version will
%           be used for efficiency. Otherwise, the entire M-file
%           initialization will run, and the MAT file cache will be
%           rebuilt.
%
% Syntax:
%           CachedLoadParameters(ScriptFile)
%           CachedLoadParameters(ScriptFile,CacheOption)
%
% Inputs:
%           ScriptFile - name or full path of a script file used to
%                        initialize workspace parameters
%           CacheOption - can be one of the following strings:
%               'internal'   - load from cache if MAT file timestamp is 
%                              newer than M-file (default)
%               'cache'      - load from MAT file cache
%               'buildcache' - load from M-file and rebuild MAT file cache
%               'edit'       - edit the M-file
%
% Outputs:
%           none
%
% Examples:
%   Assuming a model has a parameter loading script called
%   "MyModel_LoadParameters.m", you could use the following syntax:
%
%           CachedLoadParameters('MyModel_LoadParameters');
%           CachedLoadParameters('MyModel_LoadParameters','internal')
%           CachedLoadParameters('MyModel_LoadParameters','cache')
%           CachedLoadParameters('MyModel_LoadParameters','buildcache')
%           CachedLoadParameters('MyModel_LoadParameters','edit')
%
% Notes: none
%

% Copyright 2007 - 2009 The MathWorks, Inc.
%
% Auth/Revision:
%   The MathWorks Consulting Group
%   $Author: rjackey $
%   $Revision: 7 $  $Date: 2007-05-07 11:09:42 -0400 (Mon, 07 May 2007) $
% -------------------------------------------------------------------------

% Check input arguments
if nargin < 1
    error('No ScriptFile was specified');
elseif nargin < 2
    CacheOption = 'internal';
end

% Get the path to this M-file, and the cache MAT file
[MFileName,MATFileName] = i_GetFilePaths(ScriptFile);

% Determine which option was used
switch CacheOption
    
    case 'internal'
        
        % Check whether the cache MAT file is up to date
        if ~i_CacheUpToDate(MFileName,MATFileName)
           i_BuildCache(MFileName,MATFileName);
        end
        i_LoadCache(MATFileName);
            
    case 'cache'
        
        % Load from cache MAT file regardless of timestamps
        i_LoadCache(MATFileName);
        
    case 'buildcache'
        
        % Rebuild MAT file cache regardless of timestamps
        i_BuildCache(MFileName,MATFileName);
        i_LoadCache(MATFileName);
        
    case 'edit'
        
        % Just open the M-file for editing
        edit(MFileName);
        
    otherwise
        error('Invalid CacheOption');
end
    

% ----------------------------------------------------------------------- %
%% Subfunction i_CacheUpToDate
% ----------------------------------------------------------------------- %
% This function returns true if the cached MATFile exists and the timestamp
% is more recent than the MFile
function Result = i_CacheUpToDate(MFile,MATFile)

% Get file info with timestamps
MFileInfo = dir(MFile);
MATFileInfo = dir(MATFile);

% Check the existance of MATFile and the datestamps
if ~isempty(MATFileInfo) && (datenum(MATFileInfo.date) > datenum(MFileInfo.date))
    Result = true;
else
    Result = false;
end


% ----------------------------------------------------------------------- %
%% Subfunction i_LoadCache
% ----------------------------------------------------------------------- %
% This function loads the specified MAT file into the base workspace.
function i_LoadCache(MATFile)

evalin('base',sprintf('load(''%s'');',MATFile));


% ----------------------------------------------------------------------- %
%% Subfunction i_BuildCache
% ----------------------------------------------------------------------- %
% This function initializes parameters and saves them to the specified MAT
% file.  
function i_BuildCache(MFile,MATFile)

run(MFile);

% Get a list of parameters, minus 'MFile' and 'MATFile'
ParamNames = who;
ParamNames = ParamNames(~ismember(ParamNames,{'MFile','MATFile'}));

% Verify that if the the MATFile exists, it is writable
[Status,MATFileAttrib] = fileattrib(MATFile);
if Status == true && MATFileAttrib.UserWrite ~= 1
    error('File is read-only: %s',MATFile);
end

% Save the parameters to MAT file cache
save(MATFile,ParamNames{:});


% ----------------------------------------------------------------------- %
%% Subfunction i_GetFilePaths
% ----------------------------------------------------------------------- %
% This function returns the full path of the M-file script and the cache
% MAT file
function [MFileName,MATFileName] = i_GetFilePaths(ScriptFile)

% Check for the existance of the script as an M-file
if exist(ScriptFile,'file') == 2

    % Get the full path of the ScriptFile
    MFileName = which(ScriptFile);

    % Now replace the extension with .mat to form the cache file name
    MATFileName = regexprep(MFileName,'.m$','_cache.mat');

else
    error(['The specified script file was not an M-file found on the MATLAB path:' ScriptFile]);
end