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


## 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-list [module]

    (import util-list)

This module implements basic list functionality which is common in
most scheme implementations.

### filter [procedure]

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

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