Stutter Library

You can load these by (require 'library-name).






(1+|1- v)

Macros for v + 1 and - 1.

(assign (symb1 symb2 ...) list)

Quick way to assign subsequent elements of a list to different symbols. (The generated assignments use set!.) For example:

> (assign (a (b c)) '(1 (2 3)))
> (list a b c)
(1 2 3)

(grab (symb1 symb2 ...) list)

Same as assign, but uses setq instead of set!.

(cadr|second v)

Macro for (car (cdr v)).

(caddr|third v)

Macro for (car (cdr (cdr v))).

(cadddr|fourth v)

Macro for (car (cdr (cdr (cdr v)))).

(when test code ...)

Short for (if test (begin code ...))

(round number)

Returns number rounded to the nearest integer.

(cut proc arg1 ...)

Macro that returns (lambda () (proc arg1 ...)), except if any of the arguments equals <>, it adds a parameter to the lambda and uses that parameter in the call. For example, (cut + <> 2) will give (lambda (n) (+ n 2)) (except it tries to generate unique parameter names with gensym). If <---> occurs in the argument list, all remaining arguments are inserted into the call there; this means that ((cut list 1 2 <---> 5 6) 3 4) will give (1 2 3 4 5 6).

(defconst name value)

Macro that defines a constant (with symbolic-macro, so the value replaces the referencing symbols).

(defun name params body ...)

Macro for (set 'name (lambda params body ...))

(defmacro name params body ...)

Macro for (set 'name (macro params body ...))

(defsetf place (loc val) body ...)

Defines a setf expansion for (setf (place loc...) val). Body should be a macro body that returns appropriate code for performing the set. The two parameters are the cdr of the place (e.g. when (setf (aref n 1 2) 8), it's (n 1 2)) and the expression for the new value. Example:

(defsetf car (loc val)
		 `(scar ,(car loc) ,val))

(dotimes (symbol count) body ...)

Executes body count times, each time binding the iteration counter (up from 0) to the symbol. Supports return.

(dolist (symbol list) body ...)

Executes body for each element in the list, each time binding the current element to the symbol. Supports return.

(for init test incr body ...)

Macro that implements a C-like for construct. Example:

> (for (set 'i 0) (< i 3) (set 'i (1+ i)) (println i))

Supports return.


Returns a supposedly unique symbol (actually, symbols like GENSYM-N, where N is an incremented integer).


The lc-* functions provide a non-functional list construction facility. This one results a handle to a new constructor.

(lc-append handle obj)

Appends the object to the end of the constructed list.

(lc-get handle)

Returns the constructed list.

(loop ...)

Loop constructor. Supported methods of iteration:

Extra loop termination conditionals:

Supported actions:

(setf place value)

Macro system that updates a place to a value. It knows a number of possible places by default (e.g. a symbol, (car something), (third list), etc), and can be taught more (with defsetf).

(setq name value)

Macro for (set 'name value).

(sqlite-query handle query (args) (fn))

A convenience function for SQLite -exec-like queries with type support.

The query may contain parameter places that are filled in from the optional args list, in order. Elements from the args list might be two-element lists instead of atoms; in that case, the first of the pair is used as parameter name and the second as value.

By default, the results are returned similarly as sqlite-exec would. If however a lambda is passed as the fourth fn parameter, it's called for each row with two arguments (current row as list, and a list of column names), and finally nil is returned.

Regular Expressions

match?, match1, match*, split, replace1, replace*

These are convenience macros for the pcre- family of functions in the PCRE module. Each has the same call signature as its pcre- counterpart, but takes a regular expression in a string instead of a precompiled handle as first argument. For each place the macros are invoked at, the regular expression is compiled only once and then cached (so for dynamic regexes the original function set with separate compilation will have to be used).


(assoc key assoclist cmp)

Returns pair with key from an assoclist. Uses optional cmp as a comparison function (equal by default).

(find func list)

Returns first element of list that for (func element) is true.

(foreach func list)

Calls func for each element of list. Returns last result.

(join sep list)

Concatenates a list of strings together with a separator in between elements.

(last list num)

Returns the last num (optional, default 1) CONSes of the list.

(list-index pred list)

Returns index of first item in list that for the lambda pred gives T, or nil.

(member needle list comp)

Returns the CONS of the list with the first occurrence of the element needle (that is, a tail of the list). Optionally, uses a custom comparison function (default equal).

(merge list1 list2 comp)

Returns the two lists merged (rearranging happens in place, so the original lists are destroyed). If the original lists were sorted, the result will be sorted too. The optional comp parameter is the comparison function; defaults to <.

(nthcdr n list)

Returns the nth cdr of the list, or in other words, the list element at offset n (beginning with 0).

(nth n list)

Macro for (car (nthcdr n list)).

(range n m step)

Provides a python-like range function. Only one argument is mandatory.

> (range 3)
(0 1 2)
> (range 3 8)
(3 4 5 6 7)
> (range 8 3 -2)
(8 6 4)

(reduce fn list [initial])

Combines all elements of a list using a function of two arguments. fn is called with the first two elements of the list, then with the result and the third element of the list, then with the result and the fourth element, etc. The final result is returned.

If initial is given, the first call is made as (fn initial (car list)) instead.

If list is nil and initial is supplied, initial is returned right away. If initial is omitted, the result is (fn) (called without arguments).

If list has exactly one element and initial is not given, the only element is returned without further processing.

(reverse list)

Returns the list reversed.

(sort list cmp)

Sorts and returns list (rearranging happens in place, so the original list is destroyed). The cmp parameter is the comparison function (optional, defaults to <).

> (sort (mapcar (lambda (n) (random 10)) (range 5)))
(0 2 5 6 8)
> (sort '(whydah customizable plushly abacus divider) >)


This include implements simple LISP-like structures inside the language, with macros. Single inheritance is supported. Instance data is stored in arrays.

(defstruct name | (name parent) slot1 slot2 ...)

Creates a number of macros and functions to access a structure (a container of named slots). If a parent is given, the new structure inherits the slots from all its ancestors.

> (defstruct person name age sex)
> (set 'bob (make-person "Bob" 28 'male))
> (list (person-name bob) (person-age bob) (person-sex bob))
("Bob" 28 MALE)

> (setf (person-age bob) 29)
> (list (person-name bob) (person-age bob) (person-sex bob))
("Bob" 29 MALE)

> (defstruct (programmer person) prowess)
> (set 'jim (make-programmer "Jim" 25 'male 1337))
> (list (person-name jim) (person-age jim) (programmer-sex jim) (programmer-prowess jim))
("Jim" 25 MALE 1337)

> (list (person-p bob) (programmer-p bob) (person-p jim) (programmer-p jim))
(T nil T T)

Default values for slots may be given. If an ancestor has already defined a slot with the same name, the definition (and possible default value) is overruled.

> (defstruct dog age gender (name 'fido))
> (set 'my-dog (make-dog 10 'male))
> (list (dog-name my-dog) (dog-age my-dog) (dog-gender my-dog))
> (set 'second-dog (make-dog 3 'female 'rex))
> (list (dog-name second-dog) (dog-age second-dog) (dog-gender second-dog))

Values may be supplied in key/value pairs (thus in any order):

> (set 'third-dog (make-dog :gender 'none-anymore :age 5))
> (list (dog-name third-dog) (dog-age third-dog) (dog-gender third-dog))

defstruct will define these macros and functions for each new structure:

(make-struct val1 val2 ...)

Returns a new instance. Initializes slots to the given values. Uninitialized slots for which a default value isn't specified are set to nil.

(struct-p obj)

This predicate returns T if obj is an instance either of struct or any of its descendants.

(struct-slot obj)

References a specific slot of a structure. Warning: no error or type checking is done, behavior is undefined if obj isn't an instance of the specific struct or any of the struct's descendants.


(defstruct xmlnode parent name attr children)

Struct for a node of an XML DOM. The fields mean:

The list of children is read-only, do not modify it except by the provided API.

(read-xml-tree fnstart fnend fntext)

Provides a "message tree" interface for read-xml. The three arguments are expected to be functions like this:

fnstart for the root node will be called with nil as context. For every child (including node close, plus child nodes and character data) will be called with the value returned by fnstart. Reading will stop when the root node is closed, or at EOF.

(xmldom-builder setter)

Returns a list of three functions with semantics good for read-xml-tree. These functions will build an XML DOM from the received data, and call (setter root-node) when finished.

(xmldom-traverse node fnstart fnend fntext)

Traverses the XML DOM tree from node. Dispatches messages to the three argument functions similarly to read-xml-tree.


Uses the XML API to parse an XML document from *input-stream*, builds a DOM tree and returns it.

(xmlnode-addchild parent node)

Adds a node to a parent node as a child. The node may as usual either be an xmlnode struct or a string.

(xmlnode-remove parent node)

Removes a node from the children of its parent. May be slow!

(print-xmldom node)

Pretty-prints an XML DOM to *output-stream*.

(dump-xmldom node)

Prints an XML DOM to *output-stream*, preserving the original white space.

(dommake NODE)

This is a quicker interface for making DOM trees. It interprets a nested list describing the desired tree. The format of this list is as follows.

NODE := "string"                       ;; character data
        | ( NODEDEF NODE1 NODE2 ...)   ;; XML DOM node

NODEDEF := "tagname"                             ;; <tagname>
           | ("tagname" ("attr" . "value")       ;; <tagname attr="value"
                        ("attr2" . "value") ...) ;;          attr2="value">

For example:

  (dommake '(("library" ("whose" . "of Congress") ("ghosts" . "3"))
              ("author" "S. Stallone")
              ("title" "Exploits of a Well-Oiled Man")))))

This will yield:

<library whose="of Congress" ghosts="3">
    <author>S. Stallone</author>
    <title>Exploits of a Well-Oiled Man</title>

(xmlnode-sform node)

Outputs a dommake-style nested list for a DOM node.

(xmlnode-text node)

Returns the full text of a node (all string children concatenated).