hackerbase/doc/d-utils.md

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.

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.