Guide to TTN's Personal Scheme Library

Display an "ambiguous command" message a la gdb.

Display an "undefined command" message a la gdb.

See if NAME is visible as a child in TREE, as either an abbrev tree or an alias. If found, STURDY is called with the fullname of the child. If not found, SHAKY is called with NAME and TREE as args. If there is ambiguity, AMBIGUOUS is called with args NAME, TREE and a list of possible fullnames.

At this time, the optional arg SO-FAR is not used, but it will probably be tacked on as the optional arg for STURDY, SHAKY and AMBIGUOUS at some point (as a place for caller-defined data).

If module configuration variable `%careful%' is #t, children that are neither abbrev trees nor aliases throw a `bad-child' error. Otherwise, such children result in an immediate call to SHAKY as described above.

Add to TREE by splitting up FULLNAME-PATH into constituent words and creating children trees. FULLNAME-PATH is scrubbed before splitting. If FULLNAME-PATH already has been added, an error is signalled. [But what about `DATA' ?!?]

Translate IN-DATA, a nested list, into an abbrev tree and return it. For each list in IN-DATA, the car becomes a fullname and the CDR the children. Elements of the cdr can be lists, in which case `abtree-import' is called recursively. This procedure is experimental and may go away.

Recursively add alias children to TREE. Each alias's `ab' slot is either an abbrev tree when unambiguous, or a list of fullnames of possible abbrev trees, when ambiguous. Only TREE's children are consulted and referenced.

Insert into gb the tree (of strings), walked depth-first. If gb is #f, create a new gap-buffer. Return the gap-buffer.

Write buffer into file filename. This makes the buffer visit that file. filename cannot name a directory.

Write buffer into file filename, but only if doing so would create a new file or a file with different contents than the pre-existing one. filename cannot name a directory.

Save buffer to disk. buffer should be visiting a file. An error is thrown if buffer is not visiting a file. An error is thrown if the file cannot be written. Return #t if all goes well.

Call program synchronously in separate process with optional args. Return a numeric exit status. Keyword args (all default values are #f) are:

#:inb

Input buffer.

#:outb

Output buffer

#:errb

Error output buffer.

#:norm

Non-#f means that program and args should be passed through args->normalized-list (see shellutils).

Call program synchronously in separate process with optional args. Unless give #:outp 0, wait for program to terminate and return a numeric exit status.

#:inp (current-input-port)

Input port. #f means /dev/null.

#:outp (current-output-port)

Output port. #f means discard output; 0 (zero) means discard, don't wait for program to terminate, and return #f.

#:errp (current-error-port)

Error output port. #f means discard output.

#:norm

Non-#f means program and args should be passed through args->normalized-list (see shellutils).

Examine cadr of cmdline-list and invoke one of the handlers.

cmdline-list is a two-element list, of the form:

          (PROG-NAME COMMAND)

handlers is zero or more forms:

          ((KEY) (BODY1) (BODY2) ...)

body1, body2 and so on are optional. key is a symbol or string. The body forms for a key are executed if command matches key. If cmdline-list does not have exactly two elements, a usage message is displayed and a "bad usage" error is thrown. If command matches no key, cron silently returns #t, otherwise, the return value is the value of the last body form executed.

For example:

          #!/usr/local/bin/guile -s
          !#
          (use-modules ((ttn cron) #:select (cron)))
          (exit (cron (command-line)
                  ((hourly) (display "yawn, stretch") (newline))
                  ((daily)  (display "zonk") (newline))))

Call cron with (command-line) and handlers. Exit with the return value.

Run "cvs log" on file; return an alist describing the head revision. Keys include: rcs-file, working-file, head, locker, date, author and state. All values are strings.

Return a list of CVS files under dir, as listed by CVS/Entries.

Display alist value r returned by Scheme function cvslog. Optional args fields are symbols specifying which fields to display and in what order. If omitted, display, in this order: rcs-file, working-file, head, date, author, state.

For directory dir, summarize state info for files in CVS/Entries. Files are grouped by state and sorted w/ most-recently changed first.

Create a directory dir, as well as any missing parent dirs.

Return list of file names in directory dir.

Apply filter to each file name in dir; return list of non-#f values. filter is a procedure applied to each file name – it should return #f if that file name is to be omitted from the overall list, or a value to be collected. The file name list is not sorted.

In dir, apply filter to each file name; return list of non-#f values. filter is a procedure applied to to each filename – it should return #f if that file name is to be omitted from the overall list. Otherwise, its return value can be a string, or #t which is synonymous with the filename with the dir prefixed. The file name list is not sorted. options are zero or more keywords that modify the behavior:

#:filter-prefixed

Pass to filter each file with dir already prefixed.

#:collect-nodir

For the case when filter returns #t, collect the filename without the dir prefix.

NB: The argument order is opposite that of filtered-files.

Return #f if file is "." or "..", otherwise return file.

Return a procedure that filters based on ext, a string. The procedure takes a filename and if it ends in .EXT (note dot), returns the portion of the filename before the dot, otherwise #f. Optional arg transform controls precisely how the returned filename is to be processed. If transform is omitted or #f, the extension is discarded. If it is #t, the extension is left alone. If it is a string, the stem is concatenated with it. If it is a procedure, that procedure is applied to the stem, and it's return value, which need not be a string, is collected.

Take sep-char and return a procedure that, given filename, returns a copy of it w/o the ending sep-char.

Return #t if file file1 is newer than file file2. If file1 does not exist, the answer is #f; otherwise, if file2 does not exist, the answer is #t.

Evaluate body and restore the original cwd afterward.

Change directory to dir, evaluate body and restore cwd.

Email who w/ subject the log of failed shell-command. who and subject are strings or symbols. shell-command is one or more strings or symbols, to be passed through system*. If shell-command is successful, no email is sent. Log includes both stdout and stderr. Use "mail" for mailer. Return #t if shell-command is successful, otherwise #f.

Change the system mail program to program. Normally it is ‘mail’. program should behave similarly: it must support the command-line sequence -s subject recipient, and take the mail message body from stdin.

Convert filename name to absolute, and canonicalize it. Second arg default-directory is directory to start with if name is relative (does not start with slash); if default-directory is #f or missing, (getcwd) is used. File name components that are . are removed, and so are file name components followed by .., along with the .. itself; note that these simplifications are done without checking the resulting file names in the file system. An initial ~/ expands to your home directory. An initial ~USER/ expands to USER's home directory.

Reset the cache expand-file-name uses for the results of expanding ~ and ~USER. Optional arg size specifies the hash table bucket count to use (default is 7).

Substitute environment variables referred to in string. $FOO where FOO is an environment variable name means to substitute the value of that variable. The variable name should be terminated with a character not a letter, digit or underscore; otherwise, enclose the entire variable name in braces. For instance, in ab$cd-x, $cd is treated as an environment variable.

Use $$ to insert a single dollar sign.

Substitute env vars in string then expand it as a filename. See substitute-env-vars and expand-file-name.

Return the filesystem tree rooted at filename as a nested list of node values as obtained by calling node-proc, a procedure that takes five arguments, on each directory and subdirecory. The arguments to node-proc are explained fully in the nftw documentation.

          (node-proc name statinfo flag base level) => node value

If filename is names a file (not a directory), simply return the node value resulting from one call to node-proc. Otherwise, for each list in the return value, the car is the node value of the directory and the cdr the node values of the children.

The remaining control-flags are passed through to nftw. You need not specify the flag depth; it is automatically included.

If name begins with "/", return it. Otherwise, return a new string composed by taking name in vicinity of dir.

Return name, a string, stripping the terminating "/" character. If there is no "/", just return name.

Return a list of filename components parsed from string. Components are delimited by "/", which is discarded. Null string components are also discarded.

Return a string composed by prefixing each element of ls with "/".

Walk tree depth-first, displaying elements if they are strings. Signal "bad type" error for non-string, non-list elements. Optional second arg out is a procedure to use instead of display.

Flatten to port (using flatten) the tree, a nested list of strings. If port is #f return a string, instead.

Quietly read a line from current input port, first displaying prompt. Typed characters are not echoed to the screen. Throw bad-environment error if running under Emacs.

Invoke gpg --clearsign on msg (a string or port), and return the output. Throw bad-environment error if running under Emacs.

Invoke gpg --verify on msg (a string or port), and return a siginfo value. The elements of this value (all strings) can be extracted using one of the "siginfo:foo" procedures. If the gpg call fails, throw a signature-verification-error with argument the gpg verifier. This verifier is created using make-buffered-caller, q.v.

Return the signer (typically includes name and email address) of si.

Return the message-signing time of si.

Return the signing method (may include key ID) of si.

Return the signature (hex digits and sometimes "=") of si.

Return the body of the message, w/o gnupg message envelope, of si.

Return list of matches to regexp re from strings list. Optional flags are keywords (or symbols with the same name) which modify regexp matching:

#:invert

the result list is those strings that do NOT match

#:fold-case

consider upper and lower case to be identical

#:count

return length of result list instead of list

#:literal

re specifies a literal string to match

Return list order is the same as in the input list.

Return non-#f match results of regexp-exec of regexp re on strings list. Optional flags are keywords (or symbols with the same name) which modify regexp matching:

#:invert

the result list is composed entirely of #t values, with length equal to the number of strings that do NOT match (useful with count flag below)

#:fold-case

consider upper and lower case to be identical

#:count

return length of result list instead of list

#:literal

re specifies a literal string to match

Return list order is the same as in the input list.

Search for regular expression re in files. Return a list of those that match. re specifies a regular expression that matches on one line (multi-line results not currently supported). files is a list, each element of which can either be a filename or a seekable port. In the returned list, if the element is a port, its read offset is left at the beginning of the line of the first match.

Return the tree:

          ("<?xml version=\"1.0\" encoding=\""
           encoding
           "\"?>" :LF)

Return the tree:

          ("<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 "
           type-as-capitalized-string
           "//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-"
           type-as-string
           ".dtd\">" :LF)

type is one of #:strict, #:transitional, #:frameset; or a symbol with the same name.

Concatentate source, a shell command that writes image data to stdout, with a series of shell commands from the Netpbm package. Optional arg invert? non-#f means to include a call to pnminvert in the pipeline.

Execute the pipeline in a subshell and return its output as a string.

Profile string for small non-whitespace intervals to be “marked up” as the text of an HTML A element, with reference taken randomly from list-of-links (list of strings). As as special case, if the car of list-of-links is the symbol file-lines, then the cadr is taken to be a filename which must contain one link (URL) per line.

Return an html-data tree (nested list of strings). Optional third arg link-tree specifies a procedure to use instead of href (see html-data) to construct hyperlink references. It should take arguments url and text (both strings), and return a tree (nested list of strings).

Return an html-data tree made from an ASCII-representation of a globe image. When optional arg links is specified, the single string is profiled for small non-whitespace intervals to be “marked up” as the text of an HTML A element, with the reference taken randomly from links.

links may be the name of a file containing one URL per line. links may also be a list or vector of URLs.

Keyword parameters, default values, and their meanings:

#:size	150	Size in pixels (NxN) of the originating image.
#:gen	#:ppmforge	Preferred backend program used to generate the image, one of #:xearth, #:xplanet or #:ppmforge. The value can also be a symbol.
#:link-tree	href	Another procedure to use instead of href (see html-data). It should take arguments url and text (both strings), and return a tree (nested list of strings).

Return a thunk that listens with ear, a list in of the form (FAMILY ADDRESS [ARGS]). As a special case, if ear is an integer, it is taken to specify a TCP/IP port p and converted internally to family PF_INET, address INADDR_ANY, and args p. options are alternating keyword ands values:

#:setup-sock

A procedure taking one arg, the listener socket, called right before doing bind. This is a good place for setsockopt calls.

#:nqueue

Number of queued requests, default 10.

#:pre

#:handle

#:post

Procedures that take two args, port and conn, the output of accept. These three procedures are thunkified to form the branches of a dynamic-wind, the child. After calling the post procedure, port is closed. If pre, handle, and post are unspecified, the default action is to do nothing.

#:concurrency

The value may be #:coop-thread, in which case each child is run in its own thread. If it is #f or unspecified, child dispatch is serial.

#:catch-tag

A symbol that will catch any calls to throw that uses it. Normally, the server loop uses #t to catch all throws. This tag (and indeed any args in the throw) are ignored.

Return a procedure capable of calling program w/ optional args. When called, the program stdout and stderr are captured to buffers. The key #:inb (default #f) specifies an input buffer to use for the call.

The returned procedure takes one of the following commands (either a keyword or similarly-named symbol):

#:redefine NEW-DEF

Redefine the called program and its args. new-def is one or more strings.

#:execute

Call program, clearing buffers first. Return raw exit status of the program. See status:exit-val for more info.

#:execute/no-init

Same as #:execute, but do not clear buffers first.

#:outbuf

Return output buffer object.

#:outbuf-string

Return output buffer as a string.

#:outbuf-lines

Return output buffer as a list of strings.

#:errbuf

Return error output buffer.

#:errbuf-string

Return error output buffer as a string.

#:errbuf-lines

Return error output buffer as a list of strings.

#:exit-val

Return exit status from the last execution. Signal an error if #:execute (or #:execute/no-init) command has not yet been issued since closure creation or most recent #:redefine.

The #:outbuf-lines and #:errbuf-lines commands use newline to separate.

The double-quote character #\", as a string.

The newline character #\newline, as a string.

The null string, "".

Return keyword-or-symbol as a symbol.

Return keyword-or-symbol as a string.

Scan list of the form:

          ([attr-name attr-value ...] [body...])

Each attr-name is either a keyword or a symbol. Each attr-value is either a string, a (possibly) nested list of strings, a symbol or a number. When there are no more attribute names, the rest of the list (which may be null) is taken as the body.

Return a pair whose car is the attributes, formatted (in a tree) as NAME="VALUE"; and whose cdr is the body.

Return a proc p that expands into a tree based on elem. Precisely, p partitions its arglist with peel into attributes and body and returns the tree:

          ("<" elem attributes [" /"] ">"
           [neck]
           [body ["</" elem ">"]]
           [tail])

Other args are keywords. Here is a list (with default value):

#:xbsc #f

Non-#f means “XMLish (blech) start close”, i.e., the start tag should be rendered as ‘<ELEM />’ instead of of ‘<ELEM>’ (with space and slash before closing angle bracket). Typically, this is specified in conjunction with #:end-tag :NULL.

#:neck :NULL

This is inserted between the initial tag and is not subjected to prep-body. Typically :LF when specified.

#:prep-body #f

This can be a procedure that is passed body and returns a transformed tree. It can also be a a pair whose car is the symbol map and whose cdr is a procedure taking one arg. The effective body is computed by mapping this procedure over all the top-level elements of body.

#:no-end-tag-if-null-body? #f

Non-#f specifies that if body is the empty list, the ‘</ELEM>’ end tag should be omitted entirely.

#:end-tag #f

Specifies an alternative end tag.

#:tail :NULL

A value to be appended at the very end of the tree. Typically :LF when specified.

If arg is already a list, return it. Otherwise return (list arg).

Return a tree made from expanding CSS rule, a list of the form:

          (target [property value...])

In this form, target can be a string or a flat list of strings; property can be a string, symbol, or keyword, and value can be a string or a nested list of strings.

Return a mixp parser with initial user data init and handlers. handlers is a 14-element vector, which is used by the procs expat:set-FOO-handler, where FOO and the handler elements are as follows:

          element                 0 1
          character-data          2
          processing-instruction  3
          comment                 4
          cdata-section           5 6
          default                 7
          unparsed-entity-decl    8
          namespace-decl          9 10
          not-standalone          11
          external-entity-ref     12
          unknown-encoding        13 #f

Note that for expat:set-unknown-encoding-handler, the second arg is hardcoded to #f.

Call mixp:parse on parser and afterwards, return its user data. Optional arg port specifies an input port, otherwise the current input port is used.

Remove keywords and their values from list ls. Return a new list. For example:

          (remove-keys '(ok1 #:a 42 #:b 99 ok2 #:c #:d ok3))
          ⇒ (ok1 ok2 ok3)

Parse mailmsg, return a query proc. mailmsg may be a list of lines (w/o terminating newline), a gap-buffer, or something that make-gap-buffer takes. The query proc takes a symbol comp, and returns the associated message component. Supported values for comp are:

from

first whitespace-delimited token after "^From " on first line

headers

the headers as an alist (keys are strings), order maintained

body

rest of the mail message

Any other query results in a "bad component" error.

Run rlog(1) on file; return an alist describing the head revision. Keys include: rcs-file, working-file, head, locker, date, author and state. All values are strings.

Return a list of RCS/*,v files under dir.

Display alist value r returned by Scheme function rlog. Optional args fields are symbols specifying which fields to display and in what order. If omitted, display, in this order: rcs-file, working-file, head, date, author, state.

For directory dir, summarize state info for files in subdir RCS. Files are grouped by state and sorted w/ most-recently changed first.

Read a text-db-table from filename/port, return a list of records. Each record is an alist whose keys are the field names, in order. filename/port can be a filename (string), or an input port. In the latter case, it is left open when done.

As a side effect, the property text-db-table-meta (procedure with setter) for the returned list is set to the table's metadata, if any.

flags is a list of zero or more keywords that change the default behavior. These are the recognized flags:

#:list

Return each record as a list instead of as an alist.

#:closure

Return each record as a closure (procedure) that accepts one arg sel. If #:list is specified, sel is a 0-based integer to index into the record's data. Otherwise, sel names a field in the record's data.

Group logs, a list of alists, by key in each alist. Return a list with elements of the form (KEY L1 L2...), where key is a symbol and l1... are elements of logs.

Optional args keep specify keys of those elements in l1... to collect. If unspecified, return the entire alist.

Return the internal graph representation object created from reading VCG file filename.

Write vcg, an internal graph representation, to file filename. If filename is #t, write to stdout.

Prepend dir to %load-path if it is not already present.

Prepend to var documentation-files filename of ttn docs. The filename is computed using %search-load-path. Do not modify var if ttn/ttn-pers-scheme.gdf1 is not found.

Set up interactive session environment according to ttn preferences. Specifically, set debug depth, turn on backtrace (on error :-), make the repl verbose, remove "." from %load-path, arrange for package docs to be findable, and extend the read-hash table so that #^Ffoo (where ^F is #\ack or "\C-f" in Emacs nomenclature) reads as a filename (string) formed as a result of passing it through expand-file-name-substituting-env-vars.

Pretty-print x, using escape sequences in strings.

Pretty-print the source of proc. This uses pp.

Return a new scat of LEN bits, w/ DEFAULT-VALUE, a number. If DEFAULT-VALUE is omitted, it is taken as 0. If DEFAULT-VALUE takes more bits than LEN, it is silently truncated.

Return `len' field of SCAT.

Return `default-value' field of SCAT.

Return new scat made from SCAT1 and SCAT2. In the result, SCAT1 is shifted left and SCAT2 maintains low-order bits.

Return a new SL structure made from FIELD-DEFS, a list of elements of the form (NAME LENGTH VALUE) or (NAME HEX-STRING). In the latter case, LENGTH and VALUE are computed from HEX-STRING. NAME may be #f, in which means no name. FIELD-DEFS order is maintained in the returned SL.

Return a copy of SL.

Destructively modify SL using FIELD-EDITS, a list. Each element of FIELD-EDITS has the form: (NAME VALUE).

Copy SL and apply FIELD-EDITS to the new structure. Return the new. This is a non-destructive variant of `sl-edit!'.

Return list of byte values for SL, in network-byte order. Optional arg BYTE-SIZE indicates how many bits are to be included in a byte, default if omitted is 8. Signal error if SL aggregate bit length is not an integral multiple of the byte size.

List of property specifications. This is called the FF[4] property index by the GNU Go sources. Each entry has the form: (NICK DESC CONTEXT VALUE-SPECS).

nick

One- or two-character symbol. (Note, however, that in the tree returned by read-sgf-file, nick is represented by a keyword.) Some examples: B, W, FF.

desc

A short string describing the property. Examples: "Black", "White", "Fileformat".

context

A symbol indicating where this property is likely to be found. [Perhaps the actual specification is more restrictive; the current parser ignores this information completely.] Examples: move, setup, root, -.

value-specs

One or more expressions that comprise a mini-language for describing the possible values for this property.

none

Symbol. The property has no value.

double

real

number

Symbols. The value is a number. The first two indicate that the number may be a real number (with component to the right of the radix point).

#(number (LOW . HIGH) ...)

Vector with symbol number at index zero, followed by one or more pairs of integers. The value is a number but constrained to the inclusive range(s) described by low and high. For example, #(number (3 . 5) (8 . 10)) means that the value must be 3, 4, 5, 8, 9, or 10.

text

simpletext

Symbols. The value is a string. Actually, these probably should be differentiated somehow; when we regain internet connection access to the actual spec will clarify things a bit...

color

Symbol. The value is either black or white.

point

move

Symbols. The value is a two-character codification of a vertice on the board, starting from aa. Apparently the value tt means "PASS".

(TYPE-1 . TYPE-2)

Pair of symbols. The value is a composed type, rendered as the first followed by a colon character (:) followed by the second.

(or number (number . number))

List of three elements, exactly as shown. The value can be a single number or a composed type of two numbers.

(or none TYPE)

List of three elements, the first two symbols or and none. The property may take no value, or one of type type (which may be simple or composed).

list TYPE

elist TYPE

Sequence (not a list) of symbol followed by further specification. The property can have multiple values, one after another. The difference between list and elist is not clear at the moment.

Vector of elements specifying how the SGF format has changed. Each element is one of these values:

nil

no such format version (ERROR!)

integer (same as index)

no info for this format version

pair

car and cdr are, respectively, lists of changed and added property nicks

The expression (1- (vector-length *format-changes*)) evaluates to a number specifying the currently supported file format version.

Return the collection of game trees parsed from reading filename.

Write the collection of game trees to filename.

Return a list of children game trees for tree, or #f if tree has no children.

Return a list of nodes (minimum is one) for tree.

In node, return a list of all values for property prop. The list may be empty or it may contain several values.

In node, return the value associated with the first occurance of prop.

Display to the current output port a simple analysis of tree. (This is more for debugging support than anything serious.) Optional arg prefix specifies the number of spaces to insert at the beginning of the line, for recursive analysis of children trees.

Echo args to make a string and pass it to system.

Apply simple-format to args and pass to system. The car of args is the format string.

For args, trim surrounding whitespace, join together separated by space, then split apart on space boundaries. For example:

          (args->normalized-list "rsync a b c"
                                 " d "
                                 "e"
                                 "f g h")
          ⇒ ("rsync" "a" "b" "c" "d" "e" "f" "g" "h")

Return a procedure that concatenates its args to produce an object of type return-type, one of string or #:string or symbol or #:symbol.