From f870430cf1fcd31c7b9a7d1ff4624af6e93c6d3e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dominik=20Pant=C5=AF=C4=8Dek?=
 <dominik.pantucek@trustica.cz>
Date: Mon, 20 Mar 2023 21:02:05 +0100
Subject: [PATCH] Document the progress module.

---
 README.md    | 35 +++++++++++++++++++++++++++++++++++
 progress.scm |  9 ++++++---
 2 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 1684ed5..3d0007c 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,41 @@ Support Modules
 
 ### Progress
 
+Provides syntax forms and procedures for showing progress of a
+process.
+
+    (with-progress echo? pre post body ...)
+
+* ```echo?``` - flag enabling progress output
+* ```pre``` - string to be printed at start
+* ```post``` - string to be printed after finish
+* ```body ...``` - expressions of the process tracked
+
+Displays process progress starting with the ```pre``` string, adding
+arbitrary string to the output using the ```progress-advance``` during
+each and every step. If the process reaches its finish, the output
+line is finished with the ```post``` string and cursor is moved to new
+line.
+
+During the steps, the whole line is always refreshed when the progress
+gets updated.
+
+If ```echo?``` is ```#f``` (false), nothing is output.
+
+    (progress-advance [str])
+
+* ```str``` - string to add to progress, defaults to "."
+
+Adds given string to current progress and refreshes the progress
+line. Must be evaluated within ```with-progress``` expression.
+
+    (progress-break body ...)
+
+* ```body ...``` - arbitrary expressions to be evaluated
+
+Evaluates the ```body ...``` expressions. Hides current progress line
+before the evaluation and redisplays it when finished.
+
 ### Testing
 
 This module provides simple syntax forms for (unit) testing of other
diff --git a/progress.scm b/progress.scm
index bc2d4fa..edec25b 100644
--- a/progress.scm
+++ b/progress.scm
@@ -50,10 +50,13 @@
        (display (sprintf "\r\x1b[K~A" cp)))))
 
  ;; Adds something to current progress and refreshes the display.
- (define (progress-advance str)
+ (define (progress-advance . args)
    (when (*current-progress*)
-     (*current-progress* (string-append (*current-progress*) (sprintf "~A" str)))
-     (print-current-progress)))
+     (let ((str (if (null? args)
+		    "."
+		    (car args))))
+       (*current-progress* (string-append (*current-progress*) (sprintf "~A" str)))
+       (print-current-progress))))
 
  ;; Runs given procedure within progress environment
  (define (run-with-progress echo? pre-msg post-msg thunk)