hackerbase/doc/utils.md

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.

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

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.

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

(import util-stdout)

Very simple module wrapping standard output.

(*stdout-quiet* [quiet])

A boolean parameter which disables all output from procedures in this module if its value is #t.

(stdout-print . args)

If not quiet, passes args to print.

(stdout-printf fmt . args)

If not quiet, prints formatted string fmt by applying args to format procedure.

(stdout-newline)

If not quiet, calls (newline).

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.