1 files changed, 359 insertions, 0 deletions
diff --git a/doc/ref/general/util.texi b/doc/ref/general/util.texi
new file mode 100644
index 00000000..bae19987
--- /dev/null
+++ b/doc/ref/general/util.texi
@@ -0,0 +1,359 @@
+@node Miscellaneous utilities
+@section Miscellaneous utilities
+
+Provided by the module @code{(hnh util)}.
+
+@defmac define-syntax [stx]
+Extends the default syntax from the default
+@lisp
+(define-syntax @r{<name>} (λ (stx) body ...))
+@end lisp
+To also allow
+@lisp
+(define-syntax (@r{<name>} stx) body ...)
+@end lisp
+@end defmac
+
+
+@defmac when pred body ...
+@defmacx unless pred body ...
+Extends @var{when} and @var{unless} to return @code{'()} on the
+false-case (instead of being undefined).
+@end defmac
+
+
+@defmac aif condition consequent alternate
+@defmacx awhen condition consequent ...
+Equivalent to the standard @var{if} and @var{when}@footnote{Actually
+our extra specialized @var{when}}, but binds the return of
+@var{condition} in the variable @var{it}.
+@end defmac
+
+
+@defmac for key in collection body ...
+@defmacx for (key ...) in collection body ...
+Syntactic sugar over @code{map}.
+@example
+(for x in collection
+     body ...)
+@end example
+expands into
+@example
+(map (lambda (x) body ...) collection)
+@end example
+
+If keys are a list, an match-lambda is used instead.
+@xref{Pattern Matching,,,guile}
+
+@defun break args ...
+Abandon the entire loop. Returing what was given to @code{break}.
+@end defun
+
+@defun continue [arg]
+Abandon the current iteration of the loop. If an argument is given,
+it's used as the result in the resulting list, otherwise @code{#f} is
+used.
+@end defun
+
+@end defmac
+
+
+@defmac print-and-return expr
+Prints @var{expr}, and then returns it.
+Only evaluates @var{expr} once.
+@end defmac
+
+
+@defun swap f
+@math{swap (λ (x y) body ...) ⇔ λ (y x) body ...}
+@end defun
+
+@defmac set! key value ...
+@defmacx set! key = proc ...
+@defmacx set! key = (op args ...) ...
+Extends @var{set!} to allow multiple forms in one, also introduces the
+cases:
+@lisp
+(set! x = f) ⇔ (set! x (f x))
+(set! x = (+ 1) ⇔ (set! x (+ x 1))
+@end lisp
+@end defmac
+
+@defmac set/r! key value ...
+See @var{set!}, but also returns the final value.
+@end defmac
+
+@defmac label name proc
+Equivalent to
+@lisp
+(letrec ((name proc))
+       proc)
+@end lisp
+@end defmac
+
+
+@defun sort* items comperator [get=identity]
+@defunx sort*! items comperator [get=identity]
+A sort more similar to Python's. Applies @var{get} to each item before
+calling @var{comperator} on them.
+
+@var{sort*!} may modify the input list.
+@end defun
+
+
+@defun find-extreme items [<=<] [access=identity]
+Returns 2 values, the most extreme value, as compared by @var{<} after
+calling @var{access} on each element, along with the remaining values
+in an undefined order.
+
+Should be faster than @var{car+cdr} ∘ @var{sort*}.
+@end defun
+
+@defun find-min list [access=identity]
+@defunx find-max list [access=identity]
+See @var{find-extreme}
+@end defun
+
+@defun filter-sorted proc list
+@c TODO document me
+@end defun
+
+@defun != args ...
+@lisp
+(define != (negate =))
+@end lisp
+@end defun
+
+@defun take-to lst n
+Equivalent to @var{take}, but return everything (instead of crash) if
+n > (length lst).
+@end defun
+
+@defun string-take-to str n
+Same as @var{take-to}, but for strings
+@end defun
+
+
+@defun string-first
+@defunx string-last
+Returns the first and last character of a string respectivly
+@end defun
+
+
+@defun as-symb s
+Returns @code{(string->symbol s)} if @var{s} is a string, @var{s} otherwise.
+@end defun
+
+@defun enumerate lst
+Returns a list of lists, where the @var{car} is the index in the list,
+and the @var{cadr} is the corresponding element of the original list
+@end defun
+
+
+@defun unval proc [n=0]
+Takes a procedure returning multiple values, and returns a function
+which takes the same arguments as the original procedure, but only
+returns one of the procedures. Which procedure can be sent as an
+additional parameter.
+@end defun
+
+
+@defun flatten lst
+Takes an arbitrarily nested list, and flattens it to a depth 1 list
+@end defun
+
+
+@defmac let-lazy forms body ...
+Syntactically equivalent to a regular @var{let}, but wraps each variable
+in @var{forms} in @var{delay}, while it finds each instance of that
+variable in body and wraps in in @var{force}.
+@end defmac
+
+
+@defun map/dotted proc dotted-list
+Like @var{map}, but also works for improper lists.
+@end defun
+
+
+@defun assq-merge a b
+@c TODO
+@end defun
+
+@defun kvlist->assq
+Given a flat list where each odd element (counting from 1) is a
+keyword, and each even element is any value, return these as a list of
+pairs of symbols and values.
+
+@lisp
+(kvlist->assq '(#:a 1 #:b "Hello"))
+⇒ ((a . 1)
+   (b . "Hello"))
+@end lisp
+@end defun
+
+@defun assq-limit alist [number=1]
+@c TODO document
+@end defun
+
+@defun group-by proc lst
+Calls @var{proc} on each element in @var{lst}, and return a
+association list which @code{(proc e)} as its keys, and all elements
+which mapped to that value.
+
+The values returned by @var{proc} are compared as per @code{equal?}.
+@end defun
+
+@defun split-by lst element
+Split a list into sub-lists on @var{element}
+@lisp
+(split-by '(0 1 2 3 4 2 5 6) 2)
+⇒ ((0 1) (3 4) (5 6))
+@end lisp
+@end defun
+
+
+@defun span-upto count predicate list
+Simar to span from srfi-1, but never takes more than
+@var{count} items. Can however still take less.
+@example
+(span-upto 2 char-numeric? (string->list "123456"))
+⇒ (#\1 #\2)
+⇒ (#\3 #\4 #\5 #\6)
+(span-upto 2 char-numeric? (string->list "H123456"))
+⇒ ()
+⇒ (#\H #\1 #\2 #\3 #\4 #\5 #\6)
+@end example
+@end defun
+
+
+@defun cross-product args ...
+Returns the cross product between all given lists. Each pair will be a
+list, whose indices matches the order of the inputs
+@end defun
+
+@defun string-flatten tree
+@c TODO document me
+@end defun
+
+@defun intersperse item list
+Inserts @var{item} between each element in @var{list}.
+@end defun
+
+
+@defun insert-ordered item collection [<=<]
+Inserts @var{item} into @var{collection}, such that collection
+remainins sorted if it was sorted beforehand.
+@end defun
+
+
+@defmac -> item forms ...
+@defmacx ->> item forms ...
+Applies each form onto item, from left to right.
+A form can either by a symbol, which is the applied directly, or a
+list, in which case @var{->} inserts item as the second argument
+(after the operand), and @var{->>} inserts it last.
+@end defmac
+
+
+@defmac set (accessor object) value
+@defmacx set (accessor object) = (operation args ...)
+See @xref{SRFI-9 Records,,,guile}
+@end defmac
+
+@defmac set-> object (accessor value) rest ...
+@defmacx set-> object (accessor = (operator args)) rest ...
+Wrapper around @var{set}, but applies transformations from left to
+right, similar to @var{->}.
+@end defmac
+
+
+@defmac and=>> value procedures ...
+Chained application of @code{and=>}, so applies each procedure from
+left to right, stopping when one return @code{#f}.
+@end defmac
+
+@defun downcase-symbol
+Converts a symbol to lower case.
+@end defun
+
+
+@defun group list chunk-size
+Splits @var{list} into sub-lists of size @var{chunk-size}.
+Requires that @math{chunk-size|(length list)}
+@end defun
+
+
+@defun iterate proc until base
+Repeatedly applies @var{proc} to @var{base}, until @var{until} is
+satisfied.
+@end defun
+
+@defun valued-map proc lists ...
+Applies a procedure which returns multiple values to each element of a
+list, and returns all values returned from all procedure calls.
+@example
+(define (± x) (values x (- x)))
+(valued-map ± '(1 2))
+⇒  1
+⇒ -1
+⇒  2
+⇒ -2
+@end example
+@end defun
+
+
+@defun assoc-ref-all alist key
+@defunx assq-ref-all alist key
+@defunx assv-ref-all alist key
+Equivalent to assoc-ref (and family), but works on association lists with
+non-unique keys, returning all mathing records (instead of just the first).
+@lisp
+(assoc-ref-all '((a . 1) (b . 2) (a . 3)) 'a)
+⇒ (1 3)
+@end lisp
+@end defun
+
+
+@defun vector-last v
+Returns the last element of @var{v}.
+@end defun
+
+@defun ->string any
+Converts @var{any} to a string, as per @var{display}.
+@end defun
+
+
+@defmac let-env bindings body ...
+Similar to @var{let}, but sets environment variables for the code in
+body. Restores the old values once we leave.
+
+A variable can also be removed from the environment, by setting its
+value to @code{#f}.
+@end defmac
+
+@defmac catch* thunk (symbol proc) ...
+Macro allowing multiple exception types to be caught. Each (symbol
+proc) pair expands to a regular @code{catch}, with the leftmost being
+innermost.
+
+@var{Symbol} can also be on the form @code{(pre-unwind @var{symbol})},
+then @code{with-throw-handler} is used instead of @code{catch}.
+@end defmac
+
+@defun uniq lst
+@defunx univ lst
+@defunx unique lst
+@defunx uniqx comp lst
+Squash repeated equivalent elements in a list into single instances,
+similar to the POSIX command uniq(1). The three variants uses
+@code{eq?}, @code{eqv?}, and @code{equal?} respectively.
+
+@code{uniqx} also takes @var{comp}, which is sholud be a binary
+procedure returning if the elements are equal.
+@end defun
+
+@defmac begin1 forms ...
+Port of Common Lisp's @code{begin1} form. Like @code{begin} runs each
+form in its body in order, but returns the first result instead of the
+last.
+@end defmac