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.

### 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)

* ```cmd``` - a string with the command

Returns a list of strings representing all the lines produced by
running the command given.

### 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.

### 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-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.

### 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.

### 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```.