xref: /dports/devel/guile-lib/guile-lib-0.2.6.1/doc/guile-library.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename guile-library.info
@settitle Guile Library
@c %**end of header

@copying
This manual is for Guile Library (version 0.2.6.1, updated July 2018)

Copyright 2003,2007,2010,2011,2016,2017,2018 Andy Wingo, Richard Todd

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published y the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

@end quotation

@end copying

@dircategory The Algorithmic Language Scheme
@direntry
* Guile Library: (guile-library.info).  Common modules for Guile Scheme.
@end direntry

@titlepage
@title Guile Library
@subtitle version 0.2.6.1, updated July 2018
@author Andy Wingo (@email{wingo at pobox.com})
@author Richard Todd (@email{richardt at vzavenue.net})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnottex
@node Top
@top Guile Library
@insertcopying
@menu
* apicheck::             Describe and verify library programming interfaces
* config load::          Loading configuration files
* container async-queue::  A thread-safe message queue
* container nodal-tree::  A tree consisting of nodes with attributes
* container delay-tree::  A nodal tree with lazily evaluated fields
* debugging assert::     Helpful assert macro
* debugging time::       A simple macro to time the execution of an expression
* graph topological-sort::  Routines to perform topological sorts
* htmlprag::             Neil Van Dyke's permissive ("pragmatic") HTML parser
* io string::            SLIB's IO routines dealing with strings
* logging logger::       A flexible logging system
* logging port-log::     A logger that outputs to a port
* logging rotating-log::  A logger that rotates its output files
* match-bind::           Nifty and concise regular expression routines
* math minima::          A golden-section minimum finder
* math primes::          Functions related to prime numbers and factorization
* os process::           Spawning processes and capturing their output
* scheme documentation::  Macros to define different kinds of variables with documentation
* scheme kwargs::        Defining functions with flexible keyword arguments
* search basic::         Classic search functions
* string completion::    Building blocks for tab completion
* string soundex::       The SOUNDEX string categorization algorithm
* string transform::     Beyond SRFI-13
* string wrap::          A versatile string formatter
* term ansi-color::      Generate ANSI color escape sequences
* unit-test::            A JUnit-style unit testing framework

* Copying This Manual::
* Concept Index::
* Function Index::
@end menu

@end ifnottex

@iftex
@shortcontents
@end iftex

@node apicheck
@chapter (apicheck)
@section Overview
@code{(apicheck)} exports two routines.  @code{apicheck-generate}
produces a description of the Scheme API exported by a set of modules as
an S-expression.  @code{apicheck-validate} verifies that the API
exported by a set of modules is compatible with an API description
generated by @code{apicheck-generate}.

It would be nice to have Makefile.am fragments here, but for now, see
the Guile-Library source distribution for information on how to
integrate apicheck with your module's unit test suite.

@section Usage
@anchor{apicheck apicheck-generate}@defun apicheck-generate module-names
Generate a description of the API exported by the set of modules
@var{module-names}.

@end defun

@anchor{apicheck apicheck-validate}@defun apicheck-validate api module-names
Validate that the API exported by the set of modules @var{module-names}
is compatible with the recorded API description @var{api}.  Raises an
exception if the interface is incompatible.

@end defun

@node config load
@chapter (config load)
@section Overview
@verbatim
 This module needs to be documented.
@end verbatim

@section Usage
@anchor{config load <configuration>}@deftp Class <configuration>
@end deftp

@anchor{config load load-config!}@deffn Generic load-config!
@end deffn

@deffn Method load-config!  (@var{cfg} @code{<configuration>}) (@var{commands} @code{<list>}) (@var{file-name} @code{<string>})
@end deffn

@anchor{config load &config-error}@defvar &config-error
@end defvar

@anchor{config load config-error-arguments}@defun config-error-arguments c
@end defun

@node container async-queue
@chapter (container async-queue)
@section Overview
A asynchronous queue can be used to safely send messages from one thread
to another.

@section Usage
@anchor{container async-queue make-async-queue}@defun make-async-queue
Create a new asynchronous queue.

@end defun

@anchor{container async-queue async-enqueue!}@defun async-enqueue! q elt
Enqueue @var{elt} into @var{q}.

@end defun

@anchor{container async-queue async-dequeue!}@defun async-dequeue! q
Dequeue a single element from @var{q}.  If the queue is empty, the
calling thread is blocked until an element is enqueued by another
thread.

@end defun

@node container nodal-tree
@chapter (container nodal-tree)
@section Overview
A nodal tree is a tree composed of nodes, each of which may have
children.  Nodes are represented as alists.  The only alist entry that
is specified is @code{children}, which must hold a list of child nodes.
Other entries are intentionally left unspecified, so as to allow for
extensibility.

@section Usage
@anchor{container nodal-tree nodal-tree?}@defun nodal-tree? x
Predicate to determine if @var{x} is a nodal tree.  Not particularly
efficient: intended for debugging purposes.

@end defun

@anchor{container nodal-tree make-node}@defun make-node . attributes
@end defun

@anchor{container nodal-tree node-ref}@defun node-ref node name
@end defun

@anchor{container nodal-tree node-set!}@defun node-set! node name val
@end defun

@anchor{container nodal-tree node-children}@defun node-children node
@end defun

@node container delay-tree
@chapter (container delay-tree)
@section Overview
A delay tree is a superset of a nodal tree (see (container nodal-tree)).
It extends nodal trees to allow any entry of the node to be a promise
created with the @code{delay} operator.

@section Usage
@anchor{container delay-tree force-ref}@defun force-ref node field
Access a field in a node of a delay tree.  If the value of the field is
a promise, the promise will be forced, and the value will be replaced
with the forced value.

@end defun

@node debugging assert
@chapter (debugging assert)
@section Overview
Defines an @code{assert} macro, and the @code{cout} and @code{cerr}
utility functions.

@section Usage
@anchor{debugging assert assert}@defspec assert doit (expr ...) (r-exp ...)
@defspecx assert collect (expr ...)
@defspecx assert collect (expr ...) report: r-exp ...
@defspecx assert collect (expr ...) expr1 stuff ...
@defspecx assert stuff ...
Assert the truth of an expression (or of a sequence of expressions).

syntax: @code{assert @var{?expr} @var{?expr} ... [report: @var{?r-exp}
@var{?r-exp} ...]}

If @code{(and @var{?expr} @var{?expr} ...)} evaluates to anything but
@code{#f}, the result is the value of that expression.  Otherwise, an
error is reported.

The error message will show the failed expressions, as well as the
values of selected variables (or expressions, in general).  The user may
explicitly specify the expressions whose values are to be printed upon
assertion failure -- as @var{?r-exp} that follow the identifier
@code{report:}.

Typically, @var{?r-exp} is either a variable or a string constant.  If
the user specified no @var{?r-exp}, the values of variables that are
referenced in @var{?expr} will be printed upon the assertion failure.

@end defspec

@anchor{debugging assert cout}@defun cout . args
Similar to @code{cout << arguments << args}, where @var{argument} can be
any Scheme object.  If it's a procedure (e.g.  @code{newline}), it's
called without args rather than printed.

@end defun

@anchor{debugging assert cerr}@defun cerr . args
Similar to @code{cerr << arguments << args}, where @var{argument} can be
any Scheme object.  If it's a procedure (e.g.  @code{newline}), it's
called without args rather than printed.

@end defun

@node debugging time
@chapter (debugging time)
@section Overview
@c it's really texinfo
Defines a macro to time execution of a body of expressions.  Each
element is timed individually.

@section Usage
@anchor{debugging time time}@defspec time args
syntax: @code{(time @var{expr1} @var{expr2}...)}

Times the execution of a list of expressions, in milliseconds.  The
resolution is limited to guile's @code{internal-time-units-per-second}.
Disregards the expressions' return value(s) (FIXME).

@end defspec

@node graph topological-sort
@chapter (graph topological-sort)
@section Overview
@verbatim
 The algorithm is inspired by Cormen, Leiserson and Rivest (1990)
 ``Introduction to Algorithms'', chapter 23.
@end verbatim

@section Usage
@anchor{graph topological-sort topological-sort}@defun topological-sort dag
Returns a list of the objects in the directed acyclic graph, @var{dag},
topologically sorted.  Objects are compared using @code{equal?}.  The
graph has the form:

@lisp
 (list (obj1 . (dependents-of-obj1))
       (obj2 . (dependents-of-obj2)) ...)
@end lisp

...specifying, for example, that @code{obj1} must come before all the
objects in @code{(dependents-of-obj1)} in the sort.

@end defun

@anchor{graph topological-sort topological-sortq}@defun topological-sortq dag
Returns a list of the objects in the directed acyclic graph, @var{dag},
topologically sorted.  Objects are compared using @code{eq?}.  The graph
has the form:

@lisp
 (list (obj1 . (dependents-of-obj1))
       (obj2 . (dependents-of-obj2)) ...)
@end lisp

...specifying, for example, that @code{obj1} must come before all the
objects in @code{(dependents-of-obj1)} in the sort.

@end defun

@anchor{graph topological-sort topological-sortv}@defun topological-sortv dag
Returns a list of the objects in the directed acyclic graph, @var{dag},
topologically sorted.  Objects are compared using @code{eqv?}.  The
graph has the form:

@lisp
 (list (obj1 . (dependents-of-obj1))
       (obj2 . (dependents-of-obj2)) ...)
@end lisp

...specifying, for example, that @code{obj1} must come before all the
objects in @code{(dependents-of-obj1)} in the sort.

@end defun

@node htmlprag
@chapter (htmlprag)
@section Overview
HtmlPrag provides permissive HTML parsing capability to Scheme programs,
which is useful for software agent extraction of information from Web
pages, for programmatically transforming HTML files, and for
implementing interactive Web browsers.  HtmlPrag emits ``SHTML,'' which
is an encoding of HTML in [SXML], so that conventional HTML may be
processed with XML tools such as [SXPath] and [SXML-Tools].  Like
[SSAX-HTML], HtmlPrag provides a permissive tokenizer, but also attempts
to recover structure.  HtmlPrag also includes procedures for encoding
SHTML in HTML syntax.

The HtmlPrag parsing behavior is permissive in that it accepts erroneous
HTML, handling several classes of HTML syntax errors gracefully, without
yielding a parse error.  This is crucial for parsing arbitrary
real-world Web pages, since many pages actually contain syntax errors
that would defeat a strict or validating parser.  HtmlPrag's handling of
errors is intended to generally emulate popular Web browsers'
interpretation of the structure of erroneous HTML.  We euphemistically
term this kind of parse ``pragmatic.''

HtmlPrag also has some support for [XHTML], although XML namespace
qualifiers [XML-Names] are currently accepted but stripped from the
resulting SHTML.  Note that valid XHTML input is of course better
handled by a validating XML parser like [SSAX].

To receive notification of new versions of HtmlPrag, and to be polled
for input on changes to HtmlPrag being considered, ask the author to add
you to the moderated, announce-only email list,
@code{htmlprag-announce}.

Thanks to Oleg Kiselyov and Kirill Lisovsky for their help with SXML.

@section Usage
@anchor{htmlprag shtml-comment-symbol}@defvar shtml-comment-symbol
@end defvar

@anchor{htmlprag shtml-decl-symbol}@defvar shtml-decl-symbol
@end defvar

@anchor{htmlprag shtml-empty-symbol}@defvar shtml-empty-symbol
@end defvar

@anchor{htmlprag shtml-end-symbol}@defvar shtml-end-symbol
@end defvar

@anchor{htmlprag shtml-entity-symbol}@defvar shtml-entity-symbol
@end defvar

@anchor{htmlprag shtml-named-char-id}@defvar shtml-named-char-id
@end defvar

@anchor{htmlprag shtml-numeric-char-id}@defvar shtml-numeric-char-id
@end defvar

@anchor{htmlprag shtml-pi-symbol}@defvar shtml-pi-symbol
@end defvar

@anchor{htmlprag shtml-start-symbol}@defvar shtml-start-symbol
@end defvar

@anchor{htmlprag shtml-text-symbol}@defvar shtml-text-symbol
@end defvar

@anchor{htmlprag shtml-top-symbol}@defvar shtml-top-symbol
@end defvar

@anchor{htmlprag html->shtml}@defun html->shtml input
@end defun

@anchor{htmlprag html->sxml}@defun html->sxml input
@end defun

@anchor{htmlprag html->sxml-0nf}@defun html->sxml-0nf input
@end defun

@anchor{htmlprag html->sxml-1nf}@defun html->sxml-1nf input
@end defun

@anchor{htmlprag html->sxml-2nf}@defun html->sxml-2nf input
@end defun

@anchor{htmlprag make-html-tokenizer}@defun make-html-tokenizer in normalized?
@end defun

@anchor{htmlprag parse-html/tokenizer}@defun parse-html/tokenizer tokenizer normalized?
@end defun

@anchor{htmlprag shtml->html}@defun shtml->html shtml
@end defun

@anchor{htmlprag shtml-entity-value}@defun shtml-entity-value entity
@end defun

@anchor{htmlprag shtml-token-kind}@defun shtml-token-kind token
@end defun

@anchor{htmlprag sxml->html}@defun sxml->html shtml
@end defun

@anchor{htmlprag test-htmlprag}@defun test-htmlprag
@end defun

@anchor{htmlprag tokenize-html}@defun tokenize-html in normalized?
@end defun

@anchor{htmlprag write-shtml-as-html}@defun write-shtml-as-html shtml out
@end defun

@anchor{htmlprag write-sxml-html}@defun write-sxml-html shtml out
@end defun

@node io string
@chapter (io string)
@section Overview
@c really, texinfo
Procedures that do io with strings.

@section Usage
@anchor{io string find-string-from-port?}@defun find-string-from-port? str <input-port> . max-no-char
Looks for @var{str} in @var{<input-port>}, optionally within the first
@var{max-no-char} characters.

@end defun

@node logging logger
@chapter (logging logger)
@section Overview
@anchor{cindex-logging}@cindex logging
@anchor{cindex-loggers relationship with handlers}@cindex loggers, relationship with handlers
@anchor{cindex-handlers relationship with loggers}@cindex handlers, relationship with loggers
@anchor{cindex-log levels}@cindex log levels
This is a logging subsystem similar to the one in the python standard
library.  There are two main concepts to understand when working with
the logging modules.  These are loggers and log handlers.

@table @asis
@item Loggers
Loggers are the front end interfaces for program logging.  They can be
registered by name so that no part of a program needs to be concerned
with passing around loggers.  In addition, a default logger can be
designated so that, for most applications, the program does not need to
be concerned with logger instances at all beyond the initial setup.

Log messages all flow through a logger.  Messages carry with them a
level (for example: 'WARNING, 'ERROR, 'CRITICAL), and loggers can filter
out messages on a level basis at runtime.  This way, the amount of
logging can be turned up during development and bug investigation, but
turned back down on stable releases.

Loggers depend on Log Handlers to actually get text to the log's
destination (for example, a disk file).  A single Logger can send
messages through multiple Log Handlers, effectively multicasting logs to
multiple destinations.

@item Log Handlers
Log Handlers actually route text to a destination.  One or more handlers
must be attached to a logger for any text to actually appear in a log.

Handlers apply a configurable transformation to the text so that it is
formatted properly for the destination (for instance: syslogs, or a text
file).  Like the loggers, they can filter out messages based on log
levels.  By using filters on both the Logger and the Handlers, precise
controls can be put on which log messages go where, even within a single
logger.

@end table

@section Example use of logger
Here is an example program that sets up a logger with two handlers.  One
handler sends the log messages to a text log that rotates its logs.  The
other handler sends logs to standard error, and has its levels set so
that INFO and WARN-level logs don't get through.

@lisp
(use-modules (logging logger)
             (logging rotating-log)
             (logging port-log)
             (scheme documentation)
             (oop goops))

 ----------------------------------------------------------------------
 Support functions
 ----------------------------------------------------------------------
(define (setup-logging)
  (let ((lgr       (make <logger>))
        (rotating  (make <rotating-log>
                     #:num-files 3
                     #:size-limit 1024
                     #:file-name "test-log-file"))
        (err       (make <port-log> #:port (current-error-port))))

    ;; don't want to see warnings or info on the screen!!
    (disable-log-level! err 'WARN)
    (disable-log-level! err 'INFO)

    ;; add the handlers to our logger
    (add-handler! lgr rotating)
    (add-handler! lgr err)

    ;; make this the application's default logger
    (set-default-logger! lgr)
    (open-log! lgr)))


(define (shutdown-logging)
  (flush-log)   ;; since no args, it uses the default
  (close-log!)  ;; since no args, it uses the default
  (set-default-logger! #f))

 ----------------------------------------------------------------------
 Main code
 ----------------------------------------------------------------------
(setup-logging)

 Due to log levels, this will get to file,
 but not to stderr
(log-msg 'WARN "This is a warning.")

 This will get to file AND stderr
(log-msg 'CRITICAL "ERROR message!!!")

(shutdown-logging)
@end lisp

@section Usage
@anchor{logging logger <log-handler>}@deftp Class <log-handler>
This is the base class for all of the log handlers, and encompasses the
basic functionality that all handlers are expected to have.  Keyword
arguments recognized by the @code{<log-handler>} at creation time are:

@table @code
@item #:formatter
This optional parameter must be a function that takes three arguments:
the log level, the time (as from @code{current-time}), and the log
string itself.  The function must return a string representing the
formatted log.

Here is an example invokation of the default formatter, and what it's
output looks like:

@lisp
 (default-log-formatter 'CRITICAL
                       (current-time)
                       "The servers are melting!")
==> "2003/12/29 14:53:02 (CRITICAL): The servers are melting!"
@end lisp

@end table

@end deftp

@anchor{logging logger emit-log}@deffn Generic emit-log
@code{emit-log handler str}.  This method should be implemented for all
the handlers.  This sends a string to their output media.  All level
checking and formatting has already been done by @code{accept-log}.

@end deffn

@anchor{logging logger accept-log}@deffn Generic accept-log
@code{accept-log handler lvl time str}.  If @var{lvl} is enabled for
@var{handler}, then @var{str} will be formatted and sent to the log via
the @code{emit-log} method.  Formatting is done via the formatting
function given at @var{handler}'s creation time, or by the default if
none was given.

This method should not normally need to be overridden by subclasses.
This method should not normally be called by users of the logging
system.  It is only exported so that writers of log handlers can
override this behavior.

@end deffn

@deffn Method accept-log  (@var{self} @code{<log-handler>}) (@var{level} @code{<top>}) (@var{time} @code{<top>}) (@var{str} @code{<top>})
@end deffn

@anchor{logging logger <logger>}@deftp Class <logger>
This is the class that aggregates and manages log handlers.  It also
maintains the global information about which levels of log messages are
enabled, and which have been suppressed.  Keyword arguments accepted on
creation are:

@table @code
@item #:handlers
This optional parameter must be a list of objects derived from
@code{<log-handler>}.  Handlers can always be added later via
@code{add-handler!} calls.

@end table

@end deftp

@anchor{logging logger add-handler!}@deffn Generic add-handler!
@code{add-handler! lgr handler}.  Adds @var{handler} to @var{lgr}'s list
of handlers.  All subsequent logs will be sent through the new handler,
as well as any previously registered handlers.

@end deffn

@deffn Method add-handler!  (@var{lgr} @code{<logger>}) (@var{handler} @code{<log-handler>})
@end deffn

@anchor{logging logger log-msg}@deffn Generic log-msg
@code{log-msg [lgr] lvl arg1 arg2 ...}.  Send a log message made up of
the @code{display}'ed representation of the given arguments.  The log is
generated at level @var{lvl}, which should be a symbol.  If the
@var{lvl} is disabled, the log message is not generated.  Generated log
messages are sent through each of @var{lgr}'s handlers.

If the @var{lgr} parameter is omitted, then the default logger is used,
if one is set.

As the args are @code{display}'ed, a large string is built up.  Then,
the string is split at newlines and sent through the log handlers as
independent log messages.  The reason for this behavior is to make
output nicer for log handlers that prepend information like pid and
timestamps to log statements.

@lisp
;; logging to default logger, level of WARN
 (log-msg 'WARN "Warning! " x " is bigger than " y "!!!")

;; looking up a logger and logging to it
 (let ((l (lookup-logger "main")))
     (log-msg l 'CRITICAL "FAILURE TO COMMUNICATE!")
     (log-msg l 'CRITICAL "ABORTING NOW"))
@end lisp

@end deffn

@deffn Method log-msg  (@var{lgr} @code{<logger>}) (@var{lvl} @code{<top>}) (@var{objs} @code{<top>})...
@end deffn

@deffn Method log-msg  (@var{lvl} @code{<symbol>}) (@var{objs} @code{<top>})...
@end deffn

@anchor{logging logger set-default-logger!}@defun set-default-logger! lgr
Sets the given logger, @var{lgr}, as the default for logging methods
where a logger is not given.  @var{lgr} can be an instance of
@code{<logger>}, a string that has been registered via
@code{register-logger!}, or @code{#f} to remove the default logger.

With this mechanism, most applications will never need to worry about
logger registration or lookup.

@lisp
;; example 1
 (set-default-logger! "main")  ;; look up "main" logger and make it the default

;; example 2
 (define lgr (make  <logger>))
 (add-handler! lgr
              (make <port-handler>
                    #:port (current-error-port)))
 (set-default-logger! lgr)
 (log-msg 'CRITICAL "This is a message to the default logger!!!")
 (log-msg lgr 'CRITICAL "This is a message to a specific logger!!!")
@end lisp

@end defun

@anchor{logging logger register-logger!}@defun register-logger! str lgr
Makes @var{lgr} accessible from other parts of the program by a name
given in @var{str}.  @var{str} should be a string, and @var{lgr} should
be an instance of class @code{<logger>}.

@lisp
 (define main-log  (make <logger>))
 (define corba-log (make <logger>))
 (register-logger! "main" main-log)
 (register-logger! "corba" corba-log)

;; in a completely different part of the program....
 (log-msg (lookup-logger "corba") 'WARNING "This is a corba warning.")
@end lisp

@end defun

@anchor{logging logger lookup-logger}@defun lookup-logger str
Looks up an instance of class @code{<logger>} by the name given in
@var{str}.  The string should have already been registered via a call to
@code{register-logger!}.

@end defun

@anchor{logging logger enable-log-level!}@defun enable-log-level! lgr lvl
Enables a specific logging level given by the symbol @var{lvl}, such
that messages at that level will be sent to the log handlers.  @var{lgr}
can be of type @code{<logger>} or @code{<log-handler>}.

Note that any levels that are neither enabled or disabled are treated as
enabled by the logging system.  This is so that misspelt level names do
not cause a logging blackout.

@end defun

@anchor{logging logger disable-log-level!}@defun disable-log-level! lgr lvl
Disables a specific logging level, such that messages at that level will
not be sent to the log handlers.  @var{lgr} can be of type
@code{<logger>} or @code{<log-handler>}.

Note that any levels that are neither enabled or disabled are treated as
enabled by the logging system.  This is so that misspelt level names do
not cause a logging blackout.

@end defun

@anchor{logging logger flush-log}@deffn Generic flush-log
@code{flush-log handler}.  Tells the @code{handler} to output any log
statements it may have buffered up.  Handlers for which a flush
operation doesn't make sense can choose not to implement this method.
The default implementation just returns @code{#t}.

@end deffn

@deffn Method flush-log  (@var{lgr} @code{<logger>})
@end deffn

@deffn Method flush-log
@end deffn

@deffn Method flush-log  (@var{lh} @code{<log-handler>})
@end deffn

@anchor{logging logger open-log!}@deffn Generic open-log!
@code{open-log! handler}.  Tells the @code{handler} to open its log.
Handlers for which an open operation doesn't make sense can choose not
to implement this method.  The default implementation just returns
@code{#t}.

@end deffn

@deffn Method open-log!
@end deffn

@deffn Method open-log!  (@var{lgr} @code{<logger>})
@end deffn

@deffn Method open-log!  (@var{lh} @code{<log-handler>})
@end deffn

@anchor{logging logger close-log!}@deffn Generic close-log!
@code{open-log! handler}.  Tells the @code{handler} to close its log.
Handlers for which a close operation doesn't make sense can choose not
to implement this method.  The default implementation just returns
@code{#t}.

@end deffn

@deffn Method close-log!
@end deffn

@deffn Method close-log!  (@var{lgr} @code{<logger>})
@end deffn

@deffn Method close-log!  (@var{lh} @code{<log-handler>})
@end deffn

@node logging port-log
@chapter (logging port-log)
@section Overview
@anchor{cindex-logs through ports}@cindex logs, through ports
@anchor{cindex-ports for logging}@cindex ports, for logging
This module defines a log handler that writes to an arbitrary port of
the user's choice.  Uses of this handler could include:

@itemize @bullet
@item
Sending logs across a socket to a network log collector.

@item
Sending logs to the screen

@item
Sending logs to a file

@item
Collecting logs in memory in a string port for later use

@end itemize

@section Usage
@anchor{logging port-log <port-log>}@deftp Class <port-log>
This is a log handler which writes logs to a user-provided port.

Keywords recognized by @code{<port-log>} on creation are:

@table @code
@item #:port
This is the port to which the log handler will write.

@item #:formatter
Allows the user to provide a function to use as the log formatter for
this handler.  @xref{logging logger <log-handler>}, for details.

@end table

Example of creating a @code{<port-log>}:

@lisp
 (make <port-log> #:port (current-error-port))
@end lisp

@end deftp

@node logging rotating-log
@chapter (logging rotating-log)
@section Overview
@anchor{cindex-logs rotating}@cindex logs, rotating
This module defines a log handler for text logs that rotate when they
get to be a user-defined size.  This is similar to the behavior of many
UNIX standard log files.  @xref{logging logger}, for more information in
general on log handlers.

@section Usage
@anchor{logging rotating-log <rotating-log>}@deftp Class <rotating-log>
This is a log handler which writes text logs that rotate when they reach
a configurable size limit.

Keywords recognized by @code{<rotating-log>} on creation are:

@table @code
@item #:num-files
This is the number of log files you want the logger to use.  Default is
4.

@item #:size-limit
This is the size, in bytes, a log file must get before the logs get
rotated.  Default is 1MB (104876 bytes).

@item #:file-name
This is the base of the log file name.  Default is ``logfile''.  Numbers
will be appended to the file name representing the log number.  The
newest log file is always ``@var{NAME}.1''.

@item #:formatter
Allows the user to provide a function to use as the log formatter for
this handler.  @xref{logging logger <log-handler>}, for details.

@end table

Example of creating a @code{<rotating-log>}:

@lisp
 (make <rotating-log>
      #:num-files 3
      #:size-limit 1024
      #:file-name "test-log-file"))
@end lisp

@end deftp

@node match-bind
@chapter (match-bind)
@section Overview
@c
Utility functions and syntax constructs for dealing with regular
expressions in a concise manner.  Will be submitted to Guile for
inclusion.

@section Usage
@anchor{match-bind match-bind}@defspec match-bind
Match a string against a regular expression, binding lexical variables
to the various parts of the match.

@var{vars} is a list of names to which to bind the parts of the match.
The first variable of the list will be bound to the entire match, so the
number of variables needed will be equal to the number of open
parentheses (`(') in the pattern, plus one for the whole match.

@var{consequent} is executed if the given expression @var{str} matches
@var{regex}.  If the string does not match, @var{alternate} will be
executed if present.  If @var{alternate} is not present, the result of
@code{match-bind} is unspecified.

Here is a short example:

@example
 (define (star-indent line)
   "Returns the number of spaces until the first
    star (`*') in the input, or #f if the first
    non-space character is not a star."
   (match-bind "^( *)\*.*$" line (_ spaces)
               (string-length spaces)
               #f))
@end example

@code{match-bind} compiles the regular expression @var{regex} at macro
expansion time.  For this reason, @var{regex} must be a string literal,
not an arbitrary expression.

@end defspec

@anchor{match-bind s///}@defun s/// pat subst
Make a procedure that performs perl-like regular expression
search-and-replace on an input string.

The regular expression pattern @var{pat} is in the standard regular
expression syntax accepted by @code{make-regexp}.  The substitution
string is very similar to perl's @code{s///} operator.  Backreferences
are indicated with a dollar sign (@samp{$}), and characters can be
escaped with the backslash.

@code{s///} returns a procedure of one argument, the input string to be
matched.  If the string matches the pattern, it will be returned with
the first matching segment replaced as per the substitution string.
Otherwise the string will be returned unmodified.

Here are some examples:

@example
 ((s/// "foo" "bar") "foo bar baz qux foo")
    @result{} "bar bar baz qux foo"

 ((s/// "zag" "bar") "foo bar baz qux foo")
    @result{} "foo bar baz qux foo"

 ((s/// "(f(o+)) (zag)?" "$1 $2 $3")
  "foo bar baz qux foo")
    @result{} "foo oo bar baz qux foo"
@end example

@end defun

@anchor{match-bind s///g}@defun s///g pat subst
Make a procedure that performs perl-like global search-and-replace on an
input string.

The @var{pat} and @var{subst} arguments are as in the non-global
@code{s///}.  @xref{match-bind s///,,s///}, for more information.

@code{s///g} differs from @code{s///} in that it does a global search
and replace, not stopping at the first match.

@end defun

@node math minima
@chapter (math minima)
@section Overview
@anchor{cindex-golden section}@cindex golden section
@anchor{cindex-section golden}@cindex section, golden
@anchor{cindex-minimum of a mathematical function}@cindex minimum, of a mathematical function
This module contains functions for computing the minimum values of
mathematical expressions on an interval.

@section Usage
@anchor{math minima golden-section-search}@defun golden-section-search f x0 x1 prec
The Golden Section Search algorithm finds minima of functions which are
expensive to compute or for which derivatives are not available.
Although optimum for the general case, convergence is slow, requiring
nearly 100 iterations for the example (x^3-2x-5).

If the derivative is available, Newton-Raphson is probably a better
choice.  If the function is inexpensive to compute, consider
approximating the derivative.

@var{x0} and @var{x1} are real numbers.  The (single argument) procedure
@var{func} is unimodal over the open interval (@var{x0}, @var{x1}).  That
is, there is exactly one point in the interval for which the derivative
of @var{func} is zero.

It returns a pair (@var{x} .  @var{func}(@var{x})) where
@var{func}(@var{x}) is the minimum.  The @var{prec} parameter is the
stop criterion.  If @var{prec} is a positive number, then the iteration
continues until @var{x} is within @var{prec} from the true value.  If
@var{prec} is a negative integer, then the procedure will iterate
@var{-prec} times or until convergence.  If @var{prec} is a procedure of
seven arguments, @var{x0}, @var{x1}, @var{a}, @var{b}, @var{fa},
@var{fb}, and @var{count}, then the iterations will stop when the
procedure returns @code{#t}.

Analytically, the minimum of x^3-2x-5 is 0.816497.

@example
 (define func (lambda (x) (+ (* x (+ (* x x) -2)) -5)))
 (golden-section-search func 0 1 (/ 10000))
      ==> (816.4883855245578e-3 . -6.0886621077391165)
 (golden-section-search func 0 1 -5)
      ==> (819.6601125010515e-3 . -6.088637561916407)
 (golden-section-search func 0 1
                       (lambda (a b c d e f g ) (= g 500)))
      ==> (816.4965933140557e-3 . -6.088662107903635)
@end example

@end defun

@node math primes
@chapter (math primes)
@section Overview
@anchor{cindex-prime number}@cindex prime number
@anchor{cindex-numbers prime}@cindex numbers, prime
@anchor{cindex-numbers prime factors of}@cindex numbers, prime factors of
@anchor{cindex-prime factors}@cindex prime factors
@anchor{cindex-factors prime}@cindex factors, prime
This module defines functions related to prime numbers, and prime
factorization.

@section Usage
@anchor{math primes prime:trials}@defvar prime:trials
This is the maximum number of iterations of Solovay-Strassen that will
be done to test a number for primality.  The chance of error (a
composite being labelled prime) is @code{(expt 2 (- prime:trials))}.

@end defvar

@anchor{math primes prime?}@defun prime? n
Returns @code{#f} if @var{n} is composite, and @code{t} if it is prime.
There is a slight chance, @code{(expt 2 (- prime:trials))}, that a
composite will return @code{#t}.

@end defun

@anchor{math primes prime>}@defun prime> start
Return the first prime number greater than @var{start}.  It doesn't
matter if @var{start} is prime or composite.

@end defun

@anchor{math primes primes>}@defun primes> start count
Returns a list of the first @var{count} prime numbers greater than
@var{start}.

@end defun

@anchor{math primes prime<}@defun prime< start
Return the first prime number less than @var{start}.  It doesn't matter
if @var{start} is prime or composite.  If no primes are less than
@var{start}, @code{#f} will be returned.

@end defun

@anchor{math primes primes<}@defun primes< start count
Returns a list of the first @var{count} prime numbers less than
@var{start}.  If there are fewer than @var{count} prime numbers less
than @var{start}, then the returned list will have fewer than
@var{start} elements.

@end defun

@anchor{math primes factor}@defun factor k
Returns a list of the prime factors of @var{k}.  The order of the
factors is unspecified.  In order to obtain a sorted list do
@code{(sort! (factor @var{k}) <)}.

@end defun

@node os process
@chapter (os process)
@section Overview
@anchor{cindex-Goosh module}@cindex Goosh module
@anchor{cindex-process Operating System}@cindex process, Operating System
@anchor{cindex-process chain}@cindex process chain
@anchor{cindex-pipeline process}@cindex pipeline, process
This is a library for execution of other programs from Guile.  It also
allows communication using pipes (or a pseudo terminal device, but
that's not currently implemented).  This code originates in the
@code{(goosh)} modules, which itself was part of goonix in one of
Guile's past lives.

The following will hold when starting programs:

@enumerate
@item
If the name of the program does not contain a @code{/} then the
directories listed in the current @code{PATH} environment variable are
searched to locate the program.

@item
Unlike for the corresponding primitive exec procedures, e.g.,
@code{execlp}, the name of the program can not be set independently of
the path to execute: the zeroth and first members of the argument vector
are combined into one.

@end enumerate

All symbols exported with the prefix @code{os:process:} are there in
support of macros that use them.  They should be ignored by users of
this module.

@section Usage
@anchor{os process os:process:pipe-fork-child}@defspec os:process:pipe-fork-child
@end defspec

@anchor{os process run+}@defspec run+ args
Evaluate an expression in a new foreground process and wait for its
completion.  If no connection terms are specified, then all ports except
@code{current-input-port}, @code{current-output-port} and
@code{current-error-port} will be closed in the new process.  The file
descriptors underlying these ports will not be changed.

The value returned is the exit status from the new process as returned
by the @code{waitpid} procedure.

The @var{keywords} and @var{connections} arguments are optional: see
@code{run-concurrently+}, which is documented below.  The
@code{#:foreground} keyword is implied.

@example
 (run+ (begin (write (+ 2 2)) (newline) (quit 0)))
@end example

@example
 (run+ (tail-call-program "cat" "/etc/passwd"))
@end example

@end defspec

@anchor{os process run-concurrently+}@defspec run-concurrently+ args
Evaluate an expression in a new background process.  If no connection
terms are specified, then all ports except @code{current-input-port},
@code{current-output-port} and @code{current-error-port} will be closed
in the new process.  The file descriptors underlying these ports will
not be changed.

The value returned in the parent is the pid of the new process.

When the process terminates its exit status can be collected using the
@code{waitpid} procedure.

Keywords can be specified before the connection list:

@code{#:slave} causes the new process to be put into a new session.  If
@code{current-input-port} (after redirections) is a tty it will be
assigned as the controlling terminal.  This option is used when
controlling a process via a pty.

@code{#:no-auto-close} prevents the usual closing of ports which occurs
by default.

@code{#:foreground} makes the new process the foreground job of the
controlling terminal, if the current process is using job control.  (not
currently implemented).  The default is to place it into the background

The optional connection list can take several forms:

@code{(port)} usually specifies that a given port not be closed.  However
if @code{#:no-auto-close} is present it specifies instead a port which
should be closed.

@code{(port 0)} specifies that a port be moved to a given file
descriptor (e.g., 0) in the new process.  The order of the two
components is not significant, but one must be a number and the other
must evaluate to a port.  If the file descriptor is one of the standard
set @code{(0, 1, 2)} then the corresponding standard port (e.g.,
@code{current-input-port}) will be set to the specified port.

Example:

@example
 (let ((p (open-input-file "/etc/passwd")))
   (run-concurrently+ (tail-call-program "cat") (p 0)))
@end example

@end defspec

@anchor{os process tail-call-pipeline}@defspec tail-call-pipeline args
Replace the current process image with a pipeline of connected
processes.

The expressions in the pipeline are run in new background processes.  The
foreground process waits for them all to terminate.  The exit status is
derived from the status of the process at the tail of the pipeline: its
exit status if it terminates normally, otherwise 128 plus the number of
the signal that caused it to terminate.

The signal handlers will be reset and file descriptors set up as for
@code{tail-call-program}.  Like @code{tail-call-program} it does not
close open ports or flush buffers.

Example:

@example
 (tail-call-pipeline ("ls" "/etc") ("grep" "passwd"))
@end example

@end defspec

@anchor{os process tail-call-pipeline+}@defspec tail-call-pipeline+ args
Replace the current process image with a pipeline of connected
processes.

Each process is specified by an expression and each pair of processes
has a connection list with pairs of file descriptors.  E.g., @code{((1
0) (2 0))} specifies that file descriptors 1 and 2 are to be connected
to file descriptor 0.  This may also be written as @code{((1 2 0))}.

The expressions in the pipeline are run in new background processes.  The
foreground process waits for them all to terminate.  The exit status is
derived from the status of the process at the tail of the pipeline: its
exit status if it terminates normally, otherwise 128 plus the number of
the signal that caused it to terminate.

The signal handlers will be reset and file descriptors set up as for
@code{tail-call-program}.  Like @code{tail-call-program} it does not
close open ports or flush buffers.

Example:

@example
 (tail-call-pipeline+ (tail-call-program "ls" "/etc") ((1 0))
                      (tail-call-program "grep" "passwd"))
@end example

@end defspec

@anchor{os process os:process:new-comm-pipes}@defun os:process:new-comm-pipes old-pipes out-conns
@end defun

@anchor{os process os:process:pipe-make-commands}@defun os:process:pipe-make-commands fdes port portvar
@end defun

@anchor{os process os:process:pipe-make-redir-commands}@defun os:process:pipe-make-redir-commands connections portvar
@end defun

@anchor{os process os:process:setup-redirected-port}@defun os:process:setup-redirected-port port fdes
@end defun

@anchor{os process run}@defun run prog . args
Execute @var{prog} in a new foreground process and wait for its
completion.  The value returned is the exit status of the new process as
returned by the @code{waitpid} procedure.

Example:

@example
 (run "cat" "/etc/passwd")
@end example

@end defun

@anchor{os process run-concurrently}@defun run-concurrently . args
Start a program running in a new background process.  The value returned
is the pid of the new process.

When the process terminates its exit status can be collected using the
@code{waitpid} procedure.

Example:

@example
 (run-concurrently "cat" "/etc/passwd")
@end example

@end defun

@anchor{os process run-with-pipe}@defun run-with-pipe mode prog . args
Start @var{prog} running in a new background process.  The value
returned is a pair: the CAR is the pid of the new process and the CDR is
either a port or a pair of ports (with the CAR containing the input port
and the CDR the output port).  The port(s) can be used to read from the
standard output of the process and/or write to its standard input,
depending on the @var{mode} setting.  The value of @var{mode} should be
one of "r", "w" or "r+".

When the process terminates its exit status can be collected using the
@code{waitpid} procedure.

Example:

@example
 (use-modules (ice-9 rdelim)) ; needed by read-line
 (define catport (cdr (run-with-pipe "r" "cat" "/etc/passwd")))
 (read-line catport)
@end example

@end defun

@anchor{os process tail-call-program}@defun tail-call-program prog . args
Replace the current process image by executing @var{prog} with the
supplied list of arguments, @var{args}.

This procedure will reset the signal handlers and attempt to set up file
descriptors as follows:

@enumerate
@item
File descriptor 0 is set from (current-input-port).

@item
File descriptor 1 is set from (current-output-port).

@item
File descriptor 2 is set from (current-error-port).

@end enumerate

If a port can not be used (e.g., because it's closed or it's a string
port) then the file descriptor is opened on the file specified by
@code{*null-device*} instead.

Note that this procedure does not close any ports or flush output
buffers.  Successfully executing @var{prog} will prevent the normal
flushing of buffers that occurs when Guile terminates.  Doing otherwise
would be incorrect after forking a child process, since the buffers
would be flushed in both parent and child.

Examples:

@example
 (tail-call-program "cat" "/etc/passwd")
@end example

@example
 (with-input-from-file "/etc/passwd"
  (lambda ()
    (tail-call-program "cat")))
@end example

@end defun

@node scheme documentation
@chapter (scheme documentation)
@section Overview
@c texinfo commentary
Defines some macros to help in documenting macros, variables, generic
functions, and classes.

@section Usage
@anchor{scheme documentation define-macro-with-docs}@defspec define-macro-with-docs args
Define a macro with documentation.

@end defspec

@anchor{scheme documentation define-with-docs}@defspec define-with-docs args
Define a variable with documentation.

@end defspec

@anchor{scheme documentation define-generic-with-docs}@defspec define-generic-with-docs args
Define a generic function with documentation.

@end defspec

@anchor{scheme documentation define-class-with-docs}@defspec define-class-with-docs args
Define a class with documentation.

@end defspec

@node scheme kwargs
@chapter (scheme kwargs)
@section Overview
@c
Support for defining functions that take python-like keyword arguments.
In one of his early talks, Paul Graham wrote about a large system called
"Rtml":

@quotation
Most of the operators in Rtml were designed to take keyword parameters,
and what a help that turned out to be.  If I wanted to add another
dimension to the behavior of one of the operators, I could just add a
new keyword parameter, and everyone's existing templates would continue
to work.  A few of the Rtml operators didn't take keyword parameters,
because I didn't think I'd ever need to change them, and almost every
one I ended up kicking myself about later.  If I could go back and start
over from scratch, one of the things I'd change would be that I'd make
every Rtml operator take keyword parameters.

@end quotation

@xref{scheme kwargs lambda/kwargs,,lambda/kwargs}, for documentation and
examples.

@xref{Optional Arguments,,,guile,Guile Reference Manual}, for more
information on Guile's standard support for optional and keyword
arguments.  Quote taken from
@uref{http://lib.store.yahoo.net/lib/paulgraham/bbnexcerpts.txt}.

@section Usage
@anchor{scheme kwargs define/kwargs}@defspec define/kwargs args
Defines a function that takes kwargs.  @xref{scheme kwargs
lambda/kwargs}, for more information.

@end defspec

@anchor{scheme kwargs lambda/kwargs}@defspec lambda/kwargs args
Defines a function that takes keyword arguments.

@var{bindings} is a list of bindings, each of which may either be a
symbol or a two-element symbol-and-default-value list.  Symbols without
specified default values will default to @code{#f}.

For example:

@example
 (define frobulate (lambda/kwargs (foo (bar 13) (baz 42))
                     (list foo bar baz)))
 (frobulate) @result{} (#f 13 42)
 (frobulate #:baz 3) @result{} (#f 13 3)
 (frobulate #:foo 3) @result{} (3 13 42)
 (frobulate 3 4) @result{} (3 4 42)
 (frobulate 1 2 3) @result{} (1 2 3)
 (frobulate #:baz 2 #:bar 1) @result{} (#f 1 2)
 (frobulate 10 20 #:foo 3) @result{} (3 20 42)
@end example

This function differs from the standard @code{lambda*} provided by Guile
in that invoking the function will accept positional arguments.  As an
example, the @code{lambda/kwargs} behaves more intuitively in the
following case:

@example
 ((lambda* (#:optional (bar 42) #:key (baz 73))
    (list bar baz))
  1 2) @result{} (1 73)
 ((lambda/kwargs ((bar 42) (baz 73))
    (list bar baz))
  1 2) @result{} (1 2)
@end example

The fact that @code{lambda*} accepts the extra @samp{2} argument is
probably just a bug.  In any case, @code{lambda/kwargs} does the right
thing.

@end defspec

@node search basic
@chapter (search basic)
@section Overview
@verbatim
 This module has the classic search functions in it.
@end verbatim

@section Usage
@anchor{search basic depth-first-search}@defun depth-first-search init done? expander
Performs a depth-first search from initial state @var{init}.  It will
return the first state it sees for which predicate @var{done?} returns
@code{#t}.  It will use function @var{expander} to get a list of all
states reacheable from a given state.

@var{init} can take any form the user wishes.  This function treats it
as opaque data to pass to @var{done?} and @var{expander}.

@var{done?} takes one argument, of the same type as @var{init}, and
returns either @code{#t} or @code{#f}.

@var{expander} takes one argument, of the same type as @var{init}, and
returns a list of states that can be reached from there.

@end defun

@anchor{search basic breadth-first-search}@defun breadth-first-search init done? expander
Performs a breadth-first search from initial state @var{init}.  It will
return the first state it sees for which predicate @var{done?} returns
@code{#t}.  It will use function @var{expander} to get a list of all
states reacheable from a given state.

@var{init} can take any form the user wishes.  This function treats it
as opaque data to pass to @var{done?} and @var{expander}.

@var{done?} takes one argument, of the same type as @var{init}, and
returns either @code{#t} or @code{#f}.

@var{expander} takes one argument, of the same type as @var{init}, and
returns a list of states that can be reached from there.

@end defun

@anchor{search basic binary-search-sorted-vector}@defun binary-search-sorted-vector vec target [cmp] [default]
Searches a sorted vector @var{vec} for item @var{target}.  A binary
search is employed which should find an item in O(log n) time if it is
present.  If @var{target} is found, the index into @var{vec} is
returned.

As part of the search, the function @var{cmp} is applied to determine
whether a vector item is less than, greater than, or equal to the
@var{target}.  If @var{target} cannot be found in the vector, then
@var{default} is returned.

@var{cmp} defaults to @code{-}, which gives a correct comparison for
vectors of numbers.  @var{default} will be @code{#f} if another value is
not given.

@lisp
 (binary-search-sorted-vector #(10 20 30) 20) @result{} 1
@end lisp

@end defun

@node string completion
@chapter (string completion)
@section Overview
This module provides a facility that can be used to implement features
such as TAB-completion in programs.  A class @code{<string-completer>}
tracks all the potential complete strings.  Here is an example usage.

@lisp
(use-modules (string completion)
             (oop goops)
             (srfi srfi-11))      ;; for the (let-values)

(define c (make <string-completer>))
(add-strings! c "you your yourself yourselves")

(let-values (((completions expansion exact? unique?) (complete c "yours")))
            (display completions)(newline)
            (display expansion) (newline)
            (display exact?)(newline)
            (display unique?)(newline))

==> ("yourself" "yourselves")
    "yoursel"
    #f
    #f
@end lisp

There are several more options for usage, which are detailed in the
class and method documentation.

@section Usage
@anchor{string completion <string-completer>}@deftp Class <string-completer>
This is the class that knows what the possible expansions are, and can
determine the completions of given partial strings.  The following are
the recognized keywords on the call to @code{make}:

@table @code
@item #:strings
This gives the completer an initial set of strings.  It is optional, and
the @code{add-strings!} method can add strings to the completer later,
whether these initial strings were given or not.  The strings that
follow this keyword can take any form that the @code{add-strings!}
method can take (see below).

@item #:case-sensitive?
This is a boolean that directs the completer to do its comparisons in a
case sensiteve way or not.  The default value is @code{#t}, for
case-sensitive behavior.

@end table

@end deftp

@anchor{string completion case-sensitive-completion?}@deffn Generic case-sensitive-completion?
@code{case-sensitive-completion? completer}.  Returns @code{#t} if the
completer is case-sensitive, and @code{#f} otherwise.

@end deffn

@deffn Method case-sensitive-completion?
@end deffn

@anchor{string completion add-strings!}@deffn Generic add-strings!
@code{add-strings! completer strings}.  Adds the given strings to the
set of possible comletions known to @var{completer}.  @var{strings} can
either be a list of strings, or a single string of words separated by
spaces.  The order of the words given is not important.

@end deffn

@deffn Method add-strings!  (@var{sc} @code{<string-completer>}) (@var{strings} @code{<top>})
@end deffn

@anchor{string completion all-completions}@defun all-completions completer str
Returns a list of all possible completions for the given string
@var{str}.  The returned list will be in alphabetical order.

Note that users wanting to customize the completion algorithm can
subclass @code{<string-completer>} and override this method.

@end defun

@anchor{string completion complete}@deffn Generic complete
@code{complete completer str}.  Accepts a string, @var{str}, and returns
four values via a @code{values} call.  These are:

@table @var
@item completions
This is the same list that would be returned from a call to
@code{all-completions}.

@item expansion
This is the longest string that would have returned identical results.
In other words, this is what most programs replace your string with when
you press TAB once.  This value will be equal to @var{str} if there were
no known completionss.

@example
 ("wonders" "wonderment" "wondering")
completed against "won" yields an expansion
of "wonder"
@end example

@item exact?
This will be @code{#t} if the returned @var{expansion} is an exact match
of one of the possible completions.

@item unique?
This will be #t if there is only one possible completion.  Note that
when @var{unique?} is @code{#t}, then @var{exact?} will also be
@code{#t}.

@end table

@end deffn

@deffn Method complete  (@var{sc} @code{<string-completer>}) (@var{str} @code{<top>})
@end deffn

@node string soundex
@chapter (string soundex)
@section Overview
Soundex algorithm, taken from Knuth, Vol.  3 ``Sorting and searching'',
pp 391--2

@section Usage
@anchor{string soundex soundex}@defun soundex name
Performs the original soundex algorithm on the input @var{name}.  Returns
the encoded string.  The idea is for similar sounding sames to end up
with the same encoding.

@lisp
 (soundex "Aiza")
=> "A200"
 (soundex "Aisa")
=> "A200"
 (soundex "Aesha")
=> "A200"
@end lisp

@end defun

@node string transform
@chapter (string transform)
@section Overview
Module @samp{(string transform)} provides functions for modifying
strings beyond that which is provided in the guile core and @samp{(srfi
srfi-13)}.

@section Usage
@anchor{string transform escape-special-chars}@defun escape-special-chars str special-chars escape-char
Returns a copy of @var{str} with all given special characters preceded
by the given @var{escape-char}.

@var{special-chars} can either be a single character, or a string
consisting of all the special characters.

@lisp
;; make a string regexp-safe...
 (escape-special-chars "***(Example String)***"
                      "[]()/*."
                      #\\)
=> "\\*\\*\\*\\(Example String\\)\\*\\*\\*"

;; also can escape a singe char...
 (escape-special-chars "richardt@@vzavenue.net"
                      #\@@
                      #\@@)
=> "richardt@@@@vzavenue.net"
@end lisp

@end defun

@anchor{string transform transform-string}@defun transform-string str match? replace [start] [end]
Uses @var{match?} against each character in @var{str}, and performs a
replacement on each character for which matches are found.

@var{match?} may either be a function, a character, a string, or
@code{#t}.  If @var{match?} is a function, then it takes a single
character as input, and should return @samp{#t} for matches.
@var{match?} is a character, it is compared to each string character
using @code{char=?}.  If @var{match?} is a string, then any character in
that string will be considered a match.  @code{#t} will cause every
character to be a match.

If @var{replace} is a function, it is called with the matched character
as an argument, and the returned value is sent to the output string via
@samp{display}.  If @var{replace} is anything else, it is sent through
the output string via @samp{display}.

Note that te replacement for the matched characters does not need to be
a single character.  That is what differentiates this function from
@samp{string-map}, and what makes it useful for applications such as
converting @samp{#\&} to @samp{"&amp;"} in web page text.  Some other
functions in this module are just wrappers around common uses of
@samp{transform-string}.  Transformations not possible with this
function should probably be done with regular expressions.

If @var{start} and @var{end} are given, they control which portion of
the string undergoes transformation.  The entire input string is still
output, though.  So, if @var{start} is @samp{5}, then the first five
characters of @var{str} will still appear in the returned string.

@lisp
; these two are equivalent...
 (transform-string str #\space #\-) ; change all spaces to -'s
 (transform-string str (lambda (c) (char=? #\space c)) #\-)
@end lisp

@end defun

@anchor{string transform expand-tabs}@defun expand-tabs str [tab-size]
Returns a copy of @var{str} with all tabs expanded to spaces.
@var{tab-size} defaults to 8.

Assuming tab size of 8, this is equivalent to:

@lisp
 (transform-string str #\tab "        ")
@end lisp

@end defun

@anchor{string transform center-string}@defun center-string str [width] [chr] [rchr]
Returns a copy of @var{str} centered in a field of @var{width}
characters.  Any needed padding is done by character @var{chr}, which
defaults to @samp{#\space}.  If @var{rchr} is provided, then the padding
to the right will use it instead.  See the examples below.  left and
@var{rchr} on the right.  The default @var{width} is 80.  The default
@var{lchr} and @var{rchr} is @samp{#\space}.  The string is never
truncated.

@lisp
 (center-string "Richard Todd" 24)
=> "      Richard Todd      "

 (center-string " Richard Todd " 24 #\=)
=> "===== Richard Todd ====="

 (center-string " Richard Todd " 24 #\< #\>)
=> "<<<<< Richard Todd >>>>>"
@end lisp

@end defun

@anchor{string transform left-justify-string}@defun left-justify-string str [width] [chr]
@code{left-justify-string str [width chr]}.  Returns a copy of @var{str}
padded with @var{chr} such that it is left justified in a field of
@var{width} characters.  The default @var{width} is 80.  Unlike
@samp{string-pad} from srfi-13, the string is never truncated.

@end defun

@anchor{string transform right-justify-string}@defun right-justify-string str [width] [chr]
Returns a copy of @var{str} padded with @var{chr} such that it is right
justified in a field of @var{width} characters.  The default @var{width}
is 80.  The default @var{chr} is @samp{#\space}.  Unlike
@samp{string-pad} from srfi-13, the string is never truncated.

@end defun

@anchor{string transform collapse-repeated-chars}@defun collapse-repeated-chars str [chr] [num]
Returns a copy of @var{str} with all repeated instances of @var{chr}
collapsed down to at most @var{num} instances.  The default value for
@var{chr} is @samp{#\space}, and the default value for @var{num} is 1.

@lisp
 (collapse-repeated-chars "H  e  l  l  o")
=> "H e l l o"
 (collapse-repeated-chars "H--e--l--l--o" #\-)
=> "H-e-l-l-o"
 (collapse-repeated-chars "H-e--l---l----o" #\- 2)
=> "H-e--l--l--o"
@end lisp

@end defun

@node string wrap
@chapter (string wrap)
@section Overview
Module @samp{(string wrap)} provides functions for formatting text
strings such that they fill a given width field.  A class,
@code{<text-wrapper>}, does the work, but two convenience methods create
instances of it for one-shot use, and in the process make for a more
``schemey'' interface.  If many strings will be formatted with the same
parameters, it might be better performance-wise to create and use a
single @code{<text-wrapper>}.

@section Usage
@anchor{string wrap <text-wrapper>}@deftp Class <text-wrapper>
This class encapsulates the parameters needing to be fed to the text
wrapping algorithm.  The following are the recognized keywords on the
call to @code{make}:

@table @code
@item #:line-width
This is the target length used when deciding where to wrap lines.
Default is 80.

@item #:expand-tabs?
Boolean describing whether tabs in the input should be expanded.  Default
is #t.

@item #:tab-width
If tabs are expanded, this will be the number of spaces to which they
expand.  Default is 8.

@item #:collapse-whitespace?
Boolean describing whether the whitespace inside the existing text
should be removed or not.  Default is #t.

If text is already well-formatted, and is just being wrapped to fit in a
different width, then setting this to @samp{#f}.  This way, many common
text conventions (such as two spaces between sentences) can be preserved
if in the original text.  If the input text spacing cannot be trusted,
then leave this setting at the default, and all repeated whitespace will
be collapsed down to a single space.

@item #:initial-indent
Defines a string that will be put in front of the first line of wrapped
text.  Default is the empty string, ``''.

@item #:subsequent-indent
Defines a string that will be put in front of all lines of wrapped text,
except the first one.  Default is the empty string, ``''.

@item #:break-long-words?
If a single word is too big to fit on a line, this setting tells the
wrapper what to do.  Defaults to #t, which will break up long words.
When set to #f, the line will be allowed, even though it is longer than
the defined @code{#:line-width}.

@end table

Here's an example of creating a @code{<text-wrapper>}:

@lisp
 (make <text-wrapper> #:line-width 48 #:break-long-words? #f)
@end lisp

@end deftp

@anchor{string wrap fill-string}@deffn Generic fill-string
@code{fill-string str keywds ...}.  Wraps the text given in string
@var{str} according to the parameters provided in @var{keywds}, or the
default setting if they are not given.  Returns a single string with the
wrapped text.  Valid keyword arguments are discussed with the
@code{<text-wrapper>} class.

@code{fill-string tw str}.  fills @var{str} using the instance of
@code{<text-wrapper>} given as @var{tw}.

@end deffn

@deffn Method fill-string  (@var{tw} @code{<text-wrapper>}) (@var{str} @code{<top>})
@end deffn

@deffn Method fill-string  (@var{str} @code{<top>}) (@var{keywds} @code{<top>})...
@end deffn

@anchor{string wrap string->wrapped-lines}@deffn Generic string->wrapped-lines
@code{string->wrapped-lines str keywds ...}.  Wraps the text given in
string @var{str} according to the parameters provided in @var{keywds},
or the default setting if they are not given.  Returns a list of strings
representing the formatted lines.  Valid keyword arguments are discussed
with the @code{<text-wrapper>} class.

@code{string->wrapped-lines tw str}.  Wraps the text given in string
@var{str} according to the given @code{<text-wrapper>} @var{tw}.  Returns
a list of strings representing the formatted lines.  Valid keyword
arguments are discussed with the @code{<text-wrapper>} class.

@end deffn

@deffn Method string->wrapped-lines  (@var{tw} @code{<text-wrapper>}) (@var{str} @code{<top>})
@end deffn

@deffn Method string->wrapped-lines  (@var{str} @code{<top>}) (@var{keywds} @code{<top>})...
@end deffn

@node term ansi-color
@chapter (term ansi-color)
@section Overview
@anchor{cindex-terminals ANSI color codes for}@cindex terminals, ANSI color codes for
@anchor{cindex-ANSI color codes}@cindex ANSI color codes
@anchor{cindex-color codes ANSI}@cindex color codes, ANSI
The @samp{(term ansi-color)} module generates ANSI escape sequences for
colors.  Here is an example of the module's use:

@lisp
 method one: safer, since you know the colors
 will get reset
(display (colorize-string "Hello!\n" 'RED 'BOLD 'ON-BLUE))

 method two: insert the colors by hand
(for-each display
          (list (color 'RED 'BOLD 'ON-BLUE)
                "Hello!"
                 (color 'RESET)))
@end lisp

@section Usage
@anchor{term ansi-color color}@defun color . lst
Returns a string containing the ANSI escape sequence for producing the
requested set of attributes.

The allowed values for the attributes are listed below.  Unknown
attributes are ignored.

@table @asis
@item Reset Attributes
@samp{CLEAR} and @samp{RESET} are allowed and equivalent.

@item Non-Color Attributes
@samp{BOLD} makes text bold, and @samp{DARK} reverses this.
@samp{UNDERLINE} and @samp{UNDERSCORE} are equivalent.  @samp{BLINK}
makes the text blink.  @samp{REVERSE} invokes reverse video.
@samp{CONCEALED} hides output (as for getting passwords, etc.).

@item Foregrond Color Attributes
@samp{BLACK}, @samp{RED}, @samp{GREEN}, @samp{YELLOW}, @samp{BLUE},
@samp{MAGENTA}, @samp{CYAN}, @samp{WHITE}

@item Background Color Attributes
@samp{ON-BLACK}, @samp{ON-RED}, @samp{ON-GREEN}, @samp{ON-YELLOW},
@samp{ON-BLUE}, @samp{ON-MAGENTA}, @samp{ON-CYAN}, @samp{ON-WHITE}

@end table

@end defun

@anchor{term ansi-color colorize-string}@defun colorize-string str . color-list
Returns a copy of @var{str} colorized using ANSI escape sequences
according to the attributes specified in @var{color-list}.  At the end
of the returned string, the color attributes will be reset such that
subsequent output will not have any colors in effect.

The allowed values for the attributes are listed in the documentation
for the @code{color} function.

@end defun

@node unit-test
@chapter (unit-test)
@section Overview
@section Usage
@anchor{unit-test assert-equal}@defun assert-equal expected got
@end defun

@anchor{unit-test assert-true}@defun assert-true got
@end defun

@anchor{unit-test assert-false}@defun assert-false got
@end defun

@anchor{unit-test assert-numeric-=}@defun assert-numeric-= expected got precision
@end defun

@anchor{unit-test <test-result>}@deftp Class <test-result>
@end deftp

@anchor{unit-test tests-run}@deffn Generic tests-run
@end deffn

@deffn Method tests-run
@end deffn

@anchor{unit-test tests-failed}@deffn Generic tests-failed
@end deffn

@deffn Method tests-failed
@end deffn

@anchor{unit-test tests-log}@deffn Generic tests-log
@end deffn

@deffn Method tests-log
@end deffn

@anchor{unit-test failure-messages}@deffn Generic failure-messages
@end deffn

@deffn Method failure-messages
@end deffn

@anchor{unit-test test-started}@deffn Generic test-started
@end deffn

@deffn Method test-started  (@var{self} @code{<test-result>}) (@var{description} @code{<string>})
@end deffn

@anchor{unit-test test-failed}@deffn Generic test-failed
@end deffn

@deffn Method test-failed  (@var{self} @code{<test-result>}) (@var{description} @code{<string>})
@end deffn

@anchor{unit-test summary}@deffn Generic summary
@end deffn

@deffn Method summary  (@var{self} @code{<test-result>})
@end deffn

@anchor{unit-test <test-case>}@deftp Class <test-case>
@end deftp

@anchor{unit-test name}@deffn Generic name
@end deffn

@deffn Method name
@end deffn

@deffn Method name
@end deffn

@anchor{unit-test set-up-test}@deffn Generic set-up-test
@end deffn

@deffn Method set-up-test  (@var{self} @code{<test-case>})
@end deffn

@anchor{unit-test tear-down-test}@deffn Generic tear-down-test
@end deffn

@deffn Method tear-down-test  (@var{self} @code{<test-case>})
@end deffn

@anchor{unit-test run}@deffn Generic run
@end deffn

@deffn Method run  (@var{self} @code{<test-suite>}) (@var{result} @code{<test-result>})
@end deffn

@deffn Method run  (@var{self} @code{<test-case>}) (@var{result} @code{<test-result>})
@end deffn

@anchor{unit-test <test-suite>}@deftp Class <test-suite>
@end deftp

@anchor{unit-test tests}@deffn Generic tests
@end deffn

@deffn Method tests
@end deffn

@anchor{unit-test add}@deffn Generic add
@end deffn

@deffn Method add  (@var{self} @code{<test-suite>}) (@var{suite} @code{<test-suite>})
@end deffn

@deffn Method add  (@var{self} @code{<test-suite>}) (@var{test} @code{<test-case>})
@end deffn

@anchor{unit-test run-all-defined-test-cases}@defun run-all-defined-test-cases
@end defun

@anchor{unit-test exit-with-summary}@defun exit-with-summary result
@end defun

@anchor{unit-test assert}@defspec assert
@end defspec

@anchor{unit-test assert-exception}@defspec assert-exception
@end defspec

@node Copying This Manual
@appendix Copying This Manual
This manual is covered under the GNU Free Documentation License. A copy of the FDL is provided here.@menu
* GNU Free Documentation License::  License for copying this manual
@end menu

@include fdl.texi
@node Concept Index
@unnumbered Concept Index
@printindex cp
@node Function Index
@unnumbered Function Index
@printindex fn
@bye