Split support modules documentation.
This commit is contained in:
parent
53b845dd66
commit
54263d48e1
2 changed files with 411 additions and 406 deletions
406
doc/modules.md
406
doc/modules.md
|
|
@ -572,409 +572,3 @@ prime number.
|
|||
(gen-all-4digit-primes)
|
||||
|
||||
Returns a list of all 4-digit prime numbers.
|
||||
|
||||
Generic Support Modules
|
||||
-----------------------
|
||||
|
||||
These modules are not specific to this project but had to be
|
||||
implemented anyway to not require any external dependencies.
|
||||
|
||||
### ANSI
|
||||
|
||||
A simple module for creating ANSI (ECMA-48) sequence strings.
|
||||
|
||||
(ansi . args)
|
||||
|
||||
* ```args``` - a list of color/style keywords
|
||||
|
||||
Produces an ANSI CSI (Control Sequence Introducer) SGR (Select Graphic
|
||||
Rendition) strings with given attributes (re)set.
|
||||
|
||||
It understands the following keywords:
|
||||
|
||||
* ```#:black``` - black text foreground color
|
||||
* ```#:red``` - red text foreground color
|
||||
* ```#:green``` - green text foreground color
|
||||
* ```#:yellow``` - yellow text foreground color
|
||||
* ```#:blue``` - blue text foreground color
|
||||
* ```#:magenta``` - magenta text foreground color
|
||||
* ```#:cyan``` - cyan text foreground color
|
||||
* ```#:white``` or ```#:grey``` - white (grey) text foreground color
|
||||
* ```#:brightblack``` or ```#:darkgrey```- dark grey (bright black) text foreground color
|
||||
* ```#:brightred``` - bright red text foreground color
|
||||
* ```#:brightgreen``` - bright green text foreground color
|
||||
* ```#:brightyellow``` - bright yellow text foreground color
|
||||
* ```#:brightblue``` - bright blue text foreground color
|
||||
* ```#:brightmagenta``` or ```#:pink``` - pink (bright magenta) text foreground color
|
||||
* ```#:brightcyan``` - bright cyan text foreground color
|
||||
* ```#:brightwhite``` - bright white (real white) text foreground color
|
||||
* ```#:bgblack``` - black text background color
|
||||
* ```#:bgred``` - red text background color
|
||||
* ```#:bggreen``` - green text background color
|
||||
* ```#:bgyellow``` - yellow text background color
|
||||
* ```#:bgblue``` - blue text background color
|
||||
* ```#:bgmagenta``` - magenta text background color
|
||||
* ```#:bgcyan``` - cyan text background color
|
||||
* ```#:bgwhite``` or ```#:bggrey``` - white (grey) text background color
|
||||
* ```#:bgbrightblack``` or ```#:darkgrey```- dark grey (bright black) text background color
|
||||
* ```#:bgbrightred``` - bright red text background color
|
||||
* ```#:bgbrightgreen``` - bright green text background color
|
||||
* ```#:bgbrightyellow``` - bright yellow text background color
|
||||
* ```#:bgbrightblue``` - bright blue text background color
|
||||
* ```#:bgbrightmagenta``` or ```#:pink``` - pink (bright magenta) text background color
|
||||
* ```#:bgbrightcyan``` - bright cyan text background color
|
||||
* ```#:bgbrightwhite``` - bright white (real white) text background color
|
||||
* ```#:default``` - reset all attributes to terminal defaults
|
||||
* ```#:bold``` - bold font (and/or bright foreground color on some terminals)
|
||||
|
||||
The order is important as the ```#:default``` resets all attributes
|
||||
given even in the same attribute list.
|
||||
|
||||
a:error
|
||||
|
||||
Used to signal errors. Defaults to red bold text.
|
||||
|
||||
a:warning
|
||||
|
||||
Used to signal non-fatal warnings. Defaults to regular yellow text.
|
||||
|
||||
a:success
|
||||
|
||||
Signals success of an operation. Defaults to bold green text.
|
||||
|
||||
a:neutral
|
||||
|
||||
Used for generic text. Defaults to regular white (grey) text.
|
||||
|
||||
a:default
|
||||
|
||||
Special style which just resets the terminal output attributes to
|
||||
terminal defaults.
|
||||
|
||||
a:muted
|
||||
|
||||
Used for displaying the text "muted" (dimmed). Defaults to bold/bright
|
||||
black text.
|
||||
|
||||
a:highlight
|
||||
|
||||
Generic highlight of given text. Defaults to bold blue text.
|
||||
|
||||
(ansi-string-length str)
|
||||
|
||||
* ```str``` - string that may contain ANSI CSI SGR sequences
|
||||
|
||||
Returns the string length in characters without any ANSI CSI SGR
|
||||
sequences contained.
|
||||
|
||||
(ansi-paragraph-format str width)
|
||||
|
||||
* ```str``` - a string that may contain ANSI CSI SGR sequences
|
||||
* ```width``` - a number representing themaximum number of characters per line
|
||||
|
||||
If the string ```str``` is longer than the supplied ```width```,
|
||||
splits it into multiple lines on word boundaries to wrap it
|
||||
nicely. The resulting string is free of ANSI CSI SGR sequences and may
|
||||
contain newline characters.
|
||||
|
||||
(ansi-string . args)
|
||||
|
||||
* ```args``` - a list of strings and/or ANSI keywords
|
||||
|
||||
Returns a string created by appending all the strings given and
|
||||
```ansi``` function produced ones with consecutive keywords passed to
|
||||
single ```ansi``` evaluation.
|
||||
|
||||
(clrscr)
|
||||
|
||||
Clears the terminal screen and places the cursor in the top left
|
||||
corner.
|
||||
|
||||
### Command Line parsing
|
||||
|
||||
Generic syntax-based implementation of command-line options parsing
|
||||
with focus on generated help and ergonomic binding of option
|
||||
arguments.
|
||||
|
||||
(command-line print-help (opt (args ...) help body ...) ...)
|
||||
|
||||
* ```print-help``` - identifier binding for the help printing procedure
|
||||
* ```opt``` - command-line option name as identifier (unquoted symbol)
|
||||
* ```args ...``` - optional arguments of given option
|
||||
* ```help``` - help string for this option
|
||||
* ```body ...``` - expressions to be evaluated upon option match
|
||||
|
||||
Parses command-line arguments based on the specification given. If
|
||||
evaluated inside ```csi``` script, only options and arguments after
|
||||
the ```--``` meta-option are parsed. If evaluated inside compiled
|
||||
binary, all arguments are parsed as usual.
|
||||
|
||||
Each option is represented by the ```opt``` option identifier
|
||||
(unquoted symbol), optional arguments ```args``` which become bound in
|
||||
the option specification ```body ...``` expressions, help string and
|
||||
the actual expressions to be evaluated when the option (and possibly
|
||||
its arguments) match.
|
||||
|
||||
If an option is encountered on the command-line and not enough
|
||||
arguments (according to the option specification) are provided for it,
|
||||
an exception is raised.
|
||||
|
||||
Within any of the ```body ...``` expressions the ```print-help```
|
||||
procedure can be used to print the options, their argument names and
|
||||
help strings in a nice, human-readable format.
|
||||
|
||||
### 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
|
||||
[#: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
|
||||
* ```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 a list containing the following:
|
||||
|
||||
* line number (number)
|
||||
* message (string)
|
||||
* pass stage (number)
|
||||
* type (symbol)
|
||||
|
||||
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. 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,
|
||||
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
|
||||
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.
|
||||
|
||||
(*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
|
||||
modules.
|
||||
|
||||
(run-tests name body ...)
|
||||
|
||||
* ```name``` - identifier describing the module being tested
|
||||
* ```body ...``` - test expressions
|
||||
|
||||
Runs all tests specified on the ```body ...```. Firstly it prints
|
||||
"[test] name " at the beginning of the line. Secondly it runs all
|
||||
tests, printing "." for each test successfully passed. If all tests
|
||||
pass, prints " ok." and moves the cursor to the next line.
|
||||
|
||||
In case any of the tests fails, exception is raised and program
|
||||
terminates.
|
||||
|
||||
(test-eq? name expression expected-result)
|
||||
|
||||
* ```name``` - identifier representing the name of the test
|
||||
* ```expression``` - expression to be evaluated
|
||||
* ```expected-result``` - expected result of the test expression
|
||||
|
||||
Evaluates the test ```expression``` and compares the result with
|
||||
```expected-result``` using ```eq?```. If the comparison fails, an
|
||||
exception is raised with the ```name``` of the test added to the
|
||||
exception. If the test passes, prints "." like all tests from this
|
||||
module do.
|
||||
|
||||
(test-equal? name expression expected-result)
|
||||
|
||||
* ```name``` - identifier representing the name of the test
|
||||
* ```expression``` - expression to be evaluated
|
||||
* ```expected-result``` - expected result of the test expression
|
||||
|
||||
Evaluates the test ```expression``` and compares the result with
|
||||
```expected-result``` using ```equal?```. If the comparison fails, an
|
||||
exception is raised with the ```name``` of the test added to the
|
||||
exception. If the test passes, prints "." like all tests from this
|
||||
module do.
|
||||
|
||||
(test-true name expression)
|
||||
|
||||
* ```name``` - identifier representing the name of the test
|
||||
* ```expression``` - expression to be evaluated
|
||||
|
||||
Evaluates the test ```expression``` and checks whether the result is
|
||||
```#t``` (true). An exception is raised if it is not with the
|
||||
```name``` of the test added to the exception. If the test passes,
|
||||
prints "." like all tests from this module do.
|
||||
|
||||
(test-false name expression)
|
||||
|
||||
* ```name``` - identifier representing the name of the test
|
||||
* ```expression``` - expression to be evaluated
|
||||
|
||||
Evaluates the test ```expression``` and checks whether the result is
|
||||
```#f``` (false). An exception is raised if it is not with the
|
||||
```name``` of the test added to the exception. If the test passes,
|
||||
prints "." like all tests from this module do.
|
||||
|
||||
(test-exn name expression)
|
||||
|
||||
* ```name``` - identifier representing the name of the test
|
||||
* ```expression``` - expression to be evaluated
|
||||
|
||||
Evaluates the test ```expression``` and checks whether it raised an
|
||||
exception. An exception is raised if no exception was raised during
|
||||
the evaluation. If the test passes, prints "." like all tests from
|
||||
this module do.
|
||||
|
||||
### Table
|
||||
|
||||
This module provides moderately complex terminal table rendering.
|
||||
|
||||
(*table-border-style* [style])
|
||||
|
||||
* ```style``` - symbol representing the style
|
||||
|
||||
Valid styles are:
|
||||
|
||||
* ```'debug``` - special style to see any rendering problems
|
||||
* ```'ascii``` - plain ASCII (7-bit)
|
||||
* ```'unicode``` - nice box-drawing table (UTF-8)
|
||||
|
||||
If invalid style is provided, ```'debug``` style is automatically
|
||||
substituted.
|
||||
|
||||
(table->string tbl
|
||||
[#:table-border #f]
|
||||
[#:row-border #f]
|
||||
[#:col-border #f]
|
||||
[#:row0-border #f]
|
||||
[#:col0-border #f]
|
||||
[#:border-style (*table-border-style*)]
|
||||
[#:ansi #f])
|
||||
|
||||
* ```tbl``` - list of lists with cell data
|
||||
* ```#:table-border``` - if ```#t```, the table has outer border
|
||||
* ```#:row-border``` - if ```#t```, the rows are separated by borders
|
||||
* ```#:col-border``` - if ```#t```, the columns are separated by borders
|
||||
* ```#:row0-border``` - if ```#t```, the first row is separated by border
|
||||
* ```#:col0-border``` - if ```#t```, the first column is separated by border
|
||||
* ```#:border-style``` - which border style to use (see
|
||||
```*table-border-style*``` which is the default)
|
||||
* ```#:ansi``` - if ```#t```, all cell line strings are terminated
|
||||
with ```a:default```
|
||||
|
||||
The table ```tbl``` is represented as a list of rows where each row is
|
||||
a list of cells that hold arbitrary values that are converted to
|
||||
string when rendering the table.
|
||||
|
||||
Before rendering the table, the following steps are performed:
|
||||
|
||||
* The table is made rectangular - that is all rows are extended by
|
||||
empty strings to have the same length.
|
||||
* All non-string cells are converted to string using ```sprintf```
|
||||
* All cells are split into list of strings representing the lines of
|
||||
text inside them.
|
||||
* For each row, all cells are extended by empty strings to have
|
||||
matching number of lines of text inside them.
|
||||
* For each column, all lines of text inside all of the cells are
|
||||
padded with spaces to have uniform width.
|
||||
|
||||
Then each table row is converted to list of strings adding column
|
||||
separators and table borders as required. These lists are then joined
|
||||
with row separators and possibly prefixed and suffixed by top and
|
||||
bottom table border.
|
||||
|
||||
The resulting list of strings is joined with newline character as the
|
||||
separator.
|
||||
|
||||
### Environment
|
||||
|
|
|
|||
411
doc/support.md
Normal file
411
doc/support.md
Normal file
|
|
@ -0,0 +1,411 @@
|
|||
Support Modules
|
||||
===============
|
||||
|
||||
These modules are not specific to this project but had to be
|
||||
implemented anyway to not require any external dependencies.
|
||||
|
||||
The Modules
|
||||
-----------
|
||||
|
||||
The modules have no unified naming convention as the modules have not
|
||||
much in common.
|
||||
|
||||
### ANSI
|
||||
|
||||
A simple module for creating ANSI (ECMA-48) sequence strings.
|
||||
|
||||
(ansi . args)
|
||||
|
||||
* ```args``` - a list of color/style keywords
|
||||
|
||||
Produces an ANSI CSI (Control Sequence Introducer) SGR (Select Graphic
|
||||
Rendition) strings with given attributes (re)set.
|
||||
|
||||
It understands the following keywords:
|
||||
|
||||
* ```#:black``` - black text foreground color
|
||||
* ```#:red``` - red text foreground color
|
||||
* ```#:green``` - green text foreground color
|
||||
* ```#:yellow``` - yellow text foreground color
|
||||
* ```#:blue``` - blue text foreground color
|
||||
* ```#:magenta``` - magenta text foreground color
|
||||
* ```#:cyan``` - cyan text foreground color
|
||||
* ```#:white``` or ```#:grey``` - white (grey) text foreground color
|
||||
* ```#:brightblack``` or ```#:darkgrey```- dark grey (bright black) text foreground color
|
||||
* ```#:brightred``` - bright red text foreground color
|
||||
* ```#:brightgreen``` - bright green text foreground color
|
||||
* ```#:brightyellow``` - bright yellow text foreground color
|
||||
* ```#:brightblue``` - bright blue text foreground color
|
||||
* ```#:brightmagenta``` or ```#:pink``` - pink (bright magenta) text foreground color
|
||||
* ```#:brightcyan``` - bright cyan text foreground color
|
||||
* ```#:brightwhite``` - bright white (real white) text foreground color
|
||||
* ```#:bgblack``` - black text background color
|
||||
* ```#:bgred``` - red text background color
|
||||
* ```#:bggreen``` - green text background color
|
||||
* ```#:bgyellow``` - yellow text background color
|
||||
* ```#:bgblue``` - blue text background color
|
||||
* ```#:bgmagenta``` - magenta text background color
|
||||
* ```#:bgcyan``` - cyan text background color
|
||||
* ```#:bgwhite``` or ```#:bggrey``` - white (grey) text background color
|
||||
* ```#:bgbrightblack``` or ```#:darkgrey```- dark grey (bright black) text background color
|
||||
* ```#:bgbrightred``` - bright red text background color
|
||||
* ```#:bgbrightgreen``` - bright green text background color
|
||||
* ```#:bgbrightyellow``` - bright yellow text background color
|
||||
* ```#:bgbrightblue``` - bright blue text background color
|
||||
* ```#:bgbrightmagenta``` or ```#:pink``` - pink (bright magenta) text background color
|
||||
* ```#:bgbrightcyan``` - bright cyan text background color
|
||||
* ```#:bgbrightwhite``` - bright white (real white) text background color
|
||||
* ```#:default``` - reset all attributes to terminal defaults
|
||||
* ```#:bold``` - bold font (and/or bright foreground color on some terminals)
|
||||
|
||||
The order is important as the ```#:default``` resets all attributes
|
||||
given even in the same attribute list.
|
||||
|
||||
a:error
|
||||
|
||||
Used to signal errors. Defaults to red bold text.
|
||||
|
||||
a:warning
|
||||
|
||||
Used to signal non-fatal warnings. Defaults to regular yellow text.
|
||||
|
||||
a:success
|
||||
|
||||
Signals success of an operation. Defaults to bold green text.
|
||||
|
||||
a:neutral
|
||||
|
||||
Used for generic text. Defaults to regular white (grey) text.
|
||||
|
||||
a:default
|
||||
|
||||
Special style which just resets the terminal output attributes to
|
||||
terminal defaults.
|
||||
|
||||
a:muted
|
||||
|
||||
Used for displaying the text "muted" (dimmed). Defaults to bold/bright
|
||||
black text.
|
||||
|
||||
a:highlight
|
||||
|
||||
Generic highlight of given text. Defaults to bold blue text.
|
||||
|
||||
(ansi-string-length str)
|
||||
|
||||
* ```str``` - string that may contain ANSI CSI SGR sequences
|
||||
|
||||
Returns the string length in characters without any ANSI CSI SGR
|
||||
sequences contained.
|
||||
|
||||
(ansi-paragraph-format str width)
|
||||
|
||||
* ```str``` - a string that may contain ANSI CSI SGR sequences
|
||||
* ```width``` - a number representing themaximum number of characters per line
|
||||
|
||||
If the string ```str``` is longer than the supplied ```width```,
|
||||
splits it into multiple lines on word boundaries to wrap it
|
||||
nicely. The resulting string is free of ANSI CSI SGR sequences and may
|
||||
contain newline characters.
|
||||
|
||||
(ansi-string . args)
|
||||
|
||||
* ```args``` - a list of strings and/or ANSI keywords
|
||||
|
||||
Returns a string created by appending all the strings given and
|
||||
```ansi``` function produced ones with consecutive keywords passed to
|
||||
single ```ansi``` evaluation.
|
||||
|
||||
(clrscr)
|
||||
|
||||
Clears the terminal screen and places the cursor in the top left
|
||||
corner.
|
||||
|
||||
### Command Line parsing
|
||||
|
||||
Generic syntax-based implementation of command-line options parsing
|
||||
with focus on generated help and ergonomic binding of option
|
||||
arguments.
|
||||
|
||||
(command-line print-help (opt (args ...) help body ...) ...)
|
||||
|
||||
* ```print-help``` - identifier binding for the help printing procedure
|
||||
* ```opt``` - command-line option name as identifier (unquoted symbol)
|
||||
* ```args ...``` - optional arguments of given option
|
||||
* ```help``` - help string for this option
|
||||
* ```body ...``` - expressions to be evaluated upon option match
|
||||
|
||||
Parses command-line arguments based on the specification given. If
|
||||
evaluated inside ```csi``` script, only options and arguments after
|
||||
the ```--``` meta-option are parsed. If evaluated inside compiled
|
||||
binary, all arguments are parsed as usual.
|
||||
|
||||
Each option is represented by the ```opt``` option identifier
|
||||
(unquoted symbol), optional arguments ```args``` which become bound in
|
||||
the option specification ```body ...``` expressions, help string and
|
||||
the actual expressions to be evaluated when the option (and possibly
|
||||
its arguments) match.
|
||||
|
||||
If an option is encountered on the command-line and not enough
|
||||
arguments (according to the option specification) are provided for it,
|
||||
an exception is raised.
|
||||
|
||||
Within any of the ```body ...``` expressions the ```print-help```
|
||||
procedure can be used to print the options, their argument names and
|
||||
help strings in a nice, human-readable format.
|
||||
|
||||
### 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
|
||||
[#: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
|
||||
* ```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 a list containing the following:
|
||||
|
||||
* line number (number)
|
||||
* message (string)
|
||||
* pass stage (number)
|
||||
* type (symbol)
|
||||
|
||||
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. 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,
|
||||
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
|
||||
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.
|
||||
|
||||
(*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
|
||||
modules.
|
||||
|
||||
(run-tests name body ...)
|
||||
|
||||
* ```name``` - identifier describing the module being tested
|
||||
* ```body ...``` - test expressions
|
||||
|
||||
Runs all tests specified on the ```body ...```. Firstly it prints
|
||||
"[test] name " at the beginning of the line. Secondly it runs all
|
||||
tests, printing "." for each test successfully passed. If all tests
|
||||
pass, prints " ok." and moves the cursor to the next line.
|
||||
|
||||
In case any of the tests fails, exception is raised and program
|
||||
terminates.
|
||||
|
||||
(test-eq? name expression expected-result)
|
||||
|
||||
* ```name``` - identifier representing the name of the test
|
||||
* ```expression``` - expression to be evaluated
|
||||
* ```expected-result``` - expected result of the test expression
|
||||
|
||||
Evaluates the test ```expression``` and compares the result with
|
||||
```expected-result``` using ```eq?```. If the comparison fails, an
|
||||
exception is raised with the ```name``` of the test added to the
|
||||
exception. If the test passes, prints "." like all tests from this
|
||||
module do.
|
||||
|
||||
(test-equal? name expression expected-result)
|
||||
|
||||
* ```name``` - identifier representing the name of the test
|
||||
* ```expression``` - expression to be evaluated
|
||||
* ```expected-result``` - expected result of the test expression
|
||||
|
||||
Evaluates the test ```expression``` and compares the result with
|
||||
```expected-result``` using ```equal?```. If the comparison fails, an
|
||||
exception is raised with the ```name``` of the test added to the
|
||||
exception. If the test passes, prints "." like all tests from this
|
||||
module do.
|
||||
|
||||
(test-true name expression)
|
||||
|
||||
* ```name``` - identifier representing the name of the test
|
||||
* ```expression``` - expression to be evaluated
|
||||
|
||||
Evaluates the test ```expression``` and checks whether the result is
|
||||
```#t``` (true). An exception is raised if it is not with the
|
||||
```name``` of the test added to the exception. If the test passes,
|
||||
prints "." like all tests from this module do.
|
||||
|
||||
(test-false name expression)
|
||||
|
||||
* ```name``` - identifier representing the name of the test
|
||||
* ```expression``` - expression to be evaluated
|
||||
|
||||
Evaluates the test ```expression``` and checks whether the result is
|
||||
```#f``` (false). An exception is raised if it is not with the
|
||||
```name``` of the test added to the exception. If the test passes,
|
||||
prints "." like all tests from this module do.
|
||||
|
||||
(test-exn name expression)
|
||||
|
||||
* ```name``` - identifier representing the name of the test
|
||||
* ```expression``` - expression to be evaluated
|
||||
|
||||
Evaluates the test ```expression``` and checks whether it raised an
|
||||
exception. An exception is raised if no exception was raised during
|
||||
the evaluation. If the test passes, prints "." like all tests from
|
||||
this module do.
|
||||
|
||||
### Table
|
||||
|
||||
This module provides moderately complex terminal table rendering.
|
||||
|
||||
(*table-border-style* [style])
|
||||
|
||||
* ```style``` - symbol representing the style
|
||||
|
||||
Valid styles are:
|
||||
|
||||
* ```'debug``` - special style to see any rendering problems
|
||||
* ```'ascii``` - plain ASCII (7-bit)
|
||||
* ```'unicode``` - nice box-drawing table (UTF-8)
|
||||
|
||||
If invalid style is provided, ```'debug``` style is automatically
|
||||
substituted.
|
||||
|
||||
(table->string tbl
|
||||
[#:table-border #f]
|
||||
[#:row-border #f]
|
||||
[#:col-border #f]
|
||||
[#:row0-border #f]
|
||||
[#:col0-border #f]
|
||||
[#:border-style (*table-border-style*)]
|
||||
[#:ansi #f])
|
||||
|
||||
* ```tbl``` - list of lists with cell data
|
||||
* ```#:table-border``` - if ```#t```, the table has outer border
|
||||
* ```#:row-border``` - if ```#t```, the rows are separated by borders
|
||||
* ```#:col-border``` - if ```#t```, the columns are separated by borders
|
||||
* ```#:row0-border``` - if ```#t```, the first row is separated by border
|
||||
* ```#:col0-border``` - if ```#t```, the first column is separated by border
|
||||
* ```#:border-style``` - which border style to use (see
|
||||
```*table-border-style*``` which is the default)
|
||||
* ```#:ansi``` - if ```#t```, all cell line strings are terminated
|
||||
with ```a:default```
|
||||
|
||||
The table ```tbl``` is represented as a list of rows where each row is
|
||||
a list of cells that hold arbitrary values that are converted to
|
||||
string when rendering the table.
|
||||
|
||||
Before rendering the table, the following steps are performed:
|
||||
|
||||
* The table is made rectangular - that is all rows are extended by
|
||||
empty strings to have the same length.
|
||||
* All non-string cells are converted to string using ```sprintf```
|
||||
* All cells are split into list of strings representing the lines of
|
||||
text inside them.
|
||||
* For each row, all cells are extended by empty strings to have
|
||||
matching number of lines of text inside them.
|
||||
* For each column, all lines of text inside all of the cells are
|
||||
padded with spaces to have uniform width.
|
||||
|
||||
Then each table row is converted to list of strings adding column
|
||||
separators and table borders as required. These lists are then joined
|
||||
with row separators and possibly prefixed and suffixed by top and
|
||||
bottom table border.
|
||||
|
||||
The resulting list of strings is joined with newline character as the
|
||||
separator.
|
||||
|
||||
### Environment
|
||||
Loading…
Add table
Add a link
Reference in a new issue