The phoe-toolbox Reference Manual

This is the phoe-toolbox Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 07:17:03 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 phoe-toolbox

A personal utility library

Author

Michał "phoe" Herda <>

License

BSD 2-clause

Dependencies
  • alexandria (system).
  • trivial-indent (system).
  • closer-mop (system).
Source

phoe-toolbox.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 phoe-toolbox/phoe-toolbox.asd

Source

phoe-toolbox.asd.

Parent Component

phoe-toolbox (system).

ASDF Systems

phoe-toolbox.


3.1.2 phoe-toolbox/package.lisp

Source

phoe-toolbox.asd.

Parent Component

phoe-toolbox (system).

Packages

phoe-toolbox.


3.1.3 phoe-toolbox/phoe-toolbox.lisp

Dependency

package.lisp (file).

Source

phoe-toolbox.asd.

Parent Component

phoe-toolbox (system).

Packages

phoe-toolbox/list-of.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 phoe-toolbox

Source

package.lisp.

Use List
  • alexandria.
  • common-lisp.
Public Interface
Internals

4.2 phoe-toolbox/list-of

Source

phoe-toolbox.lisp.


5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Constants

Constant: +universal-unix-time-difference+

The difference between universal time and Unix time in seconds.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.


5.1.2 Special variables

Special Variable: *whitespace*

Standard whitespace characters.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.


5.1.3 Macros

Macro: check-slot-boundp (object slot-name)

Asserts that the provided slot is bound.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: define-constructor ((class . keys) &body body)

Defines an INITIALIZE-INSTANCE :AFTER method on the given object.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: define-print ((object stream &key type identity) &body body)

Defines a PRINT-OBJECT method on the given object with inserting BODY inside PRINT-UNREADABLE-OBJECT.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: define-readable-print ((object stream &key type identity) &body body)

Defines a PRINT-OBJECT method on the given object, which depends on the value of *PRINT-READABLY*. If it is true, then the object is printed using PRINT-INSTANCE-READABLY; else, it is printed with inserting BODY inside PRINT-UNREADABLE-OBJECT.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: fbind (bindings &body body)

Binds the function objects in the function namespace.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: finalized-let* ((&rest bindings) &body body)

Like LET*, except each variable binding is of form (var initform . forms) where FORMS will be evaluated when leaving the LET* by means of UNWIND-PROTECT. These forms will be evaluated from last binding to first. Each binding has its own individual UNWIND-PROTECT cleanup.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: handler-case* (form &rest cases)

A variant of HANDLER-CASE, in which the case forms are evaluating before performing a transfer of control. This ensures that the case forms are evaluated in the dynamic scope of the signaling form.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: mod-decf (place divisor &optional delta-form)

Like DECF, except the final value set in PLACE is always a modulus modulo DIVISOR.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: mod-incf (place divisor &optional delta-form)

Like INCF, except the final value set in PLACE is always a modulus modulo DIVISOR.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: notf (place)

Sets the value of PLACE to its logical negation and returns the new value.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: signals* (condition-type n form)

Testing macro analogous to 1AM:SIGNALS, except it does not perform a non-local transfer of control and therefore is not suitable for any code that makes calls to INVOKE-DEBUGGER. Instead, it allows the caller to assert that a condition of type CONDITION-TYPE was signaled exactly N times.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: wait ((&optional timeout step) &body body)

Evaluates BODY each STEP seconds until it evaluates to true, at which point it returns the value of BODY, or until TIMEOUT seconds pass, at which point it returns NIL.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: wait-until (form &optional step)

Evaluates BODY each STEP seconds until it evaluates to true, at which point it returns the value of BODY.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: with-input-from-binary ((stream filespec) &body body)

Like WITH-OPEN-FILE, except with defaults suitable for reading from binary.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: with-output-to-binary ((stream filespec &key if-does-not-exist) &body body)

Like WITH-OPEN-FILE, except with defaults suitable for wriiting to binary.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Macro: with-temp-package (&body body)

Evaluates BODY with *PACKAGE* bound to a freshly created temporary package that will be deleted once control leaves the BODY, uninterning all symbols that were interned into it during that time.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.


5.1.4 Ordinary functions

Function: alternatingly (value-when-true &optional value-when-false initially-true-p)

Returns a function that acts like CL:CONSTANTLY, but its return value alternates between VALUE-WHEN-TRUE and VALUE-WHEN-FALSE (default NIL). INITIALLY-TRUE-P specifies whether VALUE-WHEN-TRUE is returned as the first value from the returned function.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: assoc-value-or-die (alist key &key test)

Like ALEXANDRIA:ASSOC-VALUE, except it signals an error if the value is not found.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: bound-slot-names (instance)

Given a generalized instance of STANDARD-OBJECT, returns a list of all slot names which are bound in that instance.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: call-with-handler (thunk condition-type handler-function)

The functional variant of HANDLER-BIND.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: call-with-restart (thunk restart-name restart-function &key interactive-function report-function test-function)

The functional variant of RESTART-BIND.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: cat (&rest strings)

Concatenates targets into a string.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: catn (&rest strings)

Concatenates targets into a string, inserting a newline between each of them.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: circular-graph-p (edges)

Accepts a list of directed edges (two-element lists of EQL-comparable nodes). If the graph does not contain a cycle, returns (VALUES NIL NIL). If the graph contains a cycle, returns (VALUES T VERTEX), where VERTEX is one of the vertices in the cycle.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: constantly* (&rest args)

Like CONSTANTLY, except the returned closure may return multiple values, denoted by ARGS.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: count-digits (integer)

Returns the number of digits in an integer, sans any sign.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: downcase-lisp-file (pathname)

Downcases a Common Lisp source file.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: dsubseq (sequence start &optional end)

Like SUBSEQ, except the created array is an array displaced to SEQUENCE ~ and therefore shares structure with it.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: fformat (stream format-string &rest format-args)

Acts like FORMAT, except it calls FORCE-OUTPUT on STREAM afterwards.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: get-unix-time ()

Returns the current Unix timestamp.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: gethash-or-die (key hash-table &optional default)

Like GETHASH, except it signals an error if the value is not found.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: graph-roots (edges)

Accepts a list of directed edges (two-element lists of EQL-comparable nodes). Returns a list of root vertices (vertices that are not pointed at).

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: hexadecimal-string-p (string)

Returns true if the string contains only digits 0-9 and lowercase/uppercase characters #A-#F, false otherwise.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: identity* (&rest args)

Like CONSTANTLY, except the list of ARGS is returned instead.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: make-dumped-stream (input-output-stream &key dump-input-stream dump-output-stream)

Returns a wrapper stream around the original stream. All data read from the wrapper stream is additionally sent to DUMP-INPUT-STREAM. All data written to the wrapper stream is additionally sent to the DUMP-OUTPUT-STREAM.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: multiple-value-mapcar (function &rest lists)

Returns multiple lists of all multiple values returned by repeatedly applying FUNCTION to consecutive arguments from LISTS.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: nth-funcall (function count argument)

Funcall FUNCTION composed COUNT times with itself on ARGUMENT.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: peek-char-no-hang (&optional input-stream eof-error-p eof-value recursive-p)

Like PEEK-CHAR, except it immediately returns NIL if no character is available for reading on the input stream.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: print-hash-table-readably (hash-table &optional stream)

Prints a hash table readably.

Deprecated: please use (PRINT-INSTANCE-READABLY HASH-TABLE &OPTIONAL STREAM) instead.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: rassoc-value-or-die (alist key &key test)

Like ALEXANDRIA:RASSOC-VALUE, except it signals an error if the value is not found.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: read-data-file (system pathname)

Reads the data file from the provided pathname. The pathname should be a system relative pathname.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: replace-all (string part replacement &key test)

Returns a new string in which all the occurences of the part is replaced with replacement.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: robust-subseq (sequence start &optional end)

Like SUBSEQ, but handles out-of-range bounding index designators gracefully.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: shallow-copy-object (original &rest initargs)

Creates a shallow copy of a standard object, copying the values of all slots, before calling REINITIALIZE-INSTANCE on it with the provided keyword-value pairs.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: sleepcar (function list &optional n sleep-interval)

Collects the element of funcalling FUNCTION on successive elements of LIST, sleeping for SLEEP-INTERVAL seconds every N elements.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: split (predicate list)

Separates the list into a sublist of elements for which the predicate returns true and a sublist of elements for which the predicate returns false. Returns them as two values.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: string=-getf (plist indicator)

Like GETF, except it tests with STRING= and is there suitable for use with strings and symbols.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: trim-whitespace (string)

Trims whitespace characters from both sides of a string.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: unintern-all-symbols (tree)

Returns a copy of the provided tree, in which all symbols have been uninterned. The tree must not contain improper lists.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: unix-time-to-datestring (unix-time)

Decodes the unix time and returns its textual form in format "YYYY-MM-DD HH:MM:SS".

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: upcase-lisp-file (pathname)

Upcases a Common Lisp source file.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: url-filename (url)

Given a URL, returns everything after its last slash.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: urls-pathnames (urls directory)

Provided a list of URLs and a valid directory pathname, returns a list of pathnames that end with the filenames suitable for downloaded files.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: vector-times (vector n)

Returns a fresh vector which is VECTOR concatenated to itself N times.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: whitespacep (char)

Returns true if the provided character is whitespace.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: zip (&rest lists)

Collects a list of lists, where the first list contains the first element of the argument lists, the second list - second, etc.. The lists are as long as the shortest list.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.


5.1.5 Generic functions

Generic Function: print-instance-readably (object &optional stream)

Prints an instance readably, using the #. notation.

The standard method is a hack. Its functioning depends on all direct slots of a class being of form %FOO or FOO and having an initarg keyword called :FOO. All values stored in these slots need to be printable readably. Moreover, indirect slots are not restored. Before you use it, make sure you know what you are doing.

The hash-table method uses ALEXANDRIA:ALIST-HASH-TABLE.

Programmers may define methods on this generic function in case the standard method is not enough to print the object they have.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Methods
Method: print-instance-readably (object &optional stream)
Method: print-instance-readably ((hash-table hash-table) &optional stream)

5.1.6 Types

Type: list-of (type)

A type specifier that matches a list whose all elements are of the given type.

Package

phoe-toolbox.

Source

phoe-toolbox.lisp.


5.2 Internals


5.2.1 Special variables

Special Variable: *call-with-handler-cache*
Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Special Variable: *call-with-restart-cache*
Package

phoe-toolbox.

Source

phoe-toolbox.lisp.


5.2.2 Ordinary functions

Function: case-lisp-file (pathname case-function)
Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: ensure-call-with-handler-function (condition-type)
Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: ensure-call-with-restart-function (restart-name interactive-p report-p test-p)
Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: make-handler-case*-with-no-error-case (form cases)
Package

phoe-toolbox.

Source

phoe-toolbox.lisp.

Function: make-handler-case*-without-no-error-case (form cases)
Package

phoe-toolbox.

Source

phoe-toolbox.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   B   C   D   E   F   G   H   I   M   N   P   R   S   T   U   V   W   Z  
Index Entry  Section

A
alternatingly: Public ordinary functions
assoc-value-or-die: Public ordinary functions

B
bound-slot-names: Public ordinary functions

C
call-with-handler: Public ordinary functions
call-with-restart: Public ordinary functions
case-lisp-file: Private ordinary functions
cat: Public ordinary functions
catn: Public ordinary functions
check-slot-boundp: Public macros
circular-graph-p: Public ordinary functions
constantly*: Public ordinary functions
count-digits: Public ordinary functions

D
define-constructor: Public macros
define-print: Public macros
define-readable-print: Public macros
downcase-lisp-file: Public ordinary functions
dsubseq: Public ordinary functions

E
ensure-call-with-handler-function: Private ordinary functions
ensure-call-with-restart-function: Private ordinary functions

F
fbind: Public macros
fformat: Public ordinary functions
finalized-let*: Public macros
Function, alternatingly: Public ordinary functions
Function, assoc-value-or-die: Public ordinary functions
Function, bound-slot-names: Public ordinary functions
Function, call-with-handler: Public ordinary functions
Function, call-with-restart: Public ordinary functions
Function, case-lisp-file: Private ordinary functions
Function, cat: Public ordinary functions
Function, catn: Public ordinary functions
Function, circular-graph-p: Public ordinary functions
Function, constantly*: Public ordinary functions
Function, count-digits: Public ordinary functions
Function, downcase-lisp-file: Public ordinary functions
Function, dsubseq: Public ordinary functions
Function, ensure-call-with-handler-function: Private ordinary functions
Function, ensure-call-with-restart-function: Private ordinary functions
Function, fformat: Public ordinary functions
Function, get-unix-time: Public ordinary functions
Function, gethash-or-die: Public ordinary functions
Function, graph-roots: Public ordinary functions
Function, hexadecimal-string-p: Public ordinary functions
Function, identity*: Public ordinary functions
Function, make-dumped-stream: Public ordinary functions
Function, make-handler-case*-with-no-error-case: Private ordinary functions
Function, make-handler-case*-without-no-error-case: Private ordinary functions
Function, multiple-value-mapcar: Public ordinary functions
Function, nth-funcall: Public ordinary functions
Function, peek-char-no-hang: Public ordinary functions
Function, print-hash-table-readably: Public ordinary functions
Function, rassoc-value-or-die: Public ordinary functions
Function, read-data-file: Public ordinary functions
Function, replace-all: Public ordinary functions
Function, robust-subseq: Public ordinary functions
Function, shallow-copy-object: Public ordinary functions
Function, sleepcar: Public ordinary functions
Function, split: Public ordinary functions
Function, string=-getf: Public ordinary functions
Function, trim-whitespace: Public ordinary functions
Function, unintern-all-symbols: Public ordinary functions
Function, unix-time-to-datestring: Public ordinary functions
Function, upcase-lisp-file: Public ordinary functions
Function, url-filename: Public ordinary functions
Function, urls-pathnames: Public ordinary functions
Function, vector-times: Public ordinary functions
Function, whitespacep: Public ordinary functions
Function, zip: Public ordinary functions

G
Generic Function, print-instance-readably: Public generic functions
get-unix-time: Public ordinary functions
gethash-or-die: Public ordinary functions
graph-roots: Public ordinary functions

H
handler-case*: Public macros
hexadecimal-string-p: Public ordinary functions

I
identity*: Public ordinary functions

M
Macro, check-slot-boundp: Public macros
Macro, define-constructor: Public macros
Macro, define-print: Public macros
Macro, define-readable-print: Public macros
Macro, fbind: Public macros
Macro, finalized-let*: Public macros
Macro, handler-case*: Public macros
Macro, mod-decf: Public macros
Macro, mod-incf: Public macros
Macro, notf: Public macros
Macro, signals*: Public macros
Macro, wait: Public macros
Macro, wait-until: Public macros
Macro, with-input-from-binary: Public macros
Macro, with-output-to-binary: Public macros
Macro, with-temp-package: Public macros
make-dumped-stream: Public ordinary functions
make-handler-case*-with-no-error-case: Private ordinary functions
make-handler-case*-without-no-error-case: Private ordinary functions
Method, print-instance-readably: Public generic functions
Method, print-instance-readably: Public generic functions
mod-decf: Public macros
mod-incf: Public macros
multiple-value-mapcar: Public ordinary functions

N
notf: Public macros
nth-funcall: Public ordinary functions

P
peek-char-no-hang: Public ordinary functions
print-hash-table-readably: Public ordinary functions
print-instance-readably: Public generic functions
print-instance-readably: Public generic functions
print-instance-readably: Public generic functions

R
rassoc-value-or-die: Public ordinary functions
read-data-file: Public ordinary functions
replace-all: Public ordinary functions
robust-subseq: Public ordinary functions

S
shallow-copy-object: Public ordinary functions
signals*: Public macros
sleepcar: Public ordinary functions
split: Public ordinary functions
string=-getf: Public ordinary functions

T
trim-whitespace: Public ordinary functions

U
unintern-all-symbols: Public ordinary functions
unix-time-to-datestring: Public ordinary functions
upcase-lisp-file: Public ordinary functions
url-filename: Public ordinary functions
urls-pathnames: Public ordinary functions

V
vector-times: Public ordinary functions

W
wait: Public macros
wait-until: Public macros
whitespacep: Public ordinary functions
with-input-from-binary: Public macros
with-output-to-binary: Public macros
with-temp-package: Public macros

Z
zip: Public ordinary functions