From 01987c093e2cfbd46115cc58e4ff9f789efb9d0d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Thu, 7 Sep 2023 18:03:40 +0200
Subject: Enable let-env to unset variables.

---
 doc/ref/guile/util.texi | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'doc/ref/guile/util.texi')

diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi
index 72463407..7536a9bc 100644
--- a/doc/ref/guile/util.texi
+++ b/doc/ref/guile/util.texi
@@ -315,6 +315,9 @@ Converts @var{any} to a string, as per @var{display}.
 @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) ...
-- 
cgit v1.2.3


From 5672d44892c4010cdfbdc46f5fb29259fa51e076 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Sun, 10 Sep 2023 17:07:56 +0200
Subject: Add `break` and `continue` support in `for`.

---
 doc/ref/guile/util.texi | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

(limited to 'doc/ref/guile/util.texi')

diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi
index 7536a9bc..95af9038 100644
--- a/doc/ref/guile/util.texi
+++ b/doc/ref/guile/util.texi
@@ -34,8 +34,8 @@ our extra specialized @var{when}}, but binds the return of
 @defmacx for (key ...) in collection body ...
 Syntactic sugar over @code{map}.
 @example
-for x in collection
-    body ...
+(for x in collection
+     body ...)
 @end example
 expands into
 @example
@@ -44,6 +44,17 @@ expands into
 
 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
 
 
-- 
cgit v1.2.3


From c26324e29043423387c3041e86d8cbe5cd4102b2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Tue, 21 Feb 2023 03:21:43 +0100
Subject: Change `kvlist->assq` and `group-by` to return pairs.

Each value in the return of group-by must have exactly two values, so
cons pairs (instead of lists) is much better.
---
 doc/ref/guile/util.texi | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'doc/ref/guile/util.texi')

diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi
index 95af9038..d61bd0ed 100644
--- a/doc/ref/guile/util.texi
+++ b/doc/ref/guile/util.texi
@@ -186,8 +186,8 @@ pairs of symbols and values.
 
 @lisp
 (kvlist->assq '(#:a 1 #:b "Hello"))
-⇒ ((a 1)
-   (b "Hello"))
+⇒ ((a . 1)
+   (b . "Hello"))
 @end lisp
 @end defun
 
-- 
cgit v1.2.3


From 475307bc9926898e769c7ad6fa3a844853b07f52 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Tue, 12 Sep 2023 10:04:04 +0200
Subject: Add a bunch of documentation.

---
 doc/ref/guile/util.texi | 66 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

(limited to 'doc/ref/guile/util.texi')

diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi
index d61bd0ed..e7accf90 100644
--- a/doc/ref/guile/util.texi
+++ b/doc/ref/guile/util.texi
@@ -1,6 +1,9 @@
 @node General Utilities
 @section General Utilities
 
+@node Miscellaneous utilities
+@subsection Miscellaneous utilities
+
 Provided by the module @code{(hnh util)}.
 
 @defmac define-syntax [stx]
@@ -340,6 +343,25 @@ innermost.
 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
+
+@node UUIDs
 @subsection UUID generation
 
 Provided by module @code{(hnh util uuid)}.
@@ -352,6 +374,12 @@ Generates a UUID-v4 string.
 Generates an implementation defined (but guaranteed valid) UUID.
 @end defun
 
+@deftp {parameter} seed
+Guile parameter containing the seed used when generating UUID's in
+this module. Only set this when you want non-random randomness.
+@end deftp
+
+@node IO operations
 @subsection IO
 
 Provided by module @code{(hnh util io)}.
@@ -382,3 +410,41 @@ the file, and @code{#f} otherwise.
 @defun read-file path
 Open file at path, and return its content as a string.
 @end defun
+
+@node Binary Search Tree
+@subsection Binary Search Tree
+
+A simple ``read only'' binary search tree.
+
+@defun make-tree pred? lst
+Constructs a new tree. @var{pred?} should be a procedure taking the
+first element of @var{lst}, along with each element, and should return
+a boolean value indicating if the specific element should go in the
+left or right subtree. (left subtree is ``truthy'' values).
+
+This operation is done recursively.
+@end defun
+
+@defun tree-node tree
+Return the value of a tree node.
+@end defun
+
+@defun left-subtree tree
+Return all ``truthy'' children of tree node.
+@end defun
+
+@defun right-subtree tree
+Return all ``falsy children of tree node.
+@end defun
+
+@defun length-of-longest-branch tree
+Get the depth of a tree.
+@end defun
+
+@defun tree-map proc tree
+Apply proc onto the value of every node in tree, keeping the structure
+of the tree.
+
+@b{Note:} this can cause the tree to no longer be a binary search
+tree, but simply a ``formless'' binary tree.
+@end defun
-- 
cgit v1.2.3


From 4d5d13b5e86dce1db72649204021882fbab668a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Tue, 12 Sep 2023 10:10:57 +0200
Subject: Change overarching structure of info document.

---
 doc/ref/guile/util.texi | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

(limited to 'doc/ref/guile/util.texi')

diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi
index e7accf90..d4dce3a6 100644
--- a/doc/ref/guile/util.texi
+++ b/doc/ref/guile/util.texi
@@ -1,8 +1,5 @@
-@node General Utilities
-@section General Utilities
-
 @node Miscellaneous utilities
-@subsection Miscellaneous utilities
+@section Miscellaneous utilities
 
 Provided by the module @code{(hnh util)}.
 
@@ -362,7 +359,7 @@ last.
 @end defmac
 
 @node UUIDs
-@subsection UUID generation
+@section UUID generation
 
 Provided by module @code{(hnh util uuid)}.
 
@@ -380,7 +377,7 @@ this module. Only set this when you want non-random randomness.
 @end deftp
 
 @node IO operations
-@subsection IO
+@section IO
 
 Provided by module @code{(hnh util io)}.
 
@@ -412,7 +409,7 @@ Open file at path, and return its content as a string.
 @end defun
 
 @node Binary Search Tree
-@subsection Binary Search Tree
+@section Binary Search Tree
 
 A simple ``read only'' binary search tree.
 
-- 
cgit v1.2.3


From 108a0454d05c744c4a05e298cfc8cbf157952414 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Tue, 12 Sep 2023 10:23:59 +0200
Subject: Rework file tree structure for info files.

---
 doc/ref/guile/util.texi | 447 ------------------------------------------------
 1 file changed, 447 deletions(-)
 delete mode 100644 doc/ref/guile/util.texi

(limited to 'doc/ref/guile/util.texi')

diff --git a/doc/ref/guile/util.texi b/doc/ref/guile/util.texi
deleted file mode 100644
index d4dce3a6..00000000
--- a/doc/ref/guile/util.texi
+++ /dev/null
@@ -1,447 +0,0 @@
-@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
-
-@node UUIDs
-@section UUID generation
-
-Provided by module @code{(hnh util uuid)}.
-
-@defun uuid-v4
-Generates a UUID-v4 string.
-@end defun
-
-@defun uuid
-Generates an implementation defined (but guaranteed valid) UUID.
-@end defun
-
-@deftp {parameter} seed
-Guile parameter containing the seed used when generating UUID's in
-this module. Only set this when you want non-random randomness.
-@end deftp
-
-@node IO operations
-@section IO
-
-Provided by module @code{(hnh util io)}.
-
-@defun open-input-port path
-@defunx open-output-port path
-Like @code{open-*-file}, but ``-'' gives @code{standard-@{input,output@}}.
-@end defun
-
-@defun read-lines port
-Return a list of all lines read from port.
-@end defun
-
-@defun with-atomic-output-to-file filename thunk
-Same functionality as the regular @var{with-output-to-file}, but
-with the difference that either everything is written, or nothing
-is written, and if anything is written it's all written atomicaly at
-once (the original file will never contain an intermidiate state).
-Does NOT handle race conditions between threads.
-
-propagates the return value of @var{thunk} upon successfully writing
-the file, and @code{#f} otherwise.
-@end defun
-
-@defun call-with-tmpfile proc [#:tmpl ``/tmp/file-XXXXXXX'']
-@end defun
-
-@defun read-file path
-Open file at path, and return its content as a string.
-@end defun
-
-@node Binary Search Tree
-@section Binary Search Tree
-
-A simple ``read only'' binary search tree.
-
-@defun make-tree pred? lst
-Constructs a new tree. @var{pred?} should be a procedure taking the
-first element of @var{lst}, along with each element, and should return
-a boolean value indicating if the specific element should go in the
-left or right subtree. (left subtree is ``truthy'' values).
-
-This operation is done recursively.
-@end defun
-
-@defun tree-node tree
-Return the value of a tree node.
-@end defun
-
-@defun left-subtree tree
-Return all ``truthy'' children of tree node.
-@end defun
-
-@defun right-subtree tree
-Return all ``falsy children of tree node.
-@end defun
-
-@defun length-of-longest-branch tree
-Get the depth of a tree.
-@end defun
-
-@defun tree-map proc tree
-Apply proc onto the value of every node in tree, keeping the structure
-of the tree.
-
-@b{Note:} this can cause the tree to no longer be a binary search
-tree, but simply a ``formless'' binary tree.
-@end defun
-- 
cgit v1.2.3