From 475307bc9926898e769c7ad6fa3a844853b07f52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= Date: Tue, 12 Sep 2023 10:04:04 +0200 Subject: Add a bunch of documentation. --- doc/ref/guile/crypto.texi | 17 +++++++++++ doc/ref/guile/glob.texi | 37 +++++++++++++++++++++++ doc/ref/guile/graphviz.texi | 10 +++++++ doc/ref/guile/util.texi | 66 ++++++++++++++++++++++++++++++++++++++++++ doc/ref/guile/xdg-basedir.texi | 2 +- 5 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 doc/ref/guile/crypto.texi create mode 100644 doc/ref/guile/glob.texi create mode 100644 doc/ref/guile/graphviz.texi (limited to 'doc/ref/guile') diff --git a/doc/ref/guile/crypto.texi b/doc/ref/guile/crypto.texi new file mode 100644 index 00000000..b9e362d3 --- /dev/null +++ b/doc/ref/guile/crypto.texi @@ -0,0 +1,17 @@ +@node Cryptographic and Hash Procedures +@section Cryptographic and Hash Procedures + +This module links libcrypto, exposing some hash procedures. + +@defun sha256 message +Calculate the sha256-sum of @var{message}. The message can either be a +bytevector or a string (in which case it will de encoded as UTF-8). + +Returns the checksum as a bytevector. +@end defun + +@defun checksum->string message-digest [port] +Generates a hex digest string from a checksum (generated by +@code{sha256}). The checksum is written to @var{port} if given, or +returned as a string otherwise. +@end defun diff --git a/doc/ref/guile/glob.texi b/doc/ref/guile/glob.texi new file mode 100644 index 00000000..400eb1f7 --- /dev/null +++ b/doc/ref/guile/glob.texi @@ -0,0 +1,37 @@ +@node Glob +@section Glob + +@defun glob str +Globs (glob(7)) on @var{str}, returing a list of files, which will be +on the same form of the glob. E.g. @code{(glob "../*")} will return +strings all starting with ``../'' + +If no matches are found, a misc error is thrown. +@end defun + + + +@defvar GLOB_NOMAGIC +@defvarx GLOB_NOCHECK +@defvarx unix +@defvarx GLOB_NOSPACE +@defvarx GLOB_TILDE_CHECK +@defvarx GLOB_ALTDIRFUNC +@defvarx GLOB_NOSORT +@defvarx GLOB_NOMATCH +@defvarx GLOB_TILDE +@defvarx GLOB_ERR +@defvarx GLOB_MAGCHAR +@defvarx GLOB_BRACE +@defvarx GLOB_APPEND +@defvarx GLOB_NOSYS +@defvarx GLOB_DOOFFS +@defvarx GLOB_NOESCAPE +@defvarx GLOB_MARK +@defvarx GLOB_PERIOD +@defvarx linux +@defvarx GLOB_ABORTED +@defvarx _POSIX_VDISABLE +@defvarx GLOB_ONLYDIR +``Symbols'' imported from the C header ``glob.h''. See that documentation. +@end defvar diff --git a/doc/ref/guile/graphviz.texi b/doc/ref/guile/graphviz.texi new file mode 100644 index 00000000..72817ea8 --- /dev/null +++ b/doc/ref/guile/graphviz.texi @@ -0,0 +1,10 @@ +@node Graphviz +@section Graphviz + +The graphviz library comes bundled with Guile bindings, but without a +corresponding .scm file exporting the symbols. The module @code{(guile)} does +exactly that. + +This ``header'' is borrowed from +@url{https://github.com/roelj/graphviz-guile/blob/master/graphviz.scm}, +under GPL 3.0. 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 diff --git a/doc/ref/guile/xdg-basedir.texi b/doc/ref/guile/xdg-basedir.texi index cdcf179b..2d3b2972 100644 --- a/doc/ref/guile/xdg-basedir.texi +++ b/doc/ref/guile/xdg-basedir.texi @@ -50,7 +50,7 @@ Defaults to @file{/etc/xdg}. @env{XDG_CACHE_HOME}, usually @file{~/.cache}. @end defun -@defun runtime_dir +@defun runtime-dir @findex XDG_RUNTIME_DIR If @env{XDG_RUNTIME_DIR} is set, than that is used. Otherwise a warning message is printed to stderr and @file{/tmp} is returned. -- cgit v1.2.3