Stutter Library

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

util

(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)))
3
> (list a b c)
(1 2 3)

(grab (symb1 symb2 ...) list)

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

(round number)

Returns number rounded to the nearest integer.

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))
0
1
2
nil

Supports return.

(gensym)

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

(lc-new)

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:

for symbol in list

Iterates over the list. Only here, a nested list of symbols can be given to peruse a complex list. For example:
> (loop for (a (b c)) in '((1 (2 3)) (4 (5 6))) do (println a b c))
1 2 3
4 5 6

for symbol on list

Iterates over the list, binding the full remainder of the list to the symbol each time.
> (loop for a on '(1 2 3) do (println a))
(1 2 3)
(2 3)
(3)

for symbol = expr

Assigns a computed value for each iteration. For example:
> (loop for x in '(1 2 3) for y = (* x 2) collect y)
(2 4 6)

for symbol from initial-value [to stop-value (inclusive) | below stop-value (exclusive) | downto lesser-stop-value (inclusive) | above lesser-stop-value (exclusive)] [by step-size]

Iterates over a progression. For example:
> (loop for x from 10 above 8 by 0.5 collect x)
(10 9.5 9.0 8.5)

Extra loop termination conditionals:

until test-expr

Exit loop when test-expr becomes true. For example:
> (loop for i from 1 until (> i 5) collect i)
(1 2 3 4 5)

while test-expr

Run loop while test-expr is true. For example:

> (loop for a from 1 for b from 10 by -1 while (> b a) collect (list a b))
((1 10) (2 9) (3 8) (4 7) (5 6))

Supported actions:

do expr

Executes expression. For example:
> (loop for a from 1 to 3 do (println a))
1
2
3

collect expr

Accumulates each value of expr in a list, which the loop returns. For example:
> (loop for a from 1 to 3 collect (* a 2))
(2 4 6)

append expr

Appends each value of expr (which has to evaluate to a list) into a list the loop will return. For example:
> (loop for a from 1 to 5 for b from 10 downto 6 append (list a b))
(1 10 2 9 3 8 4 7 5 6)

sum expr

Adds each value of expr together. The loop returns the result. For example:
> (loop for a from 1 to 100 sum a)
5050

maximize expr

The loop returns the greatest value expr evaluates to. For example:
> (loop for a from 0.0 to 6.28 by 0.01 maximize (sin a))
0.999999682932

minimize expr

The loop returns the smallest value expr evaluates to. For example:
> (loop for a from 0.0 to 6.28 by 0.01 minimize (sin a))
-0.999997146388

count test-expr

Count number of iterations when test-expr comes true. For example:
> (loop for a from 1 to 10 count (> a 5))
5

when test-expr action

Executes action each time test-expr comes true. For example:
> (loop for a from 1 to 10 when (< a 5) collect a)
(1 2 3 4)

if test-expr action [else action]

Executes action each time test-expr comes true. If it doesn't, and an else-branch is supplied, executes another action. For example:
> (loop for a from 1 to 10 if (> a 5) collect (* a 2) else collect (* a -2))
(-2 -4 -6 -8 -10 12 14 16 18 20)

thereis test-expr

The loop stops and returns T when test-expr comes true. If this never happens, it returns nil.

never test-expr

The loop stops and returns nil when test-expr comes true. If this never happens, it returns T.

always test-expr

The loop stops and returns nil when test-expr becomes false. If this never happens, it returns T.

return expr

The loop stops immediately and returns expr.

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



(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) >)
(WHYDAH PLUSHLY DIVIDER CUSTOMIZABLE ABACUS)


struct

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))
(FIDO 10 MALE)
> (set 'second-dog (make-dog 3 'female 'rex))
> (list (dog-name second-dog) (dog-age second-dog) (dog-gender second-dog))
(REX 3 FEMALE)


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))
(FIDO 5 NONE-ANYMORE)


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.

xml

(defstruct xmlnode parent name attr children)
Struct for a node of an XML DOM. The fields mean:

parent: parent node or nil if root
name: tag name
attr: assoclist of attributes
children: list of children (either these structs, or strings for character data)

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 context tagname attrlist)
(fnend context tagname)
(fntext context string)

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.

(read-xmldom)
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:
(print-xmldom
  (dommake '(("library" ("whose" . "of Congress") ("ghosts" . "3"))
             ("book"
              ("author" "S. Stallone")
              ("title" "Exploits of a Well-Oiled Man")))))

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


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