Ben McGunigle's utility collection

Upstream URL


Ben McGunigle <>, Your Name <>


Apache License, version 2.0, Specify license here
Provided Systems



Ben McGunigle's collection of gadgets, odds, ends and utilities general.


Function Parameters: entity &key package Turns a string into an upcased symbol. The symbol will be interned in the current package if a package is not specified


Function: &rest args

Paul Graham's mkstr. Returns a string representation of the parameters.


Macro: var val &body body

A single variable let that returns the variable when the body completes.


Macro: var func-form

Set a variable in the function namespace.


Function: key alist &key in-list

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 the rest of the sublist. A bit coarser in function than getf. Will tolerate improper plists.


Function: keywords alist &key in-list test

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. 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.


Macro: (source remainder &rest keys) body

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.


Macro: setf-spec

Cause the item at the targeted location to become quoted:

> (defparameter *list* '(zero one two three))
> (quotef (elt *list* 2))
> *list*


Function: item

Macro utility to test if an item has been quoted by the macro user.


Function: item

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.


Function: item

Utility to test if a macro parameter is a quoted list. Returns the list if it is.


Function: package &optional target-package

Like use-package, but shadows existing symbols from target-package without asking. Target-package is the current package unless otherwise specified.



Function: item

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.


Function: item

Returns a lowercase copy of the supplied string.


Function: item

Returns an uppercase copy of the supplied string.


Function: item

For processing user input. Return the input as a string unless it can be recognized as an integer.


Function: item

Convert the input string into a symbol unless it can be converted into a number.


Function: item

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. This function is useful for interactions in which a human is expected to answer a true or false question.


Function: sequence

A predicate to detect 0 length sequences.


Function: seq seq2

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 for more specific results.


Function: seq testseq

Does the sequence begin with the test sequence?


Function: seq testseq

Does the sequence end with the test sequence?


Function: filler strings

Returns a string consisting of one each of the items in strings with filler interspersed between all of the items.

> (string-join " and " '("one" "two" "three"))
"one and two and three"



(#\Space #\Newline #\Backspace #\Tab #\Linefeed #\Page #\Return #\Rubout)


Function: a b

Broad version of string-equal. Will take input that is not a string or symbol.



A case sensitive version of string-equal.


Function: str &key length indicator

Trim a string to the length specified by length - default 20, appending instead the string specified by indicator - default "...".

Keyed collection


Function: &rest keys-and-alists

A shortcut for (cdr (assoc ...)).


Function: item alist &key test

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)


Function: keys alist

Finds the first key in keys that has a match in alist. Uses equal to match strings.


Function: item

Does an item appear to be an assoc-list?


Function: item

Determine if an item qualifies as a plist


Function: hash &key test mode

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.


Function: store mapping &key ignore-missing test

Takes a store (one of hash, alist or plist) and a mapping (also a hash, alist or plist) and returns a new hash table with the values from store rekeyed according to the oldkey -> newkey pairs found in mapping. Ignore-missing instructs rekey on what to do when a key is found in store but not in mapping. If true, rekey will drop the item that has no match. When false, it will include the item as is.

The result hash table will be created with the supplied test parameter.


Macro: (key value source) &body body

Iterate over an alist.


Macro: (key value source) &body body

Iterate over a hash table


Function: key hash

Check if a hash table has a key.

Shortcut for (nth-value 1 (gethash key hash))


Function: hash

Returns a source code representation of a hash table.

List and sequence


Function: sequence start end &key type

Returns copy of sequence with start->end chopped out of it.


Function: seq

Returns a list consisting of the contents of the input sequence.


Function: list

Returns the last item in a list proper.


Function: n list

Breaks a list up into n sized chunks.

>(chunk 3 '(a b c d e f g))
((A B C) (D E F) (G))


Function: list

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)) 


Function: predicate items &key descend-all

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.


Function: predicate items

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.


Function: list/seq index &key fail

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.


Function: predicate list/seq &key fail

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.


Function: predicate list/seq &key fail

Like part-on-true, but includes the first matching item in the first list.


Function: sequence things &key key test

Returns a copy of sequence without items that are a member of things. You can modify the test function which is used by member - default eq - with the :test keyword. The :key keyword allows a single parameter function that receives a sequence item and should return a modified item for comparison to the items in things.


Function: predicate list

Performs the remove-if-not and remove-if operations on a list simultaneously, returning each list as the first and second values respectively.


Function: subseq/s sequence

Searches for a phrase or phrases in a sequence. When it finds one, it returns as values the subsequence up to the match, the subsequence after the match, and the matching subsequence. If no match is found, the whole sequence is returned as the first value.


Function: predicate list

Like the built in function some, first-match returns the first item in the list that evaluates true in the predicate. First-match uses the second value to indicate success, unlike some.


Function: predicate list

Returns the index of the first item in list that satisfies predicate.


Function: list &key test

Returns a unique list of the items in list in the order in which they first appear.


Macro: (head tail source) &body body

A dolist for situations where access to the whole list is needed. Do-list-with-rest will iterate through the list supplied in source, initially binding the list to tail. On each iteration an item is removed from the first position of tail and pushed onto head. Note that the contents of head will be in reverse from those in source


Function: list index value padding

Returns a copy of the list with index set to value. If index is beyond the length of the list, pad out the list with the value in padding.



Function: start &optional stop step

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)


Function: start end num

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.


Function: start end num

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.

Execution control


Macro: &rest clauses

A version of or that bases its decision on the second value of each clause. Forms that return no second value are considered T.


Macro: (var/s source &key size step start-padding) &body body

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.


Macro: &body body

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 throws an error outside of what you expected, you won't be warned of the variance.


Macro: test minus-clause zero-clause plus-clause

If test results in a number that is less than zero, minus-clause will be evaluated. If zero, then zero-clause. Otherwise, plus-clause.


Macro: expression func

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


Function: func step list &rest more-lists

Maps through the supplied lists, passing a step-sized chunk from each into func. Returns a list of the results. The lists should all be the same length. That length should be divisible by the value specified in step.


Function: func list

Maps over a list two items at a time. The items are passed to the function as first and second parameters.


Function: func list

This function is ideal for processing plists. As with map-by-2, func will receive items 2 at a time as the first and second parameters. It should return a list. For example:

(mapcan-by-2 (lambda (key value) (list key value)) <some-list>)

will copy a plist with no changes.


Function: func alist

Map over an assoc list, with the key and value from each pair being sent to func as, respectively, the first and second parameters.


Function: func list?

Map over a list, proper or not. The return mapping will be a proper list.


Function: func list?

Mapc over a list, proper or not. Original list is returned. Like mapc, mapc-improper is used for side effects only.


Macro: clause &optional from-target

Executes return/return-from on the result of clause if it is true


Function: function &key sleep wait on-success on-fail

Will continue to call function 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 function calls unless the :sleep keyword is set to nil. Default sleep is 0.001 of a second.

Try-awhile will return the function value on success or nil on failure. If a function is supplied to the :on-success argument, it will be executed if the function succeeds and its result will be returned instead. The :on-fail keyword may be used to supply a function that will be run if the time elapses without a successful function run. Its result will be returned instead of the default nil.

Try-awhile blocks until completion.



Function: test tree

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))))))

> (funcall * :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.

File and OS


Macro: (line stream-or-path) &body body

Steps through a file or stream, one line at a time, binding the contents of the line to the variable specified in line. If a pathname is supplied, the file will be closed on completion or other exit. Streams will not be closed.


Function: function stream-or-path

A wrapper around do-file-by-line. The specified file or stream will be passed to the supplied function one line at a time. The function results will be accumulated in a list and returned.


Macro: (path &key interval) &body body

Get an exclusive lock on a file. If lock cannot be obtained, keep trying after waiting a while


Function: second minute hour day

A utility function for creating a time delta. Returns the time delta as an integer representing seconds.


Function: ticks-per-second

Returns a timer closure that, on execution, returns the number of units of time elapsed since make-clock returned it.


Function: name

Merge the supplied pathname onto the path of the current user's home directory.


Function: thunk &key want-pathname-p

Generates a temporary directory in the appropriate location (specified by uiop), calls the supplied function, then cleans up the directory.

By default, the created pathname is passed to the function. If want-pathname-p is set to NIL, the current directory will instead be set to the temporary directory for the duration of the call.


Macro: (&key pathname) &body body

Generates a temporary directory in the appropriate location (specified by uiop), executes the body of the macro, then cleans up the directory.

When a symbol is supplied to :pathname the temporary name will be bound to it. Otherwise the current directory will be set to the temporary directory for the duration of body execution.

Debugging printers

Certain forms are awkward to debug using plain print. These tools provide some extra options.


Macro: test then &optional else

This macro is a drop in replacement for if. It prints the test expression and the result of the test, indicating which way the if statement has branched.


Macro: (&rest args) &body body

A drop in replacement for lambda that behaves as trace does for defined functions.


Macro: &rest clauses

A verbose drop in replacement for cond.


Macro: &rest forms

A verbose drop in replacement for and.


Macro: expr

Like print, but prints - and passes on - all values received. Useful for debugging expressions that return multiple values.


Function: thing

For situations where print can't reach out. Put an item into storage for later retrieval by dive.



Retrieve dumped item.

Dependencies (6)

  • alexandria
  • cl-hash-util
  • cl-utilities
  • prove
  • split-sequence
  • uiop

Dependents (0)

    • GitHub
    • Quicklisp