537 lines
13 KiB
Markdown
537 lines
13 KiB
Markdown
Utility Modules
|
|
===============
|
|
|
|
To ensure there are no external dependencies (including chicken eggs),
|
|
these modules re-implement any basic procedures which are required for
|
|
any algorithms used. And some advanced yet generic functionality as
|
|
well.
|
|
|
|
The modules are listed in alphabetical order.
|
|
|
|
### CSV
|
|
|
|
(import util-csv)
|
|
|
|
This module provides a very simple, incomplete and incorrect but fast
|
|
CSV loader.
|
|
|
|
(csv-parse filename
|
|
[#:separator #\;]
|
|
[#:string-delimiter #\"])
|
|
|
|
* ```separator``` - cell separator in CSV file
|
|
* ```string-delimiter``` - for introducing strings possibly with separators
|
|
|
|
Parses given CSV file and returns list of lists of strings
|
|
representing its contents.
|
|
|
|
(csv-split-header csv)
|
|
|
|
* ```csv``` - list of lists of strings
|
|
|
|
Splits given loaded CSV into two tables at the first empty row.
|
|
|
|
### Dictionary
|
|
|
|
(import util-dict-list)
|
|
|
|
This module implements a simple key/value dictionary using lists as
|
|
backend. All operations are O(n) with respect to time.
|
|
|
|
(make-ldict [equality?/pairs [pairs]])
|
|
|
|
* ```equality?/pairs``` - procedure or list of pairs
|
|
* ```pairs``` - list of pairs
|
|
|
|
Creates a new ldict with configurable equality procedure, optionally
|
|
populating it with initial data.
|
|
|
|
If only one argument is given, the procedure checks whether it is a
|
|
list of equality procedure and acts accordingly.
|
|
|
|
(ldict? v)
|
|
|
|
* ```v``` - any value
|
|
|
|
Returns ```#t``` if given value is a ldict.
|
|
|
|
(ldict-empty? ld)
|
|
|
|
* ```ld``` - a ldict instance
|
|
|
|
Returns ```#t``` if given dictionary contains no keys.
|
|
|
|
(ldict-contains? ld k)
|
|
|
|
* ```ld``` - a ldict instance
|
|
* ```k``` - a key compatible with given ldict
|
|
|
|
Returns ```#t``` if given ```ld``` contains given key ```k```.
|
|
|
|
(ldict-ref ld k [default])
|
|
|
|
* ```ld``` - a ldict instance
|
|
* ```k``` - a compatible key
|
|
* ```default``` - optional fallback value
|
|
|
|
Retrieves the value associated with given key in given dictionary. If
|
|
the dictionary does not contain it and no default is given, an
|
|
exception is raised. Otherwise the default value is returned in case
|
|
of missing key.
|
|
|
|
(ldict-remove ld k)
|
|
|
|
* ```ld``` - a ldict instance
|
|
* ```k``` - a compatible key
|
|
|
|
Returns a new dictionary with the record under given key removed. If
|
|
the dictionary does not contain the key ```k```, an error is raised.
|
|
|
|
(ldict-set ld k v)
|
|
|
|
* ```ld``` - a ldict instance
|
|
* ```k``` - a compatible key
|
|
* ```v``` - a value to insert
|
|
|
|
Sets existing key ```k``` to the new value ```v``` or inserts it if it
|
|
is not already present in the dictionary ```ld```.
|
|
|
|
(ldict-keys ld)
|
|
|
|
* ```ld``` - a ldict instance
|
|
|
|
Returns the list of keys stored in given dictionary.
|
|
|
|
(ldict-map proc ld)
|
|
|
|
* ```proc``` - procedure accepting 1, 2 or 3 arguments
|
|
* ```ld``` - a ldict instance
|
|
|
|
Returns a new dictionary of the same type with all values processed by
|
|
given procedure.
|
|
|
|
If it accepts one argument, only the value is passed to it. If it
|
|
accepts two values, the key and the value is passed to it. And lastly
|
|
if it accepts three arguments, the key, value and numeric index
|
|
(starting from 0) are passed to it.
|
|
|
|
In all cases the value the procedure returns is taken as the new value
|
|
for given key.
|
|
|
|
(ldict-filter pred? ld)
|
|
|
|
* ```pred?``` - predicate procedure
|
|
* ```ld``` -a ldict instance
|
|
|
|
Returns a new dictionary containing only key/value pairs matching the
|
|
given predicate. The procedure ```pred?``` must accept two arguments -
|
|
the key and the value.
|
|
|
|
(ldict-reduce init proc ld)
|
|
|
|
* ```init``` - initial accumulator value
|
|
* ```proc``` - accumulating procedure
|
|
* ```ld``` - a ldict instance
|
|
|
|
Performs a reduce operation on the pairs of given dictionary using
|
|
```init``` as initial accumulator. The accumulating procedure must
|
|
accept three arguments: the value accumulated so far, the key and the
|
|
value.
|
|
|
|
(ldict-equal? d1 d2 [equality?])
|
|
|
|
* ```d1``` - a ldict instance
|
|
* ```d2``` - a ldict instance
|
|
* ```equality?``` - optional equality? predicate for values
|
|
|
|
Returns ```#t``` if both dictionaries contain the same keys and their
|
|
values are equal according to the provided ```equality?``` predicate
|
|
which defaults to ```equal?```.
|
|
|
|
### Format
|
|
|
|
(import util-format)
|
|
|
|
A simple module with less-common formatting functions.
|
|
|
|
(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
|
|
"--".
|
|
|
|
### Git
|
|
|
|
(import util-git)
|
|
|
|
This module provides basic git repository querying functionality.
|
|
|
|
(git repo [mode])
|
|
|
|
* ```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 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
|
|
|
|
### IO
|
|
|
|
(import util-io)
|
|
|
|
Module implementing advanced I/O.
|
|
|
|
(read-lines/no-bom port)
|
|
|
|
* ```port``` - an input port
|
|
|
|
Reads lines using ```read-lines``` and if the first line contains
|
|
UTF-8 BOM, removes it.
|
|
|
|
(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 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 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.
|
|
|
|
### Keyword Arguments
|
|
|
|
TODO
|
|
|
|
### List
|
|
|
|
(import util-list)
|
|
|
|
This module implements basic list functionality which is common in
|
|
most scheme implementations.
|
|
|
|
(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.
|
|
|
|
### Mail
|
|
|
|
(import util-mail)
|
|
|
|
A simple wrapper module to send emails from UNIX system.
|
|
|
|
(*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 body-lines [#:from from] [#:to to] [#:subject subject])
|
|
|
|
* ```body-lines``` - lines of the email
|
|
* ```from``` - email address from string
|
|
* ```to``` - email address to string
|
|
* ```subject``` - email subject string
|
|
|
|
Sends email using mail(1) command. The arguments ```#:to``` and
|
|
```#:subject``` are mandatory. Argument ```#:from``` is optional.
|
|
|
|
### Parser
|
|
|
|
(import util-parser)
|
|
|
|
This module contains common functions for both configuration and
|
|
member file parsers. All functions are UTF-8 aware.
|
|
|
|
(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 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.
|
|
|
|
### Proc
|
|
|
|
(import util-proc)
|
|
|
|
This module provides a few simple procedures for querying properties
|
|
of other procedures.
|
|
|
|
((procedure-arity=? n) proc)
|
|
|
|
* ```n``` - integer representing the number of arguments
|
|
* ```proc``` - procedure to query
|
|
|
|
Returns true if the procedure ```proc``` accepts exactly ```n```
|
|
arguments.
|
|
|
|
((procedure-arity>=? n) proc)
|
|
|
|
* ```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) proc)
|
|
|
|
* ```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 proc)
|
|
|
|
* ```proc``` - procedure to check
|
|
|
|
Returns the number of mandatory arguments.
|
|
|
|
(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.
|
|
|
|
### Set (List)
|
|
|
|
(import util-set-list)
|
|
|
|
This module implements linear-time set with custom comparator.
|
|
|
|
(make-lset [comparator])
|
|
|
|
* ```comparator``` - comparison procedure, defaults to ```equal?```
|
|
|
|
Creates new lset with given comparator.
|
|
|
|
(lset? v)
|
|
|
|
* ```v``` - any value
|
|
|
|
Returns ```#t``` if given value is a lset.
|
|
|
|
(lset-empty? ls)
|
|
|
|
* ```ls``` - lset instance
|
|
|
|
Returns ```#t``` if given lset contains no elements.
|
|
|
|
(lset-member? ls el)
|
|
|
|
* ```ls``` - lset instance
|
|
* ```el``` - element to check
|
|
|
|
Returns ```#t``` if given element ```el``` is contained in the lset
|
|
```ls``` using its equality comparator.
|
|
|
|
(lset-count ls)
|
|
|
|
* ```ls``` - lset instance
|
|
|
|
Returns the number of elements in given lset.
|
|
|
|
(lset-add ls [el ...])
|
|
|
|
* ```ls``` - lset instance
|
|
* ```el``` - element(s) to add
|
|
|
|
Adds given element(s) ```el``` to the lset instance ```ls``` returning
|
|
a new lset instance.
|
|
|
|
(lset-remove ls el)
|
|
|
|
* ```ls``` - lset instance
|
|
* ```el``` - element to remove
|
|
|
|
If given lset instance ```ls``` contains the element ```el```
|
|
provided, it is removed and the new lset is returned. If the element
|
|
is not contained in ```ls```, it is returned intact.
|
|
|
|
(list->lset lst [comparator])
|
|
|
|
* ```lst``` - list to convert
|
|
* ```comparator``` - equality comparison procedure, defaults to ```equal?```
|
|
|
|
Returns a new lset with the comparator provided containing all
|
|
elements in given list.
|
|
|
|
(lset->list ls)
|
|
|
|
* ```ls``` - lset instance
|
|
|
|
Returns the list of elements in given lset.
|
|
|
|
(lset-merge ls1 ls2)
|
|
|
|
* ```ls1``` - lset instance
|
|
* ```ls2``` - lset instance
|
|
|
|
Returns a new lset instance with all elements in both lset instances given.
|
|
|
|
(lset-intersect ls1 ls2)
|
|
|
|
* ```ls1``` - lset instance
|
|
* ```ls2``` - lset instance
|
|
|
|
Returns a new lset instance containing elements present both in
|
|
```ls1``` and ```ls2```.
|
|
|
|
(lset-subtract ls1 ls2)
|
|
|
|
Returns a new lset instance from ```ls1``` with all elements in
|
|
```ls2``` removed from it.
|
|
|
|
(lset=? ls1 ls2)
|
|
|
|
* ```ls1``` - lset instance
|
|
* ```ls2``` - lset instance
|
|
|
|
Returns true if the sets contain exactly the same values.
|
|
|
|
### Stdout
|
|
|
|
TODO
|
|
|
|
### String
|
|
|
|
(import util-string)
|
|
|
|
String manipulation functions which are used throughout other modules.
|
|
|
|
(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.
|
|
|
|
(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-utf8? str)
|
|
|
|
* ```str``` - arbitrary string
|
|
|
|
Returns ```#t``` if given string ```str``` contains UTF-8 characters.
|
|
|
|
(string->list/utf8 str)
|
|
|
|
* ```str``` - arbitrary string
|
|
|
|
Returns a list of strings representing individual (possibly UTF-8)
|
|
characters of the string.
|
|
|
|
(string->qp str)
|
|
|
|
* ```str``` - arbitrary string
|
|
|
|
Returns a new string with all non-ASCII characters encoded as
|
|
quoted-printable sequences.
|
|
|
|
(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.
|
|
|
|
### Tag
|
|
|
|
(import util-tag)
|
|
|
|
A unifying module for compound data structures tagging.
|
|
|
|
(make-tag name)
|
|
|
|
* ```name``` - unquoted symbol to base the tag on
|
|
|
|
Creates a unique and collision free symbol to identify compound data
|
|
structures based on lists and pairs.
|
|
|
|
### Time
|
|
|
|
(import util-time)
|
|
|
|
Compatibility module for the differences between chicken scheme
|
|
version 5.2 and earlier and 5.3 and on.
|
|
|
|
(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```.
|
|
|
|
(today/iso)
|
|
|
|
Returns the current date as string in ISO YYYY-MM-DD format.
|