This is the gadgets Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Jun 15 05:35:29 2025 GMT+0.
The main system appears first, followed by any subsystem dependency.
gadgetsBen McGunigle’s utility collection
Ben McGunigle <bnmcgn@gmail.com>
Apache License, version 2.0
alexandria (system).
uiop (system).
cl-hash-util (system).
cl-utilities (system).
split-sequence (system).
package.lisp (file).
early.lisp (file).
gadgets.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
gadgets/early.lisppackage.lisp (file).
gadgets (system).
eval-always (macro).
gadgets/gadgets.lispearly.lisp (file).
gadgets (system).
*whitespace-characters* (special variable).
alist-p (function).
as-in-range (function).
assoc-all (function).
assoc-cdr (function).
assoc-or (function).
bind-extracted-keywords (macro).
boolify (function).
call-with-temporary-directory (function).
capitalize-first (function).
chunk (function).
def-as-func (macro).
dive (function).
do-alist (macro).
do-file-by-line (macro).
do-hash-table (macro).
do-list-with-rest (macro).
do-window (macro).
dos-to-unix (function).
dump (function).
edit-file-in-place (function).
encode-time-delta (function).
extract-keywords (function).
fetch-keyword (function).
first-match (function).
first-match-index (function).
flatten-1 (function).
flatten-1-when (function).
flatten-when (function).
hash-table->source (function).
hashval! (macro).
homedir-relative-pathname (function).
invert-hash-table (function).
key-in-hash? (function).
last-car (function).
last-match (function).
last-match-index (function).
length1 (function).
list-set-place (function).
make-clock (function).
map-assoc (function).
map-by-2 (function).
map-file-by-line (function).
map-improper (function).
mapc-improper (function).
mapcan-by-2 (function).
maplist/step (function).
mkstr (function).
nelt (function).
not-empty (function).
or2 (macro).
ordered-unique (function).
part-after-true (generic function).
part-on-index (function).
part-on-true (generic function).
part-tree (function).
pif (macro).
plist-p (function).
preserve-other-values (macro).
print-all-values (macro).
print-and (macro).
print-cond (macro).
print-lambda (macro).
quoted-list-p (function).
quoted-p (function).
quoted-symbol-p (function).
quotef (macro).
range (function).
rekey (function).
relative-to-range (function).
remove-if-member (function).
ret (macro).
return-on-true (macro).
sequence->list (function).
sequence-ends-with (function).
sequence-starts-with (function).
sequences-end-same (function).
sequences-start-same (function).
split-sequence-on-subseq (function).
splitfilter (function).
string-equal* (function).
string-equal-case (function).
string-equal-multiple (function).
string-join (function).
string-strip (function).
string-unless-number (function).
strip-leading (function).
strip-trailing (function).
symb (function).
symbol-unless-number (function).
symbolize (function).
three-way (macro).
to-lowercase (function).
to-uppercase (function).
truncate-string (function).
try-awhile (function).
tryit (macro).
use-package-with-shadowing (function).
user-cache-directory (function).
user-config-directory (function).
user-data-directory (function).
with-alist-keys (macro).
with-file-lock (macro).
with-temporary-directory (macro).
write-stream-to-file (function).
xsubseq (function).
%set-up-hash-table (function).
*dump-stor* (special variable).
Packages are listed by definition order.
gadgetscl-hash-util.
common-lisp.
*whitespace-characters* (special variable).
alist-p (function).
as-in-range (function).
assoc-all (function).
assoc-cdr (function).
assoc-or (function).
bind-extracted-keywords (macro).
boolify (function).
call-with-temporary-directory (function).
capitalize-first (function).
chunk (function).
def-as-func (macro).
dive (function).
do-alist (macro).
do-file-by-line (macro).
do-hash-table (macro).
do-list-with-rest (macro).
do-window (macro).
dos-to-unix (function).
dump (function).
edit-file-in-place (function).
encode-time-delta (function).
eval-always (macro).
extract-keywords (function).
fetch-keyword (function).
first-match (function).
first-match-index (function).
flatten-1 (function).
flatten-1-when (function).
flatten-when (function).
hash-table->source (function).
hashval! (macro).
homedir-relative-pathname (function).
invert-hash-table (function).
key-in-hash? (function).
last-car (function).
last-match (function).
last-match-index (function).
length1 (function).
list-set-place (function).
make-clock (function).
map-assoc (function).
map-by-2 (function).
map-file-by-line (function).
map-improper (function).
mapc-improper (function).
mapcan-by-2 (function).
maplist/step (function).
mkstr (function).
nelt (function).
not-empty (function).
or2 (macro).
ordered-unique (function).
part-after-true (generic function).
part-on-index (function).
part-on-true (generic function).
part-tree (function).
pif (macro).
plist-p (function).
preserve-other-values (macro).
print-all-values (macro).
print-and (macro).
print-cond (macro).
print-lambda (macro).
quoted-list-p (function).
quoted-p (function).
quoted-symbol-p (function).
quotef (macro).
range (function).
rekey (function).
relative-to-range (function).
remove-if-member (function).
ret (macro).
return-on-true (macro).
sequence->list (function).
sequence-ends-with (function).
sequence-starts-with (function).
sequences-end-same (function).
sequences-start-same (function).
split-sequence-on-subseq (function).
splitfilter (function).
string-equal* (function).
string-equal-case (function).
string-equal-multiple (function).
string-join (function).
string-strip (function).
string-unless-number (function).
strip-leading (function).
strip-trailing (function).
symb (function).
symbol-unless-number (function).
symbolize (function).
three-way (macro).
to-lowercase (function).
to-uppercase (function).
truncate-string (function).
try-awhile (function).
tryit (macro).
use-package-with-shadowing (function).
user-cache-directory (function).
user-config-directory (function).
user-data-directory (function).
with-alist-keys (macro).
with-file-lock (macro).
with-temporary-directory (macro).
write-stream-to-file (function).
xsubseq (function).
%set-up-hash-table (function).
*dump-stor* (special variable).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Removes the keywords named in keys, with their accompanying parameters, from the expression supplied in source. Source, minus the keys, is bound to remainder. The names of the keys are used for bindings for the accompanying values. (bind-extracted-keywords ((1 2 :x 3) data :x) <body>) Results in the body being executed with data bound to (1 2) and x bound to 3.
Set a variable in the function namespace.
Like dolist, iterates over a list, but instead of binding a single list
item per iteration binds a segment of the list as a sliding window.
(do-window (x ’(1 2 3 4 5 6)) ...)
will execute the body 5 times with x bound respectively to:
(1 2) (2 3) (3 4) (4 5) (5 6)
The step keyword adjusts how far the window slides per iteration. A destructuring spec can be provided in place of the variable. Therefore do-window
can be used to iterate over a plist like so:
(do-window ((k v) ’(:a 1 :b 2 :c 3) :step 2) ...)
Each key and value will be bound to k and v, respectively.
The size keyword allows adjustment of the window size.
Leading padding may be provided to do-window with the start-padding
keyword.
Tool for updating a hash table value. Binds the value found under KEY in HASH to VAR for duration of the macro. The return value of the body is placed into the hash table slot.
A version of or that bases its decision on the second value of each clause. Forms that return no second value are considered T.
Take the values returned by expression, pass the first of them to func,
returning its first value as the primary value and appending the remaining
values from expression as unchanged.
(1+ (values 1 2 3)) => 2
(preserve-other-values (values 1 2 3)
#’1+) => 2 2 3
Like print, but prints - and passes on - all values received. Useful for debugging expressions that return multiple values.
A single variable let that returns the variable when the body completes.
(ret x 3 (incf x)) => 4
Executes return/return-from on the result of clause if it is true
Execute the code in the body, returning T as the second value if the code executes without error, but returning (NIL NIL) if an exception is thrown. This provides a quick way to turn an error into a boolean value.
WARNING: This isn’t always a great idea for production code. Tryit will mask all raised errors, So if your code causes an error aside from the one you expect, you won’t be warned of the variance.
Get an exclusive lock on a file. If lock cannot be obtained, keep trying after waiting a while
Determine if an item appears to be an assoc list
Complement of relative-of-range function. Treats num as if it were a fraction of the range specified by start and end. Returns the absolute number that results.
Gets all items associated with a key, not just the first. Returns a list
(assoc-all :a ’((:a . 1) (:b . 2) (:c . 3) (:a . 4)))
=> (1 4)
A shortcut for (cdr (assoc ...)) to give immediate access to an alist value.
Finds the first key in keys that has a match in alist. Will use equal to match strings.
Attempts to guess when a string or number should be interpreted as T. Postive integers and strings like "true" and "yes" will be interpreted as true. Non-empty lists and sequences are true. Most other things are NIL
Returns a string representation of item with the first letter capitalized and the remaining characters lower-case, where applicable. Item can be a string or a symbol
Edit an existing file in place. The file location is specified in path. An input and an output stream are passed as parameters to the supplied function. The input function reads from the specified file; the output stream writes to a temporary file. The supplied function is assumed to read from the input stream, make any desired changes, and write to the output stream. If it returns without error, the streams are closed and the temporary file is copied over the original.
Traverses a plist or lambda list, removing the specified keywords and the
value that immediately follows each. Found key/value pairs are returned as a
plist in the first value. The cleaned list is returned as the second value.
This, or the related macro bind-extracted-keywords, is particularly useful for adding features to macros. It will strip out added keywords from parameter lists, allowing the remainder to be passed to the original macro processing code.
Find if a key is in a list, return the next item after it. if in-list is true, test the first element of any sublists for the key and if found return rest of list as parameter. A bit coarser in function than getf. Will tolerate improper plists.
See also ’some’
Returns the index of the first item in list that satisfies predicate.
Flattens conses found in the top level of a list. Nils in the top level will be removed.
(flatten-1 ’((1 2 3) nil (nil) ((4 5) (6 7))))
(1 2 3 NIL (4 5) (6 7))
Returns a list with any conses in it flattened if predicate returns true when called with that item. Will not flatten NILs unless the predicate indicates it. The predicate will not be called on non-cons items.
Recursively flattens any conses found in items if the predicate returns true on them. Will not flatten NILs unless the predicate indicates it. The predicate will not be called on non-cons items. Flatten-when will not normally descend into lists which it will not flatten, passing unchanged any list or cons item that fails the predicate. To cause it to descend into non-matching portions of the tree, set the :descend-all keyword.
Returns a source code representation of a hash table.
Returns a new hash table with keys and values swapped:
(:a 1 :b 3 :c 5) => (1 :a 3 :b 5 :c)
The hash table test can be set with :test. The method of value collection can be controlled with :mode. Modes are those available for cl-hash-util:collecting-hash-table.
Returns the first item from the end of the list that satisfies predicate.
Returns the index of the last item in list that satifies predicate.
Does item have a length of 1?
Map over a list, proper or not. The return mapping will be a proper list.
Mapc over a list, proper or not. Original list is returned. Like mapc, mapc-improper is used for side effects only.
Negative elt. Count in from the end of the sequence. 0 fetches the last element.
A predicate to detect 0 length sequences.
Returns a unique list of the items in list in the order in which they first appear.
Divides a list into two parts at the specified index. The two parts are returned as values. If the index is too large for the sequence, part-on-index will silently return the sequence as the first value. Set the :fail keyword T to raise an error instead.
Divides the s-expression supplied in tree into an inner and an outer portion. The outer portion is returned in the first value as a closure. The inner portion is returned as the second value. The inner portion consists of the first part of the tree that passes test. The tree is traversed breadth-first.
> (part-tree
(lambda (x) (eq ’deepest (car (ensure-list x))))
’(deep (deeper (deeperer (deepest (deepester you-are-here))))))
#<CLOSURE (LAMBDA (GADGETS::X) :IN GADGETS:PART-TREE) {C19C81D}>
(DEEPEST (DEEPESTER YOU-ARE-HERE))
> (funcall * :xyz)
(DEEP (DEEPER (DEEPERER :XYZ)))
The returned closure should be called with a single argument. It will return the outer portion with the supplied argument in place of the inner portion.
Determine if an item qualifies as a plist
Utility to test if a macro parameter is a quoted list. Returns the list if it is.
Macro utility to test if an item has been quoted by the macro user.
Macro utility to test if an item has been passed into a macro as a quoted symbol. If so, returns the symbol without the quote.
Creates a list containing a sequential range of integers. By default the
range runs from 0 to one below the supplied stop value:
(range 3) -> (0 1 2)
If a second parameter is supplied, the first is treated as a starting value, and
the second as a stop:
(range 7 10) -> (7 8 9)
The third parameter specifies a step size:
(range 0 10 2) -> (0 2 4 6 8)
A negative step parameter causes the range to travel down from the start to the
stop:
(range 10 5) -> (10 9 8 7 6)
Returns a value indicating where num is positioned relative to start and end. If num lies between start and end, the return value will be between 0.0 and 1.0.
Does the sequence end with the test sequence?
Does the sequence begin with the test sequence?
Given two sequences, does the tail of the longer match the shorter over its length? If the sequences are the same length then they must be equal to satisfy the predicate.
Given two sequences, are they the same until one runs out? This function does not care which sequence contains the other. Use sequence-starts-with if you need something more specific.
Broad version of string-equal. Will take input that is not a string or symbol.
A case sensitive version of string-equal.
For things that send multiple items with "[]" appended to the var name, a convention started by the PHP people. Mostly useful for web programming.
Strip whitespace characters from the beginning and end of a string. An alternate set of characters to strip can be supplied as a list in the optional second parameter.
Return the input as a string unless it can be recognized as an integer.
Convert the input string into a symbol unless it can be converted into a number.
Will continue to call predicate until either it returns success or a given amount of time elapses. Duration can be set with the :wait keyword. It defaults to 1 second. Try-awhile will sleep between predicate calls unless the :sleep keyword is set to nil. Default sleep is 0.001 of a second.
Try-awhile will return the predicate value on success or nil on failure. If a function is supplied to the :on-success argument, it will be executed if the predicate succeeds and its result will be returned instead of the predicate result. The :on-fail keyword may be used to supply a function that will be run if the time elapses without a predicate success. It’s result will be returned instead of the default nil.
OS independent functions to supply the recommended locations for user writable cache, config and data directories on the current platform. It’s best not to place application files in the returned directory. ’common-lisp/[appname]’ or perhaps ’[appname]/’ should first be appended to the diectory.
OS independent functions to supply the recommended locations for user writable cache, config and data directories on the current platform. It’s best not to place application files in the returned directory. ’common-lisp/[appname]’ or perhaps ’[appname]/’ should first be appended to the diectory.
OS independent functions to supply the recommended locations for user writable cache, config and data directories on the current platform. It’s best not to place application files in the returned directory. ’common-lisp/[appname]’ or perhaps ’[appname]/’ should first be appended to the diectory.
Write the whole contents of a stream to the file at ’path’, then close the file.
Returns sequence with start->end chopped out of it
Like part-on-true, but includes the first matching item in the first list.
Divides a list or sequence into two parts, with the second part starting with the first item to cause test to return true. The two parts of the sequence are returned as values. If a dividing point is not found, part-on-true will return the whole sequence as the first value. If you wish it to raise an error instead, set the :fail parameter to true.
| Jump to: | %
A B C D E F G H I K L M N O P Q R S T U W X |
|---|
| Jump to: | %
A B C D E F G H I K L M N O P Q R S T U W X |
|---|
| Jump to: | *
S |
|---|
| Jump to: | *
S |
|---|
| Jump to: | E F G P S |
|---|
| Jump to: | E F G P S |
|---|