The gadgets Reference Manual

This is the gadgets Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Nov 04 13:32:40 2020 GMT+0.

1 Introduction

Gadgets

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

symbolize

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

mkstr

Function: &rest args

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

ret

Macro: var val &body body

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

def-as-func

Macro: var func-form

Set a variable in the function namespace.

fetch-keyword

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.

extract-keywords

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.

bind-extracted-keywords

Macro: (source remainder &rest keys) body

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

quotef

Macro: setf-spec

Cause the item at the targeted location to become quoted:

> (defparameter *list* '(zero one two three))
> (quotef (elt *list* 2))
> *list*
(ZERO ONE 'TWO THREE)

quoted-p

Function: item

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

quoted-symbol-p

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.

quoted-list-p

Function: item

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

use-package-with-shadowing

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.

String

capitalize-first

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.

to-lowercase

Function: item

Returns a lowercase copy of the supplied string.

to-uppercase

Function: item

Returns an uppercase copy of the supplied string.

string-unless-number

Function: item

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

symbol-unless-number

Function: item

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

boolify

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.

not-empty

Function: sequence

A predicate to detect 0 length sequences.

sequences-start-same

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.

sequence-starts-with

Function: seq testseq

Does the sequence begin with the test sequence?

sequence-ends-with

Function: seq testseq

Does the sequence end with the test sequence?

string-join

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"

whitespace-characters

List

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

string-equal*

Function: a b

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

string-equal-case

Function:

A case sensitive version of string-equal.

truncate-string

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

assoc-cdr

Function: &rest keys-and-alists

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

assoc-all

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)

assoc-or

Function: keys alist

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

alist-p

Function: item

Does an item appear to be an assoc-list?

plist-p

Function: item

Determine if an item qualifies as a plist

invert-hash-table

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.

rekey

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.

do-alist

Macro: (key value source) &body body

Iterate over an alist.

do-hash-table

Macro: (key value source) &body body

Iterate over a hash table

key-in-hash?

Function: key hash

Check if a hash table has a key.

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

hash-table-source

Function: hash

Returns a source code representation of a hash table.

List and sequence

xsubseq

Function: sequence start end &key type

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

sequence->list

Function: seq

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

last-car

Function: list

Returns the last item in a list proper.

chunk

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

flatten-1

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

flatten-when

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.

flatten-1-when

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.

part-on-index

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.

part-on-true

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.

part-after-true

Function: predicate list/seq &key fail

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

remove-if-member

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.

splitfilter

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.

split-sequence-on-subseq

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.

first-match

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.

first-match-index

Function: predicate list

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

ordered-unique

Function: list &key test

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

do-list-with-rest

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

list-set-place

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.

Numerical

range

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)

relative-to-range

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.

as-in-range

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

or2

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.

do-window

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.

tryit

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.

three-way

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.

preserve-other-values

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

maplist/step

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.

map-by-2

Function: func list

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

mapcan-by-2

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.

map-assoc

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.

map-improper

Function: func list?

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

mapc-improper

Function: func list?

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

return-on-true

Macro: clause &optional from-target

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

try-awhile

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.

Tree

part-tree

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

File and OS

do-file-by-line

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.

map-file-by-line

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.

with-file-lock

Macro: (path &key interval) &body body

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

encode-time-delta

Function: second minute hour day

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

make-clock

Function: ticks-per-second

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

homedir-relative-pathname

Function: name

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

call-with-temporary-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.

with-temporary-directory

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.

pif

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.

print-lambda

Macro: (&rest args) &body body

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

print-cond

Macro: &rest clauses

A verbose drop in replacement for cond.

print-and

Macro: &rest forms

A verbose drop in replacement for and.

print-all-values

Macro: expr

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

dump

Function: thing

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

dive

Function

Retrieve dumped item.

2 Systems

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

2.1 `gadgets`

Author

Ben McGunigle <bnmcgn@gmail.com>

License

Apache License, version 2.0

Description

Ben McGunigle’s utility collection

Dependencies

alexandria
uiop
cl-hash-util
cl-utilities

Source

gadgets.asd (file)

Components

package.lisp (file)
early.lisp (file)
gadgets.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 `gadgets.asd`

Location: gadgets.asd
Systems: gadgets (system)

3.1.2 `gadgets/package.lisp`

Parent: gadgets (system)
Location: package.lisp
Packages: gadgets

3.1.3 `gadgets/early.lisp`

Dependency: package.lisp (file)
Parent: gadgets (system)
Location: early.lisp
Exported Definitions: eval-always (macro)

3.1.4 `gadgets/gadgets.lisp`

Dependencies

early.lisp (file)
early.lisp (file)

Parent

gadgets (system)

Location

gadgets.lisp

Exported Definitions

*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)
dump (function)
encode-time-delta (function)
extract-keywords (function)
fetch-keyword (function)
first-match (function)
flatten-1 (function)
flatten-1-when (function)
flatten-when (function)
hash-table->source (function)
homedir-relative-pathname (function)
invert-hash-table (function)
key-in-hash? (function)
last-car (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)
not-empty (function)
or2 (macro)
ordered-unique (function)
part-after-true (generic function)
part-after-true (method)
part-after-true (method)
part-on-index (function)
part-on-true (generic function)
part-on-true (method)
part-on-true (method)
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-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-unless-number (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)
with-file-lock (macro)
with-temporary-directory (macro)
xsubseq (function)

Internal Definitions

%set-up-hash-table (function)
*dump-stor* (special variable)
first-match-index (function)

4 Packages

Packages are listed by definition order.

4.1 `gadgets`

Source

package.lisp (file)

Use List

cl-hash-util
common-lisp

Exported Definitions

*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)
dump (function)
encode-time-delta (function)
eval-always (macro)
extract-keywords (function)
fetch-keyword (function)
first-match (function)
flatten-1 (function)
flatten-1-when (function)
flatten-when (function)
hash-table->source (function)
homedir-relative-pathname (function)
invert-hash-table (function)
key-in-hash? (function)
last-car (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)
not-empty (function)
or2 (macro)
ordered-unique (function)
part-after-true (generic function)
part-after-true (method)
part-after-true (method)
part-on-index (function)
part-on-true (generic function)
part-on-true (method)
part-on-true (method)
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-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-unless-number (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)
with-file-lock (macro)
with-temporary-directory (macro)
xsubseq (function)

Internal Definitions

%set-up-hash-table (function)
*dump-stor* (special variable)
first-match-index (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *whitespace-characters*

Package: gadgets
Source: gadgets.lisp (file)

5.1.2 Macros

Macro: bind-extracted-keywords (SOURCE REMAINDER &rest KEYS) &body 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.

Package: gadgets
Source: gadgets.lisp (file)

Macro: def-as-func VAR FUNC-FORM

Set a variable in the function namespace.

Package: gadgets
Source: gadgets.lisp (file)

Macro: do-alist (KEY VALUE SOURCE) &body BODY

Package: gadgets
Source: gadgets.lisp (file)

Macro: do-file-by-line (LINE STREAM-OR-PATH) &body BODY

Package: gadgets
Source: gadgets.lisp (file)

Macro: do-hash-table (KEY VALUE SOURCE) &body BODY

Package: gadgets
Source: gadgets.lisp (file)

Macro: do-list-with-rest (HEAD TAIL SOURCE) &body BODY

Package: gadgets
Source: gadgets.lisp (file)

Macro: do-window (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.

Package: gadgets
Source: gadgets.lisp (file)

Macro: eval-always &body BODY

Package: gadgets
Source: early.lisp (file)

Macro: or2 &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.

Package: gadgets
Source: gadgets.lisp (file)

Macro: pif TEST THEN &optional ELSE

Package: gadgets
Source: gadgets.lisp (file)

Macro: preserve-other-values 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

Package: gadgets
Source: gadgets.lisp (file)

Macro: print-all-values EXPR

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

Package: gadgets
Source: gadgets.lisp (file)

Macro: print-and &rest FORMS

Package: gadgets
Source: gadgets.lisp (file)

Macro: print-cond &rest CLAUSES

Package: gadgets
Source: gadgets.lisp (file)

Macro: print-lambda (&rest ARGS) &body BODY

Package: gadgets
Source: gadgets.lisp (file)

Macro: quotef SETF-SPEC

Package: gadgets
Source: gadgets.lisp (file)

Macro: ret VAR VAL &body BODY

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

(ret x 3 (incf x)) => 4

Package: gadgets
Source: gadgets.lisp (file)

Macro: return-on-true CLAUSE &optional FROM-TARGET

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

Package: gadgets
Source: gadgets.lisp (file)

Macro: three-way TEST MINUS-CLAUSE ZERO-CLAUSE PLUS-CLAUSE

Package: gadgets
Source: gadgets.lisp (file)

Macro: tryit &body BODY

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.

Package: gadgets
Source: gadgets.lisp (file)

Macro: with-file-lock (PATH &key INTERVAL) &body BODY

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

Package: gadgets
Source: gadgets.lisp (file)

Macro: with-temporary-directory (&key PATHNAME) &body BODY

Package: gadgets
Source: gadgets.lisp (file)

5.1.3 Functions

Function: alist-p ITEM

Determine if an item appears to be an assoc list

Package: gadgets
Source: gadgets.lisp (file)

Function: as-in-range 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.

Package: gadgets
Source: gadgets.lisp (file)

Function: assoc-all 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)

Package: gadgets
Source: gadgets.lisp (file)

Function: assoc-cdr &rest KEYS-AND-ALISTS

A shortcut for (cdr (assoc ...)) to give immediate access to an alist value.

Package: gadgets
Source: gadgets.lisp (file)

Function: assoc-or KEYS ALIST

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

Package: gadgets
Source: gadgets.lisp (file)

Function: boolify ITEM

Package: gadgets
Source: gadgets.lisp (file)

Function: call-with-temporary-directory THUNK &key WANT-PATHNAME-P

Package: gadgets
Source: gadgets.lisp (file)

Function: capitalize-first 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

Package: gadgets
Source: gadgets.lisp (file)

Function: chunk N ALIST

Package: gadgets
Source: gadgets.lisp (file)

Function: dive ()

Package: gadgets
Source: gadgets.lisp (file)

Function: dump THING

Package: gadgets
Source: gadgets.lisp (file)

Function: encode-time-delta SECOND MINUTE HOUR DAY

Package: gadgets
Source: gadgets.lisp (file)

Function: extract-keywords 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 in the first value. The cleaned list is returned as the second value.

Package: gadgets
Source: gadgets.lisp (file)

Function: fetch-keyword KEY ALIST &key IN-LIST

Find if a key is in a list, return the next item after it. if checklist 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.

Package: gadgets
Source: gadgets.lisp (file)

Function: first-match PREDICATE LIST

5.1.4 Generic functions

Generic Function: part-after-true TEST LIST/SEQ &key FAIL

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

Package

gadgets

Source

gadgets.lisp (file)

Methods

Method: part-after-true (TEST function) (LIST/SEQ list) &key FAIL

Method: part-after-true (TEST function) (LIST/SEQ sequence) &key FAIL

Generic Function: part-on-true TEST LIST/SEQ &key FAIL

Package

gadgets

Source

gadgets.lisp (file)

Methods

Method: part-on-true (TEST function) (LIST/SEQ list) &key FAIL

Method: part-on-true (TEST function) (LIST/SEQ sequence) &key FAIL

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *dump-stor*

Package: gadgets
Source: gadgets.lisp (file)

5.2.2 Functions

Function: %set-up-hash-table DATA TEST

Package: gadgets
Source: gadgets.lisp (file)

Function: first-match-index PREDICATE LIST

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

Package: gadgets
Source: gadgets.lisp (file)

Appendix A Indexes

A.1 Concepts

Jump to:	F G L

	Index Entry	Section

F
	File, Lisp, `gadgets.asd`:	The gadgets․asd file
	File, Lisp, `gadgets/early.lisp`:	The gadgets/early․lisp file
	File, Lisp, `gadgets/gadgets.lisp`:	The gadgets/gadgets․lisp file
	File, Lisp, `gadgets/package.lisp`:	The gadgets/package․lisp file

G
	`gadgets.asd`:	The gadgets․asd file
	`gadgets/early.lisp`:	The gadgets/early․lisp file
	`gadgets/gadgets.lisp`:	The gadgets/gadgets․lisp file
	`gadgets/package.lisp`:	The gadgets/package․lisp file

L
	Lisp File, `gadgets.asd`:	The gadgets․asd file
	Lisp File, `gadgets/early.lisp`:	The gadgets/early․lisp file
	Lisp File, `gadgets/gadgets.lisp`:	The gadgets/gadgets․lisp file
	Lisp File, `gadgets/package.lisp`:	The gadgets/package․lisp file

Jump to:	F G L

A.2 Functions

Jump to:	% A B C D E F G H I K L M N O P Q R S T U W X

	Index Entry	Section

%
	`%set-up-hash-table`:	Internal functions

A
	`alist-p`:	Exported functions
	`as-in-range`:	Exported functions
	`assoc-all`:	Exported functions
	`assoc-cdr`:	Exported functions
	`assoc-or`:	Exported functions

B
	`bind-extracted-keywords`:	Exported macros
	`boolify`:	Exported functions

C
	`call-with-temporary-directory`:	Exported functions
	`capitalize-first`:	Exported functions
	`chunk`:	Exported functions

D
	`def-as-func`:	Exported macros
	`dive`:	Exported functions
	`do-alist`:	Exported macros
	`do-file-by-line`:	Exported macros
	`do-hash-table`:	Exported macros
	`do-list-with-rest`:	Exported macros
	`do-window`:	Exported macros
	`dump`:	Exported functions

E
	`encode-time-delta`:	Exported functions
	`eval-always`:	Exported macros
	`extract-keywords`:	Exported functions

F
	`fetch-keyword`:	Exported functions
	`first-match`:	Exported functions
	`first-match-index`:	Internal functions
	`flatten-1`:	Exported functions
	`flatten-1-when`:	Exported functions
	`flatten-when`:	Exported functions
	`Function, %set-up-hash-table`:	Internal functions
	`Function, alist-p`:	Exported functions
	`Function, as-in-range`:	Exported functions
	`Function, assoc-all`:	Exported functions
	`Function, assoc-cdr`:	Exported functions
	`Function, assoc-or`:	Exported functions
	`Function, boolify`:	Exported functions
	`Function, call-with-temporary-directory`:	Exported functions
	`Function, capitalize-first`:	Exported functions
	`Function, chunk`:	Exported functions
	`Function, dive`:	Exported functions
	`Function, dump`:	Exported functions
	`Function, encode-time-delta`:	Exported functions
	`Function, extract-keywords`:	Exported functions
	`Function, fetch-keyword`:	Exported functions
	`Function, first-match`:	Exported functions
	`Function, first-match-index`:	Internal functions
	`Function, flatten-1`:	Exported functions
	`Function, flatten-1-when`:	Exported functions
	`Function, flatten-when`:	Exported functions
	`Function, hash-table->source`:	Exported functions
	`Function, homedir-relative-pathname`:	Exported functions
	`Function, invert-hash-table`:	Exported functions
	`Function, key-in-hash?`:	Exported functions
	`Function, last-car`:	Exported functions
	`Function, list-set-place`:	Exported functions
	`Function, make-clock`:	Exported functions
	`Function, map-assoc`:	Exported functions
	`Function, map-by-2`:	Exported functions
	`Function, map-file-by-line`:	Exported functions
	`Function, map-improper`:	Exported functions
	`Function, mapc-improper`:	Exported functions
	`Function, mapcan-by-2`:	Exported functions
	`Function, maplist/step`:	Exported functions
	`Function, mkstr`:	Exported functions
	`Function, not-empty`:	Exported functions
	`Function, ordered-unique`:	Exported functions
	`Function, part-on-index`:	Exported functions
	`Function, part-tree`:	Exported functions
	`Function, plist-p`:	Exported functions
	`Function, quoted-list-p`:	Exported functions
	`Function, quoted-p`:	Exported functions
	`Function, quoted-symbol-p`:	Exported functions
	`Function, range`:	Exported functions
	`Function, rekey`:	Exported functions
	`Function, relative-to-range`:	Exported functions
	`Function, remove-if-member`:	Exported functions
	`Function, sequence->list`:	Exported functions
	`Function, sequence-ends-with`:	Exported functions
	`Function, sequence-starts-with`:	Exported functions
	`Function, sequences-start-same`:	Exported functions
	`Function, split-sequence-on-subseq`:	Exported functions
	`Function, splitfilter`:	Exported functions
	`Function, string-equal*`:	Exported functions
	`Function, string-equal-case`:	Exported functions
	`Function, string-equal-multiple`:	Exported functions
	`Function, string-join`:	Exported functions
	`Function, string-unless-number`:	Exported functions
	`Function, symb`:	Exported functions
	`Function, symbol-unless-number`:	Exported functions
	`Function, symbolize`:	Exported functions
	`Function, to-lowercase`:	Exported functions
	`Function, to-uppercase`:	Exported functions
	`Function, truncate-string`:	Exported functions
	`Function, try-awhile`:	Exported functions
	`Function, use-package-with-shadowing`:	Exported functions
	`Function, xsubseq`:	Exported functions

G
	`Generic Function, part-after-true`:	Exported generic functions
	`Generic Function, part-on-true`:	Exported generic functions

H
	`hash-table->source`:	Exported functions
	`homedir-relative-pathname`:	Exported functions

I
	`invert-hash-table`:	Exported functions

K
	`key-in-hash?`:	Exported functions

L
	`last-car`:	Exported functions
	`list-set-place`:	Exported functions

M
	`Macro, bind-extracted-keywords`:	Exported macros
	`Macro, def-as-func`:	Exported macros
	`Macro, do-alist`:	Exported macros
	`Macro, do-file-by-line`:	Exported macros
	`Macro, do-hash-table`:	Exported macros
	`Macro, do-list-with-rest`:	Exported macros
	`Macro, do-window`:	Exported macros
	`Macro, eval-always`:	Exported macros
	`Macro, or2`:	Exported macros
	`Macro, pif`:	Exported macros
	`Macro, preserve-other-values`:	Exported macros
	`Macro, print-all-values`:	Exported macros
	`Macro, print-and`:	Exported macros
	`Macro, print-cond`:	Exported macros
	`Macro, print-lambda`:	Exported macros
	`Macro, quotef`:	Exported macros
	`Macro, ret`:	Exported macros
	`Macro, return-on-true`:	Exported macros
	`Macro, three-way`:	Exported macros
	`Macro, tryit`:	Exported macros
	`Macro, with-file-lock`:	Exported macros
	`Macro, with-temporary-directory`:	Exported macros
	`make-clock`:	Exported functions
	`map-assoc`:	Exported functions
	`map-by-2`:	Exported functions
	`map-file-by-line`:	Exported functions
	`map-improper`:	Exported functions
	`mapc-improper`:	Exported functions
	`mapcan-by-2`:	Exported functions
	`maplist/step`:	Exported functions
	`Method, part-after-true`:	Exported generic functions
	`Method, part-after-true`:	Exported generic functions
	`Method, part-on-true`:	Exported generic functions
	`Method, part-on-true`:	Exported generic functions
	`mkstr`:	Exported functions

N
	`not-empty`:	Exported functions

O
	`or2`:	Exported macros
	`ordered-unique`:	Exported functions

P
	`part-after-true`:	Exported generic functions
	`part-after-true`:	Exported generic functions
	`part-after-true`:	Exported generic functions
	`part-on-index`:	Exported functions
	`part-on-true`:	Exported generic functions
	`part-on-true`:	Exported generic functions
	`part-on-true`:	Exported generic functions
	`part-tree`:	Exported functions
	`pif`:	Exported macros
	`plist-p`:	Exported functions
	`preserve-other-values`:	Exported macros
	`print-all-values`:	Exported macros
	`print-and`:	Exported macros
	`print-cond`:	Exported macros
	`print-lambda`:	Exported macros

Q
	`quoted-list-p`:	Exported functions
	`quoted-p`:	Exported functions
	`quoted-symbol-p`:	Exported functions
	`quotef`:	Exported macros

R
	`range`:	Exported functions
	`rekey`:	Exported functions
	`relative-to-range`:	Exported functions
	`remove-if-member`:	Exported functions
	`ret`:	Exported macros
	`return-on-true`:	Exported macros

S
	`sequence->list`:	Exported functions
	`sequence-ends-with`:	Exported functions
	`sequence-starts-with`:	Exported functions
	`sequences-start-same`:	Exported functions
	`split-sequence-on-subseq`:	Exported functions
	`splitfilter`:	Exported functions
	`string-equal*`:	Exported functions
	`string-equal-case`:	Exported functions
	`string-equal-multiple`:	Exported functions
	`string-join`:	Exported functions
	`string-unless-number`:	Exported functions
	`symb`:	Exported functions
	`symbol-unless-number`:	Exported functions
	`symbolize`:	Exported functions

T
	`three-way`:	Exported macros
	`to-lowercase`:	Exported functions
	`to-uppercase`:	Exported functions
	`truncate-string`:	Exported functions
	`try-awhile`:	Exported functions
	`tryit`:	Exported macros

U
	`use-package-with-shadowing`:	Exported functions

W
	`with-file-lock`:	Exported macros
	`with-temporary-directory`:	Exported macros

X
	`xsubseq`:	Exported functions

Jump to:	% A B C D E F G H I K L M N O P Q R S T U W X

A.3 Variables

Jump to:	* S

	Index Entry	Section

*
	`dump-stor`:	Internal special variables
	`whitespace-characters`:	Exported special variables

S
	`Special Variable, dump-stor`:	Internal special variables
	`Special Variable, whitespace-characters`:	Exported special variables

Jump to:	* S

A.4 Data types

Jump to:	G P S

	Index Entry	Section

G
	`gadgets`:	The gadgets system
	`gadgets`:	The gadgets package

P
	`Package, gadgets`:	The gadgets package

S
	`System, gadgets`:	The gadgets system

Jump to:	G P S

• Introduction		What gadgets is all about
• Systems		The systems documentation
• Files		The files documentation
• Packages		The packages documentation
• Definitions		The symbols documentation
• Indexes		Concepts, functions, variables and data types

• The gadgets.asd file
• The gadgets/package.lisp file
• The gadgets/early.lisp file
• The gadgets/gadgets.lisp file

• Exported special variables
• Exported macros
• Exported functions
• Exported generic functions

• Concept index
• Function index
• Variable index
• Data type index

The gadgets Reference Manual

Table of Contents

The gadgets Reference Manual

1 Introduction

Gadgets

symbolize

mkstr

Function: &rest args

ret

Macro: var val &body body

def-as-func

Macro: var func-form

fetch-keyword

Function: key alist &key in-list

extract-keywords

Function: keywords alist &key in-list test

bind-extracted-keywords

Macro: (source remainder &rest keys) body

quotef

Macro: setf-spec

quoted-p

Function: item

quoted-symbol-p

Function: item

quoted-list-p

Function: item

use-package-with-shadowing

Function: package &optional target-package

String

capitalize-first

Function: item

to-lowercase

Function: item

to-uppercase

Function: item

string-unless-number

Function: item

symbol-unless-number

Function: item

boolify

Function: item

not-empty

Function: sequence

sequences-start-same

Function: seq seq2

sequence-starts-with

Function: seq testseq

sequence-ends-with

Function: seq testseq

string-join

Function: filler strings

whitespace-characters

List

string-equal*

Function: a b

string-equal-case

Function:

truncate-string

Function: str &key length indicator

Keyed collection

assoc-cdr

Function: &rest keys-and-alists

assoc-all

Function: item alist &key test

assoc-or

Function: keys alist

alist-p

Function: item

plist-p

Function: item

invert-hash-table

Function: hash &key test mode

rekey

Function: store mapping &key ignore-missing test

do-alist

Macro: (key value source) &body body

do-hash-table

Macro: (key value source) &body body

key-in-hash?

Function: key hash