From 7abb4065381312cb48baaca4a68f522845d6fa61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dominik=20Pant=C5=AF=C4=8Dek?= Date: Thu, 23 Mar 2023 16:59:09 +0100 Subject: [PATCH] Split modules documentation from readme. --- MODULES.md | 598 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 591 ---------------------------------------------------- 2 files changed, 598 insertions(+), 591 deletions(-) create mode 100644 MODULES.md diff --git a/MODULES.md b/MODULES.md new file mode 100644 index 0000000..a7b76bf --- /dev/null +++ b/MODULES.md @@ -0,0 +1,598 @@ +BrmBuro Modules +=============== + +This file contains documentation of all exported symbols of all +modules used. Modules are grouped according to their specificity to +this project. + +Functional Modules +------------------ + +These modules are specific to this project and their generic usage is +questionable. + +### Configuration + +The exact behavior of some algorithms in other modules can be changed +via configuration parameters in this global configuration module. + + (*current-month* [month]) + +* ```month``` - valid month structure as specified in the ```month``` module + +Configuration parameter specifying the current month. Defaults to the +current month derived from the current system time. + + (*member-file-context* [lines]) + +* ```lines``` - number of context lines + +How many lines of context are to be shown in source file +listing. Mainly used by the member file module parser and processor. + + (*member-file-check-syntax* [mode]) + +* ```mode``` - mode symbol + +Configures syntax error handling when parsing member files. Known +modes are: + +* ```'error``` - raises an error upon encountering error +* ```'warning``` - displays warning and displays relevant part of + member file source with the offending line highlighted. +* ```'quiet``` - supresses any error reporting + +Other values are invalid. + + (*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) + +Determines how many months the member can be suspended before any +action is required. + +### Member File + +### Member Record + +### Member Base + +Specific Support Modules +------------------------ + +### Month + +Module for handling months algebra to be used in period construction +and matching. + + (make-month y m) + +* ```y``` - a number representing valid year +* ```m``` - a number between 1 and 12 inclusive + +Constructs a new month value with ```y``` number as the year component +and ```m``` number as the month component. + + (month-valid? m) + +* ```m``` - constructed month value + +Checks whether given value is structurally valid month value, the year +is between 1000 and 9999 inclusive and the month is between 1 and 12 +inclusive. Returns boolean value. + + (string->month s) + +* ```s``` - a string in "YYYY-MM" format + +Parses given string ```s``` as month and constructs a month value from +the YYYY and MM components parsed. The resulting month value is +returned only if it is valid. Otherwise ```#f``` is returned. + + (month->string m) + +* ```m``` - valid month value or ```#f``` + +Converts given month value to a string in ```"YYYY-MM"``` format. + +If ```#f```, returns a special empty month result ```"____-__"```. + +Raises an error if ```m``` is not a valid month. + + (month=? m n) + +* ```m``` - first valid month value +* ```n``` - second valid month value + +Returns ```#t``` if both month values are valid and ```equal?```. + + (month=? m n) + +* ```m``` - first valid month value +* ```n``` - second valid month value + +Returns ```#t``` if both month values are valud and ```m``` comes +after ```n``` in the calendar or they are ```equal?```. + + (month>? m n) + +* ```m``` - first valid month value +* ```n``` - second valid month value + +Returns ```#t``` if both month values are valud and ```m``` comes +after ```n``` in the calendar. + + (month-diff f t) + +* ```f``` - valid month (from) +* ```t``` - valid month (to) + +Returns the difference in months from month ```f``` to month +```t```. If both months are the same, the result is zero. If ```t``` +is before ```f```, the result is negative. + + (month-add m n) + +* ```m``` - valid month +* ```n``` - an integer + +Returns a new valid month that comes ```n``` months after ```m```. If +```n``` is negative, it correctly subtracts the months. + +### Period + +This module implements simple calendar period handling with month +granularity. + + (period-markers->periods l) + +* ```l``` - list of sorted (list tag month) + +Converts a list of period markers ```l``` into actual periods where +each period is represented by ```(list start-month end-month)```. + +The ```end-month``` may be ```#f``` in which case it is an open-ended +period which has not ended yet. + + (periods-duration l) + +* ```l``` - list of periods + +Returns the total duration in months of the periods given in the list +```l```. Each period is represented as ```(list start-month +end-month)```. + + (month-in-periods? ps [m (*current-month*)]) + +* ```ps``` - a list of periods +* ```m``` - a valid month - defaults to ```(*current-month*)``` + +Returns ```#t``` if given month ```m``` lies within any of the periods +given in the list of periods ```ps```. + + (periods->string ps) + +* ```ps``` - a list of periods + +Returns a string representing all the periods given in the list of +periods ```ps```. The periods are represented as +````"YYYY-MM..YYYY-MM"``` and an open end is substituded with +```"____-__"```. + + + (periods-match ps [m (*current-month*)]) + +* ```ps``` - a list of periods + +Returns the period from the list of periods ```ps``` the given month +```m``` falls into. If no period matches, returns ```#f```. + +### Primes + +A very simple module for generating and checking 4-digit prime numbers. + + (is-4digit-prime? n) + +* ```n``` - a number + +Returns true if the given number ```n``` has four digits and it is a +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``` - white (grey) text foreground 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. + +### 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. + +### Dictionary + +Simple key/value dictionary with most operations implemented in linear +time. The dictionary is internally represented as ```assq``` list and +is best suitable for symbols and numbers as keys. + + (make-dict) + +Creates an empty dictionary. + + (dict-has-key? d k) + +* ```d``` - the dictionary +* ```k``` - key to check + +Returns ```#t``` (true) if the dictionary ```d``` contains the key +```k```. + + (dict-ref d k [v]) + +* ```d``` - the dictionary +* ```k``` - the key to retrieve +* ```v``` - optional default value + +Retrieves given key ```k``` from the dictionary ```d```. + +If the key is not stored in the dictionary an error is raised unless +an optional value ```v``` is provided which is then returned in that +case. + + (dict-remove d k) + +* ```d``` - the dictionary +* ```k``` - the key to remove + +Removes the key ```k``` from the given dictionary ```d``` raising an +exception if the key is not stored in the dictionary. + + (dict-set d k v) + +* ```d``` - the dictionary +* ```k``` - key to (re)set +* ```v``` - the value to set + +If the dictionary ```d``` does not contain the key ```k```, adds the +value ```v``` into it under the given key. If the key is present, its +value is then replaced. + + (dict-keys d) + +* ```d``` - the dictionary + +Returns the list of keys contained in the dictionary ```d```. + + (dict-map proc d) + +* ```proc``` - procedure for processing +* ```d``` - the dictionary + +Returns a dictionary created by processing all elements of the +dictionary ```d``` using the procedure ```proc```. + +If the procedure accepts just one argument, only values are passed to +it. If the procedure accepts two arguments, both the key and value are +passed to it. In both cases, the procedure must produce only the value. + + (dict-filter pred? d) + +* ```pred?``` - predicate procedure +* ```d``` - the dictionary + +Returns a new dictionary created by keeping only the key/value pairs +from the dictionary ```d``` matching the predicate ```pred?```. + +If the procedure accepts just one argument, only values are passed to +it. If the procedure accepts two arguments, both the key and value are +passed to it. + + (dict-reduce init proc d) + +* ```init``` - arbitrary initial value +* ```proc``` - procedure for performing the reducing step +* ```d``` - the dictionary to reduce + +Iterates over the key/value pairs of given dictionary ```d``` +initializing the algorithm with the ```init``` value given. In each +step the procedure ```proc``` is called with three arguments: the +value accumulated so far, key and value. + +### 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 +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 +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. + +### Utils + +To ensure there are no external dependencies (including chicken eggs), +this module re-implements any basic procedures which are required for +any algorithms used. + + (filter pred? lst) + +* ```pred?``` - procedure accepting any value and returning #t or #f +* ```lst``` - list to be filtered + +Returns a list containing only elements matching given ```pred?``` +predicate. + + (string-repeat str rep) + +* ```str``` - string to repeat +* ```rep``` - number of repeats + +Returns a string created by repeating the string ```str``` exactly +```rep``` number of times. diff --git a/README.md b/README.md index ff90f4c..703ce10 100644 --- a/README.md +++ b/README.md @@ -80,594 +80,3 @@ Building the import module files, shared and static binaries together: make all -Functional Modules ------------------- - -These modules are specific to this project and their generic usage is -questionable. - -### Configuration - -The exact behavior of some algorithms in other modules can be changed -via configuration parameters in this global configuration module. - - (*current-month* [month]) - -* ```month``` - valid month structure as specified in the ```month``` module - -Configuration parameter specifying the current month. Defaults to the -current month derived from the current system time. - - (*member-file-context* [lines]) - -* ```lines``` - number of context lines - -How many lines of context are to be shown in source file -listing. Mainly used by the member file module parser and processor. - - (*member-file-check-syntax* [mode]) - -* ```mode``` - mode symbol - -Configures syntax error handling when parsing member files. Known -modes are: - -* ```'error``` - raises an error upon encountering error -* ```'warning``` - displays warning and displays relevant part of - member file source with the offending line highlighted. -* ```'quiet``` - supresses any error reporting - -Other values are invalid. - - (*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) - -Determines how many months the member can be suspended before any -action is required. - -### Member File - -### Member Record - -### Member Base - -Specific Support Modules ------------------------- - -### Month - -Module for handling months algebra to be used in period construction -and matching. - - (make-month y m) - -* ```y``` - a number representing valid year -* ```m``` - a number between 1 and 12 inclusive - -Constructs a new month value with ```y``` number as the year component -and ```m``` number as the month component. - - (month-valid? m) - -* ```m``` - constructed month value - -Checks whether given value is structurally valid month value, the year -is between 1000 and 9999 inclusive and the month is between 1 and 12 -inclusive. Returns boolean value. - - (string->month s) - -* ```s``` - a string in "YYYY-MM" format - -Parses given string ```s``` as month and constructs a month value from -the YYYY and MM components parsed. The resulting month value is -returned only if it is valid. Otherwise ```#f``` is returned. - - (month->string m) - -* ```m``` - valid month value or ```#f``` - -Converts given month value to a string in ```"YYYY-MM"``` format. - -If ```#f```, returns a special empty month result ```"____-__"```. - -Raises an error if ```m``` is not a valid month. - - (month=? m n) - -* ```m``` - first valid month value -* ```n``` - second valid month value - -Returns ```#t``` if both month values are valid and ```equal?```. - - (month=? m n) - -* ```m``` - first valid month value -* ```n``` - second valid month value - -Returns ```#t``` if both month values are valud and ```m``` comes -after ```n``` in the calendar or they are ```equal?```. - - (month>? m n) - -* ```m``` - first valid month value -* ```n``` - second valid month value - -Returns ```#t``` if both month values are valud and ```m``` comes -after ```n``` in the calendar. - - (month-diff f t) - -* ```f``` - valid month (from) -* ```t``` - valid month (to) - -Returns the difference in months from month ```f``` to month -```t```. If both months are the same, the result is zero. If ```t``` -is before ```f```, the result is negative. - - (month-add m n) - -* ```m``` - valid month -* ```n``` - an integer - -Returns a new valid month that comes ```n``` months after ```m```. If -```n``` is negative, it correctly subtracts the months. - -### Period - -This module implements simple calendar period handling with month -granularity. - - (period-markers->periods l) - -* ```l``` - list of sorted (list tag month) - -Converts a list of period markers ```l``` into actual periods where -each period is represented by ```(list start-month end-month)```. - -The ```end-month``` may be ```#f``` in which case it is an open-ended -period which has not ended yet. - - (periods-duration l) - -* ```l``` - list of periods - -Returns the total duration in months of the periods given in the list -```l```. Each period is represented as ```(list start-month -end-month)```. - - (month-in-periods? ps [m (*current-month*)]) - -* ```ps``` - a list of periods -* ```m``` - a valid month - defaults to ```(*current-month*)``` - -Returns ```#t``` if given month ```m``` lies within any of the periods -given in the list of periods ```ps```. - - (periods->string ps) - -* ```ps``` - a list of periods - -Returns a string representing all the periods given in the list of -periods ```ps```. The periods are represented as -````"YYYY-MM..YYYY-MM"``` and an open end is substituded with -```"____-__"```. - - - (periods-match ps [m (*current-month*)]) - -* ```ps``` - a list of periods - -Returns the period from the list of periods ```ps``` the given month -```m``` falls into. If no period matches, returns ```#f```. - -### Primes - -A very simple module for generating and checking 4-digit prime numbers. - - (is-4digit-prime? n) - -* ```n``` - a number - -Returns true if the given number ```n``` has four digits and it is a -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``` - white (grey) text foreground 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. - -### 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. - -### Dictionary - -Simple key/value dictionary with most operations implemented in linear -time. The dictionary is internally represented as ```assq``` list and -is best suitable for symbols and numbers as keys. - - (make-dict) - -Creates an empty dictionary. - - (dict-has-key? d k) - -* ```d``` - the dictionary -* ```k``` - key to check - -Returns ```#t``` (true) if the dictionary ```d``` contains the key -```k```. - - (dict-ref d k [v]) - -* ```d``` - the dictionary -* ```k``` - the key to retrieve -* ```v``` - optional default value - -Retrieves given key ```k``` from the dictionary ```d```. - -If the key is not stored in the dictionary an error is raised unless -an optional value ```v``` is provided which is then returned in that -case. - - (dict-remove d k) - -* ```d``` - the dictionary -* ```k``` - the key to remove - -Removes the key ```k``` from the given dictionary ```d``` raising an -exception if the key is not stored in the dictionary. - - (dict-set d k v) - -* ```d``` - the dictionary -* ```k``` - key to (re)set -* ```v``` - the value to set - -If the dictionary ```d``` does not contain the key ```k```, adds the -value ```v``` into it under the given key. If the key is present, its -value is then replaced. - - (dict-keys d) - -* ```d``` - the dictionary - -Returns the list of keys contained in the dictionary ```d```. - - (dict-map proc d) - -* ```proc``` - procedure for processing -* ```d``` - the dictionary - -Returns a dictionary created by processing all elements of the -dictionary ```d``` using the procedure ```proc```. - -If the procedure accepts just one argument, only values are passed to -it. If the procedure accepts two arguments, both the key and value are -passed to it. In both cases, the procedure must produce only the value. - - (dict-filter pred? d) - -* ```pred?``` - predicate procedure -* ```d``` - the dictionary - -Returns a new dictionary created by keeping only the key/value pairs -from the dictionary ```d``` matching the predicate ```pred?```. - -If the procedure accepts just one argument, only values are passed to -it. If the procedure accepts two arguments, both the key and value are -passed to it. - - (dict-reduce init proc d) - -* ```init``` - arbitrary initial value -* ```proc``` - procedure for performing the reducing step -* ```d``` - the dictionary to reduce - -Iterates over the key/value pairs of given dictionary ```d``` -initializing the algorithm with the ```init``` value given. In each -step the procedure ```proc``` is called with three arguments: the -value accumulated so far, key and value. - -### 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 -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 -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. - -### Utils - -To ensure there are no external dependencies (including chicken eggs), -this module re-implements any basic procedures which are required for -any algorithms used. - - (filter pred? lst) - -* ```pred?``` - procedure accepting any value and returning #t or #f -* ```lst``` - list to be filtered - -Returns a list containing only elements matching given ```pred?``` -predicate. - - (string-repeat str rep) - -* ```str``` - string to repeat -* ```rep``` - number of repeats - -Returns a string created by repeating the string ```str``` exactly -```rep``` number of times.