676 lines
15 KiB
Markdown
676 lines
15 KiB
Markdown
# Utility modules
|
|
|
|
These are various utility modules for other HackerBase libraries.
|
|
|
|
## util-time [module]
|
|
|
|
(import util-time)
|
|
|
|
Compatibility module for the differences between chicken scheme
|
|
version 5.2 and earlier and 5.3 and on.
|
|
|
|
### current-util-milliseconds [procedure]
|
|
|
|
(current-util-milliseconds)
|
|
|
|
Returns the number of milliseconds since process startup.
|
|
|
|
Under chicken scheme <5.3 it uses ```current-milliseconds``` and for
|
|
chicken scheme >=5.3 it uses ```current-process-milliseconds```.
|
|
|
|
Without this module compilation with ```current-milliseconds```
|
|
results in warnings on chicken scheme >=5.3 and compilation under
|
|
chicken scheme <5.3 results in error with
|
|
```current-process-milliseconds```.
|
|
|
|
### seconds->iso-date-string [procedure]
|
|
|
|
(seconds->iso-date-string . args)
|
|
|
|
Converts given seconds to ISO date string YYYY-MM-DD. Defaults to ```(current-seconds)```.
|
|
|
|
### today/iso [procedure]
|
|
|
|
(today/iso)
|
|
|
|
Returns today as ISO date string YYYY-MM-DD.
|
|
|
|
## util-csv [module]
|
|
|
|
(import util-csv)
|
|
|
|
This module provides a very simple, incomplete and incorrect but fast
|
|
CSV loader.
|
|
|
|
### (make-csv-line-parser separator string-delimiter) [procedure]
|
|
|
|
((make-csv-line-parser line)
|
|
separator
|
|
string-delimiter)
|
|
|
|
Curried version of fast CSV line parser with given separator and string delimiter.
|
|
|
|
* ```separator``` - separator character
|
|
* ```string-delimiger``` - string quotation character
|
|
* ```line``` - line to parse
|
|
|
|
### csv-parse-lines [procedure]
|
|
|
|
(csv-parse-lines lines
|
|
#:separator (separator #\;)
|
|
#:string-delimiter (string-delimiter #\"))
|
|
|
|
Parses given lines and returns list of lists of strings.
|
|
|
|
### csv-parse [procedure]
|
|
|
|
(csv-parse fn
|
|
. args)
|
|
|
|
Uses ```csv-parse-lines``` on lines read from given file ```fn```.
|
|
|
|
### csv-split-header [procedure]
|
|
|
|
(csv-split-header csv)
|
|
|
|
Splits given loaded CSV into two tables at the first empty row.
|
|
|
|
## util-git [module]
|
|
|
|
(import util-git)
|
|
|
|
This module provides basic git repository querying functionality.
|
|
|
|
### git [procedure]
|
|
|
|
(git repo
|
|
(defmodesym (quote output)))
|
|
|
|
|
|
* ```repo``` - a path to repository
|
|
* ```mode``` - return values mode for operations
|
|
|
|
Returns a procedure that allows invocation of git in given ```repo```
|
|
repository returning one or two values based on ```mode``` given:
|
|
|
|
* ```'exit``` - returns exit code
|
|
* ```'output``` - returns the output lines (default)
|
|
* ```'exit+output``` - returns both exit code and output lines
|
|
|
|
|
|
### git-status [procedure]
|
|
|
|
(git-status repo)
|
|
|
|
|
|
* ```repo``` - git repository
|
|
|
|
Returns a dictionary with the following keys:
|
|
|
|
* ```'modified``` - list of modified files
|
|
* ```'untracked``` - list of untracked files
|
|
* ```'unknown``` - list of files with unknown status
|
|
|
|
|
|
### git-blame [procedure]
|
|
|
|
(git-blame repo
|
|
fname)
|
|
|
|
|
|
* ```repo``` - git repository
|
|
* ```fname``` - file name (path) relative to the git repository
|
|
|
|
Returns annotated source with information about originating commits
|
|
for each line represented by dictionary with keys from git output.
|
|
|
|
|
|
## util-io [module]
|
|
|
|
(import util-io)
|
|
|
|
Module implementing advanced I/O.
|
|
|
|
### read-lines/no-bom [procedure]
|
|
|
|
(read-lines/no-bom ip)
|
|
|
|
|
|
* ```port``` - an input port
|
|
|
|
Reads lines using ```read-lines``` and if the first line contains
|
|
UTF-8 BOM, removes it.
|
|
|
|
|
|
### get-process-output-lines [procedure]
|
|
|
|
(get-process-output-lines cmd
|
|
. args)
|
|
|
|
|
|
* ```cmd``` - a string with the command
|
|
* ```args``` - list of arguments to pass to process
|
|
|
|
Returns a list of strings representing all the lines produced by
|
|
running the command given.
|
|
|
|
|
|
### get-process-exit+output-lines [procedure]
|
|
|
|
(get-process-exit+output-lines cmd
|
|
. args)
|
|
|
|
|
|
* ```cmd``` - a string with the command
|
|
* ```args``` - list of arguments to pass to process
|
|
|
|
Returns two values - an exit code and a list of strings representing
|
|
all the lines produced by running the command given.
|
|
|
|
|
|
### process-send/recv [procedure]
|
|
|
|
(process-send/recv cmd
|
|
args
|
|
. lines)
|
|
|
|
|
|
* ```cmd``` - a string with command
|
|
* ```args``` - list of arguments
|
|
* ```lines``` - lines to feed to stdin of the process
|
|
|
|
Executes given command ```cmd``` with given argument list ```args```
|
|
writing all ```lines``` to its standard input and then reads all the
|
|
process output.
|
|
|
|
|
|
## util-stdout [module]
|
|
|
|
(import util-stdout)
|
|
|
|
Very simple module wrapping standard output.
|
|
|
|
### *stdout-quiet* [parameter]
|
|
|
|
(define *stdout-quiet* (make-parameter #f))
|
|
(*stdout-quiet*)
|
|
(*stdout-quiet* quiet)
|
|
|
|
A boolean parameter which disables all output from procedures in this
|
|
module if its value is ```#t```.
|
|
|
|
### stdout-print [procedure]
|
|
|
|
(stdout-print . args)
|
|
|
|
If not quiet, passes ```args``` to ```print```.
|
|
|
|
### stdout-printf [procedure]
|
|
|
|
(stdout-printf fmt
|
|
. args)
|
|
|
|
If not quiet, prints formatted string ```fmt``` by applying ```args```
|
|
to ```format``` procedure.
|
|
|
|
### stdout-newline [procedure]
|
|
|
|
(stdout-newline)
|
|
|
|
If not quiet, calls ```(newline)```.
|
|
|
|
## util-parser [module]
|
|
|
|
(import util-parser)
|
|
|
|
This module contains common functions for both configuration and
|
|
member file parsers. All functions are UTF-8 aware.
|
|
|
|
### parser-preprocess-line [procedure]
|
|
|
|
(parser-preprocess-line line)
|
|
|
|
* ```line``` - a string with contents of one source line
|
|
|
|
If the input ```line``` contains the ```#``` character, the rest of
|
|
the line (including this character) is removed.
|
|
|
|
Any leading and trailing space is removed.
|
|
|
|
Returns a string representing the preprocessed line.
|
|
|
|
### parser-parse-line [procedure]
|
|
|
|
(parser-parse-line line)
|
|
|
|
* ```line``` - preprocessed line (string)
|
|
|
|
If the ```line``` is empty, returns ```#f```.
|
|
|
|
If the line contains only one token consisting of non-whitespace
|
|
characters before the first whitespace character (there is no
|
|
whitespace), returns a symbol created by interning the whole
|
|
```line```.
|
|
|
|
When the ```line``` contains whitespace character(s), it returns a
|
|
pair consisting of symbol created by interning the string of
|
|
non-whitespace characters before the first whitespace character and
|
|
the string with the rest of the line.
|
|
|
|
## util-proc [module]
|
|
|
|
(import util-proc)
|
|
|
|
This module provides a few simple procedures for querying properties
|
|
of other procedures.
|
|
|
|
### improper-list-info [procedure]
|
|
|
|
(improper-list-info lst)
|
|
|
|
Returns two values: the proper part of the list length and #t if
|
|
there is an improper list end
|
|
|
|
### (procedure-arity=? n) [procedure]
|
|
|
|
((procedure-arity=? proc)
|
|
n)
|
|
|
|
* ```n``` - integer representing the number of arguments
|
|
* ```proc``` - procedure to query
|
|
|
|
Returns true if the procedure ```proc``` accepts exactly ```n```
|
|
arguments.
|
|
|
|
### (procedure-arity>=? n) [procedure]
|
|
|
|
((procedure-arity>=? proc)
|
|
n)
|
|
|
|
* ```n``` - integer representing the number of arguments
|
|
* ```proc``` - procedure to query
|
|
|
|
Returns true if the procedure ```proc``` accepts at least ```n```
|
|
arguments.
|
|
|
|
### (procedure-arity>? n) [procedure]
|
|
|
|
((procedure-arity>? proc)
|
|
n)
|
|
|
|
* ```n``` - integer representing the number of arguments
|
|
* ```proc``` - procedure to query
|
|
|
|
Returns true if the procedure ```proc``` accepts more than ```n```
|
|
arguments.
|
|
|
|
### procedure-num-args [procedure]
|
|
|
|
(procedure-num-args proc)
|
|
|
|
* ```proc``` - procedure to check
|
|
|
|
Returns the number of mandatory arguments.
|
|
|
|
### procedure-arg-names [procedure]
|
|
|
|
(procedure-arg-names proc)
|
|
|
|
* ```proc``` - procedure to check
|
|
|
|
Returns the (possibly improper) list of arguments the procedure
|
|
```proc``` accepts. If it accepts arbitrary number of arguments, it is
|
|
signalled by simple symbol instead of pair at the last position. If it
|
|
accepts an exact number of arguments, it returns a proper list.
|
|
|
|
## util-format [module]
|
|
|
|
(import util-format)
|
|
|
|
A simple module with less-common formatting functions.
|
|
|
|
### format-amount [procedure]
|
|
|
|
(format-amount amt)
|
|
|
|
* ```amt``` - a number
|
|
|
|
Converts given number to a string with two-digit fractional
|
|
part. Should the fractional part be 0, it is replaced with the string
|
|
"--".
|
|
|
|
## util-tag [module]
|
|
|
|
(import util-tag)
|
|
|
|
A unifying module for compound data structures tagging.
|
|
|
|
### make-tag [syntax]
|
|
|
|
(_ tag)
|
|
|
|
* ```tag``` - unquoted symbol to base the tag on
|
|
|
|
Creates a unique and collision free symbol to identify compound data
|
|
structures based on lists and pairs.
|
|
|
|
## util-string [module]
|
|
|
|
(import util-string)
|
|
|
|
String manipulation functions which are used throughout other modules.
|
|
|
|
### string-first+rest [procedure]
|
|
|
|
(string-first+rest str)
|
|
|
|
* ```str``` - a string to split
|
|
|
|
Returns a pair of strings where the ```car``` of the pair is the first
|
|
token in the ```str``` given and ```cdr``` is a string with the
|
|
remainder with leading whitespace removed.
|
|
|
|
### string->qp [procedure]
|
|
|
|
(string->qp str)
|
|
|
|
* ```str``` - arbitrary string
|
|
|
|
Returns a new string with all non-ASCII characters encoded as
|
|
quoted-printable sequences.
|
|
|
|
### string-upcase [procedure]
|
|
|
|
(string-upcase str)
|
|
|
|
* ```str``` - arbitrary string
|
|
|
|
Returns the ```str``` with all characters converted to upper case
|
|
using ```char-upcase```. Does not work with UTF-8.
|
|
|
|
### string-capitalize [procedure]
|
|
|
|
(string-capitalize str)
|
|
|
|
* ```str``` - arbitrary string
|
|
|
|
Returns the ```str``` with the first character converted to upper case
|
|
using ```char-upcase``` and the remainder converted to lower case
|
|
using ```char-downcase```. Does not work with UTF-8.
|
|
|
|
## util-mail [module]
|
|
|
|
(import util-mail)
|
|
|
|
A simple wrapper module to send emails from UNIX system.
|
|
|
|
### *mailto-override* [parameter]
|
|
|
|
(define *mailto-override* (make-parameter #f))
|
|
(*mailto-override*)
|
|
(*mailto-override* email)
|
|
|
|
* ```email``` - email address string
|
|
|
|
If this parameter is non-```#f```, all outgoing emails are actually
|
|
sent to the address stored within.
|
|
|
|
### send-mail [procedure]
|
|
|
|
(send-mail body-lines
|
|
#:from (from #f)
|
|
#:to to
|
|
#:subject subject
|
|
#:headers (headers (quote ())))
|
|
|
|
* ```body-lines``` - lines of the email
|
|
* ```from``` - email address from string
|
|
* ```to``` - email address to string
|
|
* ```subject``` - email subject string
|
|
* ```headers``` - list of headers to add
|
|
|
|
Sends email using mail(1) command. The arguments ```#:to``` and
|
|
```#:subject``` are mandatory. Argument ```#:from``` is optional.
|
|
|
|
## util-bst [module]
|
|
|
|
(import util-bst)
|
|
|
|
Binary Search Tree implementation
|
|
|
|
### make-bst [procedure]
|
|
|
|
(make-bst subtag
|
|
EQ?
|
|
<?)
|
|
|
|
Creates empty BST with given comparators
|
|
|
|
### (bst? subtag) [procedure]
|
|
|
|
((bst? v)
|
|
subtag)
|
|
|
|
Curried predicate for particular bst type.
|
|
|
|
### bst-empty? [procedure]
|
|
|
|
(bst-empty? bst)
|
|
|
|
Returns #t if given BST is empty.
|
|
|
|
### bst-ref [procedure]
|
|
|
|
(bst-ref bst
|
|
k
|
|
. vs)
|
|
|
|
Retrieves value associated with given key.
|
|
|
|
### bst-contains? [procedure]
|
|
|
|
(bst-contains? bst
|
|
k)
|
|
|
|
Predicate for key existence in BST.
|
|
|
|
### bst-set [procedure]
|
|
|
|
(bst-set bst
|
|
k
|
|
v)
|
|
|
|
Sets given key to given value and updates count if needed.
|
|
|
|
### bst-remove [procedure]
|
|
|
|
(bst-remove bst
|
|
k
|
|
. nos)
|
|
|
|
Removes given key from the BST.
|
|
|
|
### bst-keys [procedure]
|
|
|
|
(bst-keys bst)
|
|
|
|
Returns all the keys contained in given dictionary.
|
|
|
|
### bst-balance [procedure]
|
|
|
|
(bst-balance bst)
|
|
|
|
Unconditionally balances the BST.
|
|
|
|
### bst-find-pair [procedure]
|
|
|
|
(bst-find-pair bst
|
|
pred?)
|
|
|
|
Finds pair by predicate that accepts both key and value.
|
|
|
|
### bst-filter-pairs [procedure]
|
|
|
|
(bst-filter-pairs bst
|
|
pred?)
|
|
|
|
Returns a list of key-value pairs matching predicate.
|
|
|
|
### bst-map-list [procedure]
|
|
|
|
(bst-map-list bst
|
|
proc)
|
|
|
|
Returns arbitrary list created by mapping all elements.
|
|
|
|
### bst-map-bst [procedure]
|
|
|
|
(bst-map-bst bst
|
|
proc)
|
|
|
|
Returns a new dictionary with all values processed (keys are left intact).
|
|
|
|
### list->bst [procedure]
|
|
|
|
(list->bst lst
|
|
subtag
|
|
EQ?
|
|
<?)
|
|
|
|
Converts list of pairs into BST dictionary.
|
|
|
|
### bst-update [procedure]
|
|
|
|
(bst-update bst
|
|
k
|
|
proc
|
|
(v #f))
|
|
|
|
Functional update with optional default value (defaults to #f).
|
|
|
|
### bst-filter [procedure]
|
|
|
|
(bst-filter bst
|
|
pred?)
|
|
|
|
Returns a BST with only KV pairs matching the predicate which must
|
|
accept two arguments.
|
|
|
|
### bst-reduce [procedure]
|
|
|
|
(bst-reduce bst
|
|
proc
|
|
init)
|
|
|
|
Like generic reduce, the proc gets accumulator, key and value
|
|
arguments.
|
|
|
|
### bst-equal? [procedure]
|
|
|
|
(bst-equal? b1
|
|
b2
|
|
(equality? equal?))
|
|
|
|
Returns true if both BSTs contain the same keys and values.
|
|
|
|
## util-bst-bdict [module]
|
|
|
|
(import util-bst-bdict)
|
|
|
|
Reimplementation of old number-only BST dictionary.
|
|
|
|
## util-bst-ldict [module]
|
|
|
|
(import util-bst-ldict)
|
|
|
|
Reimplementation of old list-based symbol dictionary using new BST backend.
|
|
|
|
## util-bst-lset [module]
|
|
|
|
(import util-bst-lset)
|
|
|
|
Reimplementation of old lset using new BST backend.
|
|
|
|
## util-dir [module]
|
|
|
|
(import util-dir)
|
|
|
|
Directory handling which didn't fit elsewhere.
|
|
|
|
### ensure-directory [procedure]
|
|
|
|
(ensure-directory dir)
|
|
|
|
Makes sure given path exists and it is a directory. Throws an error
|
|
if it exists and it is not a directory.
|
|
|
|
## util-utf8 [module]
|
|
|
|
(import util-utf8)
|
|
|
|
High-performance UTF-8 support.
|
|
|
|
### utf8-char->string [procedure]
|
|
|
|
(utf8-char->string ch)
|
|
|
|
Encodes given character as UTF-8.
|
|
|
|
### make-utf8-string [procedure]
|
|
|
|
(make-utf8-string n
|
|
(ch #\space))
|
|
|
|
UTF-8 version of make-string.
|
|
|
|
### string-append-utf8-char [procedure]
|
|
|
|
(string-append-utf8-char s
|
|
ch)
|
|
|
|
UTF-8 character append.
|
|
|
|
### utf8-string->lists [procedure]
|
|
|
|
(utf8-string->lists str)
|
|
|
|
Converts a UTF-8 string into two lists: list of UTF-8 characters
|
|
of the string and a list of remaining bytes (as integers).
|
|
|
|
### utf8-bytes->lists [procedure]
|
|
|
|
(utf8-bytes->lists chars)
|
|
|
|
The same as above but accepts a list of bytes (as integers).
|
|
|
|
### utf8-string-next-char [procedure]
|
|
|
|
(utf8-string-next-char str
|
|
(si0 0))
|
|
|
|
Returns the position right after the character at specified
|
|
position.
|
|
|
|
### utf8-string-length [procedure]
|
|
|
|
(utf8-string-length s)
|
|
|
|
Calculates the length of given UTF-8 string.
|
|
|
|
### utf8-string->list [procedure]
|
|
|
|
(utf8-string->list s)
|
|
|
|
Converts utf8 string to list of unicode characters.
|
|
|
|
### list->utf8-string [procedure]
|
|
|
|
(list->utf8-string lst)
|
|
|
|
Converts list of unicode characters into utf8 string.
|
|
|
|
### string-utf8? [procedure]
|
|
|
|
(string-utf8? s)
|
|
|
|
Returns true, if given string contains UTF-8 characters.
|