The gadgets Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

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.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Gadgets

CircleCI

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

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.

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.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 gadgets

Author

Ben McGunigle <bnmcgn@gmail.com>

License

Apache License, version 2.0

Description

Ben McGunigle’s utility collection

Dependencies
Source

gadgets.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 gadgets.asd

Location

gadgets.asd

Systems

gadgets (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 gadgets/package.lisp

Parent

gadgets (system)

Location

package.lisp

Packages

gadgets


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 gadgets/early.lisp

Dependency

package.lisp (file)

Parent

gadgets (system)

Location

early.lisp

Exported Definitions

eval-always (macro)


Previous: , Up: Lisp files   [Contents][Index]

3.1.4 gadgets/gadgets.lisp

Dependencies
Parent

gadgets (system)

Location

gadgets.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 gadgets

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *whitespace-characters*
Package

gadgets

Source

gadgets.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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

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.

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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

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

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.

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.

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

See also ’some’

Package

gadgets

Source

gadgets.lisp (file)

Function: flatten-1 ALIST

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

Package

gadgets

Source

gadgets.lisp (file)

Function: flatten-1-when 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.

Package

gadgets

Source

gadgets.lisp (file)

Function: flatten-when 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.

Package

gadgets

Source

gadgets.lisp (file)

Function: hash-table->source HT

Returns a source code representation of a hash table.

Package

gadgets

Source

gadgets.lisp (file)

Function: homedir-relative-pathname NAME
Package

gadgets

Source

gadgets.lisp (file)

Function: invert-hash-table 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.

Package

gadgets

Source

gadgets.lisp (file)

Function: key-in-hash? KEY HASHTABLE
Package

gadgets

Source

gadgets.lisp (file)

Function: last-car LIST
Package

gadgets

Source

gadgets.lisp (file)

Function: list-set-place TLIST IND VAL PADDING
Package

gadgets

Source

gadgets.lisp (file)

Function: make-clock TICKS-PER-SECOND
Package

gadgets

Source

gadgets.lisp (file)

Function: map-assoc FUNC ALIST
Package

gadgets

Source

gadgets.lisp (file)

Function: map-by-2 FUNC LIST
Package

gadgets

Source

gadgets.lisp (file)

Function: map-file-by-line FUNCTION STREAM-OR-PATH
Package

gadgets

Source

gadgets.lisp (file)

Function: map-improper FUNC LIST?

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

Package

gadgets

Source

gadgets.lisp (file)

Function: mapc-improper FUNC LIST?

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

Package

gadgets

Source

gadgets.lisp (file)

Function: mapcan-by-2 FUNC LIST
Package

gadgets

Source

gadgets.lisp (file)

Function: maplist/step FUNC STEP LIST &rest MORE-LISTS
Package

gadgets

Source

gadgets.lisp (file)

Function: mkstr &rest ARGS
Package

gadgets

Source

gadgets.lisp (file)

Function: not-empty ITM

A predicate to detect 0 length sequences.

Package

gadgets

Source

gadgets.lisp (file)

Function: ordered-unique LIST &key TEST

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

Package

gadgets

Source

gadgets.lisp (file)

Function: part-on-index 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.

Package

gadgets

Source

gadgets.lisp (file)

Function: part-tree 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.

Package

gadgets

Source

gadgets.lisp (file)

Function: plist-p ITEM

Determine if an item qualifies as a plist

Package

gadgets

Source

gadgets.lisp (file)

Function: quoted-list-p ITEM

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

Package

gadgets

Source

gadgets.lisp (file)

Function: quoted-p ITEM

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

Package

gadgets

Source

gadgets.lisp (file)

Function: quoted-symbol-p 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.

Package

gadgets

Source

gadgets.lisp (file)

Function: range 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)

Package

gadgets

Source

gadgets.lisp (file)

Function: rekey STORE MAPPING &key IGNORE-MISSING TEST
Package

gadgets

Source

gadgets.lisp (file)

Function: relative-to-range 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.

Package

gadgets

Source

gadgets.lisp (file)

Function: remove-if-member SEQ THINGS &key KEY TEST
Package

gadgets

Source

gadgets.lisp (file)

Function: sequence->list SEQ
Package

gadgets

Source

gadgets.lisp (file)

Function: sequence-ends-with SEQ TESTSEQ

Does the sequence end with the test sequence?

Package

gadgets

Source

gadgets.lisp (file)

Function: sequence-starts-with SEQ TESTSEQ

Does the sequence begin with the test sequence?

Package

gadgets

Source

gadgets.lisp (file)

Function: sequences-start-same 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 if you need something more specific.

Package

gadgets

Source

gadgets.lisp (file)

Function: split-sequence-on-subseq SUBSEQ/S SEQUENCE
Package

gadgets

Source

gadgets.lisp (file)

Function: splitfilter PREDICATE ALIST
Package

gadgets

Source

gadgets.lisp (file)

Function: string-equal* A B

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

Package

gadgets

Source

gadgets.lisp (file)

Function: string-equal-case A B

A case sensitive version of string-equal.

Package

gadgets

Source

gadgets.lisp (file)

Function: string-equal-multiple A B

For things that send multiple items with "[]" appended to the var name, a convention started by the PHP people. Mostly useful for web programming.

Package

gadgets

Source

gadgets.lisp (file)

Function: string-join FILLER STRINGS
Package

gadgets

Source

gadgets.lisp (file)

Function: string-unless-number X

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

Package

gadgets

Source

gadgets.lisp (file)

Function: symb &rest ARGS
Package

gadgets

Source

gadgets.lisp (file)

Function: symbol-unless-number X

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

Package

gadgets

Source

gadgets.lisp (file)

Function: symbolize ENTITY &key PACKAGE
Package

gadgets

Source

gadgets.lisp (file)

Function: to-lowercase ITEM
Package

gadgets

Source

gadgets.lisp (file)

Function: to-uppercase ITEM
Package

gadgets

Source

gadgets.lisp (file)

Function: truncate-string STR &key LENGTH INDICATOR
Package

gadgets

Source

gadgets.lisp (file)

Function: try-awhile PREDICATE &key SLEEP WAIT ON-SUCCESS ON-FAIL

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.

Package

gadgets

Source

gadgets.lisp (file)

Function: use-package-with-shadowing PACKAGE &optional TARGET-PACKAGE
Package

gadgets

Source

gadgets.lisp (file)

Function: xsubseq SEQUENCE START END &key TYPE

Returns sequence with start->end chopped out of it

Package

gadgets

Source

gadgets.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

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

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.

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

Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *dump-stor*
Package

gadgets

Source

gadgets.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

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  

Next: , Previous: , Up: Indexes   [Contents][Index]

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  

Next: , Previous: , Up: Indexes   [Contents][Index]

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  

Previous: , Up: Indexes   [Contents][Index]

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