StartDiaryFile (LogFile, RefFile)

function CheckDiaryFile = StartDiaryFile (LogFile, RefFile)
% This routine is used for test scripts. All output from the test script is
% written to the log file. Using the internal companion routine CheckDiaryFile,
% the log file is compared with the reference file. This routine returns a
% pointer to the routine CheckDiaryFile.
%
% StartDiaryFile:
% 1(a) If the log file name is empty, only the output format parameters are
%      changed.
%  (b) If the log file name is not empty, the Matlab diary is redirected to the
%      log file.
% 2. Save the current output format parameters. Set the output format to
%    'short' and 'compact'.
% 3. Return a pointer to the routine CheckDiaryFile. The saved format parameters
%    and the file names are available to CheckDiaryFile.
%
% CheckDiaryFile:
% 1. Close the diary file if it was invoked.
% 2. Reset the output formatting to the settings prior to calling SetDiaryFile.
% 3(a) If the log file name is empty, no further action is taken.
%  (b) If the reference file name is empty, the log file is retained.
%  (c) If the log file name is the same as the reference file name, the file
%      is retained as the reference file, overwriting the reference file if it
%      exists.
%  (d) If the log file name differs from the reference file name, the contents
%      of these files are compared using the system file comparison tool.
%      (i) If the log file extension is ".ref", the log file is retained.
%      (ii) If the log file extension is not ".ref", the log file is deleted.
%
% StartDiaryFile should be called at the beginning of the test script and
% CheckDiaryFile should be called at the end of the test script.
%   CheckDiaryFile = StartDiaryFile(LogFile, RefFile)
%   ...
%   CheckDiaryFile();

% $Id: StartDiaryFile.m,v 1.6 2009/09/16 16:50:27 pkabal Exp $

if (nargin < 1)
  LogFile = [];
end
if (nargin < 2)
  RefFile = [];
end

if (~ isempty(LogFile))
  diary off;
  if (~isempty(ls(LogFile)))
    delete(LogFile);  % If it exists, we don't want to append to it
  end
  diary(LogFile);
end

DFormat = get(0, 'Format');
DFormatSpacing = get(0, 'FormatSpacing');
format;         % Set to default format (short)
format compact  % Change format spacing to compact

CheckDiaryFile = @Check_DiaryFile;

return

% ----- begin nested function

  function Check_DiaryFile ()
  % This function compares a log file with a reference file. It is the
  % companion function to SetDiaryFile. The parameters are inherited from
  % StartDiaryFile.
  %
  % 1. Close the diary file if it was invoked.
  % 2. Reset the output formatting to the settings prior to calling
  %    SetDiaryFile.
  % 3(a) If the log file name is empty, no further action is taken.
  %  (b) If the reference file name is empty, the log file is retained.
  %  (c) If the log file name is the same as the reference file name, the
  %      file is retained as the reference file, overwriting the reference
  %      file if it exists.
  %  (d) If the log file name differs from the reference file name, the
  %      contents of these files are compared using the system file comparison
  %      tool.
  %      (i) If the log file extension is ".ref", the log file is retained.
  %      (ii) If the log file extension is not ".ref", the log file is deleted.
  % Note that when Matlab displays the contents of a matrix, the number of
  % elements displayed per line depends on the width of the Matlab command
  % window. This means that a comparison of diary files may show differences
  % when the numerical values are unchanged. The workaround is to print
  % matrices using formatted I/O.

  if (~isempty(LogFile))
    diary off;
  end

  % Restore formating
  set(0, 'Format', DFormat);
  set(0, 'FormatSpacing', DFormatSpacing);

  if (~ isempty(LogFile))
    fprintf('\n***** ***** ***** *****\n');
    if (isempty(RefFile))
      fprintf('Saved log file: %s\n', LogFile);
    elseif (isempty(ls(RefFile)))
      fprintf('No reference file, saved log file: %s\n', LogFile);
    elseif (~ strcmp(LogFile, RefFile))
      if (ispc)
        eval(['!FC ', LogFile, ' ', RefFile]);
      else
        eval(['!diff ', LogFile, ' ', RefFile]);
      end
      [pathstr, name, ext] = fileparts(LogFile);
      if (strcmp(ext, '.ref'))
        fprintf('Saved log file: %s\n', LogFile);
      else
        delete(LogFile);
      end
    else
      fprintf('New reference file: %s\n', RefFile);
    end
  end

  return
  end
% ----- end nested function

end