From ba874bc953647dcf6bfd309bafd900b654677883 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dominik=20Pant=C5=AF=C4=8Dek?= Date: Thu, 30 Mar 2023 21:32:30 +0200 Subject: [PATCH] Update documentation of progress and listing modules. --- MODULES.md | 54 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 44 insertions(+), 10 deletions(-) diff --git a/MODULES.md b/MODULES.md index 280cfc0..85f3cc8 100644 --- a/MODULES.md +++ b/MODULES.md @@ -30,13 +30,6 @@ current month derived from the current system time. How many lines of context are to be shown in source file listing. Mainly used by the member file module parser and processor. - (*member-default-joined* [month]) - -* ```month``` - valid month as produced by the ```month``` module - -If the member file does not contain the ```joined``` key, this value -is substituted as a default. - (*member-suspend-max-months* [number]) * ```number``` - number of months (nonnegative integer) @@ -506,10 +499,20 @@ This module implements listing a text file with line numbers and optional highlights of given source lines, optionally with comments for those lines. - (print-source-listing lines highlights context hl-pre hl-post ctx-pre ctx-post ellipsis) + (print-source-listing lines highlights + [#:highligh-rules `((error ,(ansi #:bold #:red) ,(ansi #:default)) + (warning ,(ansi #:yellow) ,(ansi #:default)) + (info ,(ansi #:cyan) ,(ansi #:default)))] + [#:ellipsis "..."] + [#:context 3] + [#:hl-pre ""] + [#:hl-post ""] + [#:ctx-pre ""] + [#:ctx-post ""]) * ```lines``` - list of string representing lines of the text file * ```highlights``` - list of highlights (see below) +* ```highlight-rules``` - assq rules for highlight types pre and post * ```context``` - number of context lines to be shown around highlighted lies * ```hl-pre``` - string introducing highlighted lines * ```hl-post``` - string terminating highlighted lines @@ -523,10 +526,11 @@ Lines to be highlighted can be specified in the ```highlights``` list. The highlight specification is either a number or a list containing the line number and string comment. -The lines are actually highlighted by prepending them with +By default the lines are actually highlighted by prepending them with ```hl-pre``` string and the highlight is finished by appending ```hl-post``` to them. Usually some constants from the ```ansi``` -module are used. +module are used. If the highlight type is found in +```highlight-rules```, given pre/post strings are used instead. If some lines are highlighted a number of ```context``` lines surrounding them may be printed as well. If this argument is negative, @@ -576,6 +580,36 @@ line. Must be evaluated within ```with-progress``` expression. Evaluates the ```body ...``` expressions. Hides current progress line before the evaluation and redisplays it when finished. + (*progress%-width* [width]) + +* ```width``` - width of the progress bar + +Parameter configuring the progress% bar size. + + (*progress%-step* [step]) + +* ```step``` - minimal step before re-drawing the bar + +Parameter configuring the minimal step before the current progress% +bar is redrawn. The progress value is a number from 0 to 1 and the +step must be specified on the same scale. + + (with-progress% echo? name body ...) + +* ```echo?``` - flag enabling progress output +* ```name``` - name to be used at the end of progress line +* ```body ...``` - expressions to be evaluated while tracking progress% + +Displays progress while the ```body ...``` is evaluated. Current +progress% value must be updated with ```progress%-advance```. + + (progress%-advance new-value) + +* ```new-value``` - new value of progress + +If the new-value differs from last value shown more than +```(*progress%-step*)```, redisplays the current progress%. + ### Testing This module provides simple syntax forms for (unit) testing of other