function progress_line=cosmo_show_progress(clock_start, ratio_done, msg, prev_progress_line)
% Shows a progress bar, and time elapsed and expected to complete.
%
% progress_line=cosmo_show_progress(clock_start, progress[, msg[, prev_progress_line]])
%
% Inputs:
% clock_start The time the task started (from clock()).
% ratio_done 0 <= ratio_done <= 1, where 0 means nothing
% completed and 1 means fully completed.
% msg String with a message to be shown next to the
% progress bar (optional).
% prev_progress_line The output from the previous call to this
% function, if applicable (optional). If provided
% then invoking this function prefixes the output
% with numel(prev_progress_msg) backspace characters,
% which deletes the output from the previous call
% from the console. In other words, this allows for
% showing a progress message at a fixed location in
% the console window.
%
% Output:
% progress_line String indicating current progress using a bar,
% with time elapsed and expected time to complete
% (using linear extrapolation).
%
% Notes:
% - As a side effect of this function, progress_msg is written to standard
% out (the console).
% - The use of prev_progress_line may not work properly if output is
% written to standard out without using this function.
%
% Example:
% % this code takes just over 3 seconds to run, and fills a progress bar.
% prev_msg='';
% clock_start=clock();
% for k=1:100
% pause(.03);
% status=sprintf('done %.1f%%', k);
% ratio_done=k/100;
% prev_msg=cosmo_show_progress(clock_start,ratio_done,status,prev_msg);
% end
% % output:
% > +00:00:03 [####################] -00:00:00 done 100.0%
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
