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/calp.texi | 1 + doc/ref/guile.texi | 3 + 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 +- doc/ref/vulgar.texi | 261 +++++++++++++++++++++++++++++++++++ module/hnh/util.scm | 2 - module/scripts/find-undocumented.scm | 23 ++- module/vulgar/color.scm | 1 - 11 files changed, 417 insertions(+), 6 deletions(-) create mode 100644 doc/ref/guile/crypto.texi create mode 100644 doc/ref/guile/glob.texi create mode 100644 doc/ref/guile/graphviz.texi create mode 100644 doc/ref/vulgar.texi diff --git a/doc/ref/calp.texi b/doc/ref/calp.texi index a3ab4bf6..b9e8723d 100644 --- a/doc/ref/calp.texi +++ b/doc/ref/calp.texi @@ -67,6 +67,7 @@ text @footnote{Improvements welcome} @include guile.texi @include entry-points.texi @include text.texi +@include vulgar.texi @node Index @unnumbered Index diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 131d435c..1e8d44fd 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -13,6 +13,9 @@ @include guile/web.texi @include guile/vcomponent.texi @include guile/translation.texi +@include guile/glob.texi +@include guile/graphviz.texi +@include guile/crypto.texi @node Errors and Conditions @section Errors and Conditions 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. diff --git a/doc/ref/vulgar.texi b/doc/ref/vulgar.texi new file mode 100644 index 00000000..e98daaa0 --- /dev/null +++ b/doc/ref/vulgar.texi @@ -0,0 +1,261 @@ +@node Vulgar Terminal Interface +@chapter Vulgar Terminal Interface + +The Vulgar@footnote{Since it's not Curses} +Terminal Interface aims to be a simple way to semi advanced terminal +interfaces. + +@defun cls +Clear the screen, and move the cursor to the ``home''. +@end defun + +@defun set-cursor-pos x y +Move the cursor to the specified position on the screen. +@end defun + +@defun with-vulgar [bits] thunk +Runs @var{thunk} with +@code{iattr.lflag &= @var{bits}} and +@code{oattr.lflag &= @var{bite}}, along with +@command{tput civis} being run on entrance, and +@command{tput cnorm} being run on exit. + +The thunk is properly prepared on non-local entrances and exits. +@end defun + +@node Color +@section Color + +@defvar STR-RESET +ANSI escape sequence for removing all current formatting, as a string. +@end defvar + +@defmac color-if predicate color body ... +@code{(begin body ...)} is run, coloring it's return value using the +ANSI escape sequence @var{color}, if @var{predicate} is true, and +uncolored otherwise. +@end defmac + +@defun color-escape n +Generates an RGB color escape code. @var{n} can either be @code{#f}, +in which case the empty string is returned, or a a 24 bit color code +encoded hexadecimaly as @samp{#RRGGBB}. +@end defun + +@node Termios +@section Termios + +Interface to termios procedures. See termios(3) and @code{termios.h} +for general information. + +@code{(vulgar termios)} + +Refer to termios(3) for deeper information about all these fields. + +@deftp {Record Type} +See ``The termios structure'' in termios(3). +@defun make-termios +Create a new (empty) termios structure. +@end defun + +@defun cc termios +@defunx cflag termios +@defunx iflag termios +@defunx ispeed termios +@defunx lflag termios +@defunx line termios +@defunx oflag termios +@defunx ospeed termios +Accessors to termios each field. +@end defun +@end deftp + +@defun copy-termios termios +Create a copy of the given termios structure. +@end defun + +@defun tcsetattr! termios [port] [when=TCSANOW] +Updates @var{port} with flags from @var{termios}. +@end defun + +@defun tcgetattr! termios [port=(current-input-port)] +Gets termios information about @var{port}, and stores it in @var{termios}. +@end defun + +@defun cfmakeraw! termios +Calls the termios function @code{cfmakeraw} on @var{termios}, updating +the structure. +@end defun + + +@defvar TOSTOP +@defvarx NLDLY +@defvarx CREAD +@defvarx VSTOP +@defvarx B1500000 +@defvarx B4000000 +@defvarx B150 +@defvarx VEOL +@defvarx VQUIT +@defvarx CSTART +@defvarx CBAUD +@defvarx CR0 +@defvarx OLCUC +@defvarx CSTATUS +@defvarx VSTART +@defvarx IXANY +@defvarx ONOCR +@defvarx VERASE +@defvarx TTYDEF_IFLAG +@defvarx B1000000 +@defvarx NL0 +@defvarx FLUSHO +@defvarx TABDLY +@defvarx CDSUSP +@defvarx CEOL +@defvarx CIBAUD +@defvarx TAB3 +@defvarx CR2 +@defvarx NL1 +@defvarx CS8 +@defvarx CERASE +@defvarx OPOST +@defvarx TTYDEF_SPEED +@defvarx TAB1 +@defvarx EXTA +@defvarx B1200 +@defvarx TAB0 +@defvarx B75 +@defvarx EXTB +@defvarx FF1 +@defvarx CR1 +@defvarx CS5 +@defvarx INPCK +@defvarx B576000 +@defvarx B3000000 +@defvarx OCRNL +@defvarx TCOON +@defvarx CBAUDEX +@defvarx CCEQ +@defvarx IXOFF +@defvarx CREPRINT +@defvarx FF0 +@defvarx ECHONL +@defvarx IXON +@defvarx ISTRIP +@defvarx CSTOP +@defvarx PENDIN +@defvarx BRKINT +@defvarx IEXTEN +@defvarx TCIFLUSH +@defvarx VSUSP +@defvarx B38400 +@defvarx TCION +@defvarx B921600 +@defvarx ECHOPRT +@defvarx CQUIT +@defvarx IMAXBEL +@defvarx CRTSCTS +@defvarx ECHOCTL +@defvarx CEOT +@defvarx VMIN +@defvarx ICANON +@defvarx ONLRET +@defvarx VINTR +@defvarx CSTOPB +@defvarx B3500000 +@defvarx B230400 +@defvarx CS7 +@defvarx TCOFLUSH +@defvarx TIOCSER_TEMT +@defvarx B200 +@defvarx CSUSP +@defvarx BS1 +@defvarx XTABS +@defvarx CLNEXT +@defvarx VT0 +@defvarx NCCS +@defvarx BSDLY +@defvarx B9600 +@defvarx ECHOKE +@defvarx VEOF +@defvarx TTYDEF_OFLAG +@defvarx VTDLY +@defvarx VT1 +@defvarx CTRL +@defvarx NOFLSH +@defvarx VREPRINT +@defvarx ICRNL +@defvarx CINTR +@defvarx ADDRB +@defvarx B2500000 +@defvarx EXTPROC +@defvarx B110 +@defvarx XCASE +@defvarx ECHOE +@defvarx IUTF8 +@defvarx CS6 +@defvarx CFLUSH +@defvarx B500000 +@defvarx CKILL +@defvarx CDISCARD +@defvarx VDISCARD +@defvarx B2400 +@defvarx TTYDEF_CFLAG +@defvarx VWERASE +@defvarx INLCR +@defvarx ONLCR +@defvarx OFDEL +@defvarx B1800 +@defvarx ISIG +@defvarx IGNPAR +@defvarx TAB2 +@defvarx CTIME +@defvarx B1152000 +@defvarx ECHO +@defvarx CR3 +@defvarx CMSPAR +@defvarx PARENB +@defvarx B2000000 +@defvarx VKILL +@defvarx B4800 +@defvarx CLOCAL +@defvarx IGNBRK +@defvarx BS0 +@defvarx TCSAFLUSH +@defvarx B19200 +@defvarx TCSANOW +@defvarx VTIME +@defvarx B0 +@defvarx TCOOFF +@defvarx CEOF +@defvarx B460800 +@defvarx PARMRK +@defvarx VEOL2 +@defvarx FFDLY +@defvarx TCSADRAIN +@defvarx IGNCR +@defvarx CRDLY +@defvarx VLNEXT +@defvarx PARODD +@defvarx CRPRNT +@defvarx B600 +@defvarx VSWTC +@defvarx IUCLC +@defvarx HUPCL +@defvarx B50 +@defvarx TCIOFF +@defvarx TTYDEF_LFLAG +@defvarx CBRK +@defvarx ECHOK +@defvarx B115200 +@defvarx CSIZE +@defvarx B300 +@defvarx OFILL +@defvarx CWERASE +@defvarx B134 +@defvarx B57600 +@defvarx TCIOFLUSH +@defvarx CMIN +Imported from the ``termios.h'' header file. +@end defvar diff --git a/module/hnh/util.scm b/module/hnh/util.scm index 4bd06d11..91c081e2 100644 --- a/module/hnh/util.scm +++ b/module/hnh/util.scm @@ -6,7 +6,6 @@ :use-module ((srfi srfi-9 gnu) :select (set-fields)) :use-module ((ice-9 copy-tree) :select (copy-tree)) :use-module ((ice-9 control) :select (call/ec)) - :re-export (fold-values) :export (aif awhen for @@ -60,7 +59,6 @@ uniqx uniq univ - uniqv unique vector-last diff --git a/module/scripts/find-undocumented.scm b/module/scripts/find-undocumented.scm index 499f18d6..5aebcb25 100644 --- a/module/scripts/find-undocumented.scm +++ b/module/scripts/find-undocumented.scm @@ -7,6 +7,7 @@ :use-module (ice-9 regex) :use-module (ice-9 rdelim) :use-module (rnrs records syntactic) + :use-module (glob) :export (main) ) @@ -103,8 +104,20 @@ (define source-directory "module") (define doc-dir "doc/ref") (define skip-files - '("module/graphvis.scm" - "module/glob.scm")) + (append + '( + ;; Ignored since we arent't the implementor. + ;; It could however be nice to document it + "module/graphviz.scm" + ) + ;; Each entry-point should only export a main procedure, + ;; and is documented elsewhere + (glob "module/calp/entry-points/*.scm") + ;; These are scripts for `guild`. + ;; Each file exports a few pre-defined symbols, + ;; and are documented in other ways. + (glob "module/scripts/*.scm") + )) (define documented-symbols (concatenate @@ -130,6 +143,12 @@ (concatenate (for path in (all-modules-under-directory source-directory) (when (member path skip-files) + (continue '())) + + (define components* + (drop (path-split path) + (length (path-split source-directory)))) + (define name (map string->symbol (append (drop-right components* 1) diff --git a/module/vulgar/color.scm b/module/vulgar/color.scm index 5f9fbe40..91bd977f 100644 --- a/module/vulgar/color.scm +++ b/module/vulgar/color.scm @@ -1,7 +1,6 @@ (define-module (vulgar color) :export (color-if color-escape)) -(define-public STR-YELLOW "\x1b[0;33m") (define-public STR-RESET "\x1b[m") (define-syntax-rule (color-if pred color body ...) -- cgit v1.2.3