From bb118c0fbea19886c19222512e36cfe37a45270a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dominik=20Pant=C5=AF=C4=8Dek?= Date: Mon, 20 Mar 2023 21:33:05 +0100 Subject: [PATCH] Document the listing module. --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/README.md b/README.md index 3d0007c..1b3afe0 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,9 @@ Functional Modules Support Modules --------------- +There modules are not specific to this project but had to be +implemented anyway to not require any external dependencies. + ### ANSI ### Command Line parsing @@ -88,6 +91,43 @@ Support Modules ### Listing +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) + +* ```lines``` - list of string representing lines of the text file +* ```highlights``` - list of highlights (see below) +* ```context``` - number of context lines to be shown around highlighted lies +* ```hl-pre``` - string introducing highlighted lines +* ```hl-post``` - string terminating highlighted lines +* ```ctx-pre``` - string introducing context lines +* ```ctx-post``` - string terminating context lines +* ```ellipsis``` - string representing lines omitted from the output + +Prints given text file represented by the ```lines``` list of strings. + +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 +```hl-pre``` string and the highlight is finished by appending +```hl-post``` to them. Usually some constants from the ```ansi``` +module are used. + +If some lines are highlighted a number of ```context``` lines +surrounding them may be printed as well. If this argument is negative, +all non-highlighted lines are printed as context lines. + +Context lines are prepended with ```ctx-pre``` string and terminated +by ```ctx-post``` string. + +If some lines between highlight and/or context lines are omitted, +```ellipsis``` string is printed on single line as a substitute. + + ### Progress Provides syntax forms and procedures for showing progress of a