@begin(section)
@title(Index)

@b(kutils) is my personal utility library.

@begin(deflist)

@term(Source)
@begin(def)

The source code may be obtained from
@link[uri="https://github.com/kisom/kutils/"](Github).

@end(def)

@term(Setup and Usage)
@begin(def)

@c(kutils) requires
@link[uri="https://quicklisp.org/"](Quicklisp). The repository should
be cloned into the @c(local-projects) directory under the Quicklisp
home.

To use @b(kutils), either add it to the @c(:depends-on) section of
your project's @c(.asd), or @c(ql:quickload :kutils).

@end(def)

@term(License)
@begin(def)

@b(kutils) is released under the
@link[uri="https://raw.githubusercontent.com/kisom/kutils/master/LICENSE"](MIT)
license.

@end(def)
@end(deflist)

@end(section)


@begin(section)
@title(Overview)

What Lisp hacker doesn't have their own collection of useful tools and
idioms? This is the collection of tools I've been finding useful in
building new programs; some of these contain building blocks from
books on Lisp, and others I've written. It's probably of little use to
other people.

There are a few classes of utilities provided:

@begin(list)

@item(Those from Paul Graham's @u(On Lisp). I've collected those that
have actually ended up being used.)

@item(Those from Doug Hoyte's @u(Let Over Lambda); again, only those
that have actually been used are provided.)

@item(Hash-table related utilities.)

@item(Vector-related utilities.)

@item(Clojure-inspired utilities. I enjoyed working in Clojure, but
not enough to keep using it. These utilities are implementations of
some functions I found useful.)

@item(General purpose utilties that don't fit in elsewhere.)

@end(list)

@end(section)

@begin(section)
@title(On Lisp utilities)

@cl:with-package[name="kutils"](
@cl:doc(function mkstr)
@cl:doc(function symb)
@cl:doc(function group)
@cl:doc(function flatten)
@cl:doc(function compose)
)


@end(section)


@begin(section)
@title(Let Over Lambda utilities)

@cl:with-package[name="kutils"](
@cl:doc(macro defmacro!))

@end(section)


@begin(section)
@title(Miscellaneous utilities)

@begin(deflist)

@term(General)
@begin(def)
@cl:with-package[name="kutils"](
@cl:doc(macro assoc-val)
@cl:doc(function build-list)
@cl:doc(function cartprod2)
@code(@include[path=examples.lisp start=1 end=5]())
@cl:doc(function effector)
@cl:doc(function empty-or-nil-p)
@cl:doc(function macroexpand-n)
@cl:doc(function mksymb)
@cl:doc(function mkkw)
@cl:doc(function zip))
@end(def)

@term(Vector-related)
@begin(def)
@cl:with-package[name="kutils"](
@cl:doc(function new-vector)
@cl:doc(macro mapv)
@cl:doc(function build-vector)
@cl:doc(function extend-vector))
@end(def)

@term(Clojure-inspired functions)
@begin(def)

@cl:with-package[name="kutils"](
@cl:doc(function interpose)
@cl:doc(function take)
@cl:doc(function drop)
@cl:doc(function partial)
)
@end(def)

@end(deflist)
@end(section)


@begin(section)
@title(Hash table utilities)

@begin(deflist)

@term(Reader macro)

@begin(def)

The package has an optional reader macro that attempts to make
Clojure-like hash table literals in the reader. For example:

@code(@include[path=reader.lisp]())

@cl:with-package[name="kutils"](
@cl:doc(function enable-hash-table-reader))
@end(def)

@term(Table manipulation)
@begin(def)
@cl:with-package[name="kutils"](
@cl:doc(function hashkeys)
@cl:doc(macro sethash)
@cl:doc(function new-hash-table)
@cl:doc(function hash-table-to-alist)
@cl:doc(function copy-hash-table))
@end(def)

@term(@c(with-new-hash-table))
@begin(def)

@c(with-new-hash-table) is a convenience macro for creating a new
hash table and acting on it.

In the simplest case, it takes a single symbol and a body:

@begin(code)
@include[path=ht-example.lisp start=1 end=7]()
@end(code)

If more than one symbol is provided, the resulting hash tables
will be returned as an alist:

@begin(code)
@include[path=ht-example.lisp start=9 end=22]()
@end(code)

@cl:with-package[name="kutils"](
@cl:doc(macro with-new-hash-table))
@end(def)
@end(deflist)

@end(section)

@begin(section)
@title(Macros)

@begin(deflist)

@term(Let macros)
@begin(def)

These are macros that combine a @c(let) or @c(let*) form with a test
based on the results of the bindings. This is useful for reducing
common boilerplate where a let is used to perform some operations, and
some code should be executed based on the results of those bindings.

@cl:with-package[name="kutils"](
@cl:doc(macro condlet)
@cl:doc(macro condlet*)
@cl:doc(macro iflet)
@cl:doc(macro iflet*)
@cl:doc(macro unlesslet)
@cl:doc(macro unlesslet*)
@cl:doc(macro whenlet)
@cl:doc(macro whenlet*)
)

@end(def)

@end(deflist)

@end(section)

@begin(section)
@title(Symbol index)

Alphabetical list of all exported symbols.

@begin(list)

@item(@c(alist-to-hash-table) is a function defined in
@c(kutils-hash-tables.lisp), described in "Hash-table related
utilities".)

@item(@c(assoc-val) is a macro defined in @c(kutils.lisp), described
in "Miscellaneous utilities" under "General".)

@item(@c(build-list) is a function defined in @c(kutils.lisp),
described in "Miscellaneous utilities" under "General".)

@item(@c(build-vector) is a function defined in @c(kutils.lisp),
described in "Miscellaneous utilities" under "Vector-related".)

@item(@c(cartprod2) is a function defined in @c(kutils.lisp),
described in "Miscellaneous utilities" under "General".)

@item(@c(compose) is a function defined in @c(on.lisp), described in
"On Lisp utilities".)

@item(@c(condlet) is a macro defined in @c(macros.lisp), described in
"Macros".)

@item(@c(condlet*) is a macro defined in @c(macros.lisp), described in
"Macros".)

@item(@c(copy-hash-table) is a function defined in
@c(kutils-hash-tables.lisp), described in "Hash-table related
utilities".)

@item(@c(defmacro!) is a function defined in @c(lol.lisp), described
in "Let Over Lambda utilities".)

@item(@c(drop) is a function defined in @c(kutils.lisp), described in
"Miscellaneous utilities" under "Clojure-inspired functions".)

@item(@c(effector) is a function defined in @c(kutils.lisp),
described in "Miscellaneous utilities" under "General".)

@item(@c(empty-or-nil-p) is a function defined in @c(kutils.lisp),
described in "Miscellaneous utilities" under "General".)

@item(@c(enable-hash-table-reader) is a function defined in
@c(kutils-hash-tables.lisp), described in "Hash-table related
utilities.)

@item(@c(extend-vector) is a function defined in @c(kutils.lisp),
described in "Miscellaneous utilities" under "Vector-related".)

@item(@c(flatten) is a function defined in @c(on.lisp), described in
"On Lisp utilities".)

@item(@c(group) is a function defined in @c(kutils.lisp), described in
"On Lisp utilities".)

@item(@c(hash-table-to-alist) is a function defined in
@c(kutils-hash-tables.lisp), described in "Hash-table related
utilities".)

@item(@c(hashkeys) is a function defined in
@c(kutils-hash-tables.lisp), described in "Hash-table related
utilities".)

@item(@c(iflet) is a macro defined in @c(macros.lisp), described in
"Macros".)

@item(@c(iflet*) is a macro defined in @c(macros.lisp), described in
"Macros".)

@item(@c(interpose) is a function defined in @c(kutils.lisp),
described in "Miscellaneous utilities" under "Clojure-inspired
functions".)

@item(@c(macroexpand-n) is a function defined in @c(kutils.lisp),
described in "Miscellaneous utilities" under "General".)

@item(@c(mapv) is a macro defined in @c(kutils.lisp), described in
"Miscellaneous utilities" under "Vector-related".)

@item(@c(mkkw) is a function defined in @c(kutils.lisp), described in
"Miscellaneous utilities" under "General".)

@item(@c(mkstr) is a function defined in @c(on.lisp), described in "On
Lisp utilities".)

@item(@c(mksymb) is a function defined in @c(kutils.lisp), described
in "Miscellaneous utilities" under "General".)

@item(@c(new-hash-table) is a function defined in
@c(kutils-hash-tables.lisp), described in "Hash-table related
utilities".)

@item(@c(new-vector) is a function defined in @c(kutils.lisp),
described in "Miscellaneous utilities" under "Vector-related".)

@item(@c(partial) is a function defined in @c(kutils.lisp), described
in "Miscellaneous utilities" under "Clojure-inspired functions".)

@item(@c(sethash) is a macro defined in @c(kutils-hash-tables.lisp),
described in "Hash-table related utilities".)

@item(@c(symb) is a function defined in @c(on.lisp), described in "On
Lisp utilities".)

@item(@c(take) is a function defined in @c(kutils.lisp), described in
"Miscellaneous utilities" under "Clojure-inspired functions".)

@item(@c(unlesslet) is a macro defined in @c(macros.lisp), described in
"Macros".)

@item(@c(unlesslet*) is a macro defined in @c(macros.lisp), described in
"Macros".)

@item(@c(whenlet) is a macro defined in @c(macros.lisp), described in
"Macros".)

@item(@c(whenlet*) is a macro defined in @c(macros.lisp), described in
"Macros".)

@item(@c(with-new-hash-table) is a macro defined in
@c(kutils-hash-tables.lisp), described in "Hash-table related
utilities".)

@item(@c(zip) is a function defined in @c(kutils.lisp), described in
"Miscellaneous utilities" under "General".)

@end(list)
@end(section)

@begin(section)
@title(Alphabetical list)

Alphabetical documentation for all exported symbols.

@cl:with-package[name="kutils"](

@cl:doc(function alist-to-hash-table)
@cl:doc(macro assoc-val)
@cl:doc(function build-list)
@cl:doc(function build-vector)
@cl:doc(function cartprod2)
@cl:doc(function compose)
@cl:doc(macro condlet)
@cl:doc(macro condlet*)
@cl:doc(function copy-hash-table)
@cl:doc(macro defmacro!)
@cl:doc(function drop)
@cl:doc(function effector)
@cl:doc(function empty-or-nil-p)
@cl:doc(function enable-hash-table-reader)
@cl:doc(function extend-vector)
@cl:doc(function flatten)
@cl:doc(function group)
@cl:doc(function hash-table-to-alist)
@cl:doc(function hashkeys)
@cl:doc(macro iflet)
@cl:doc(macro iflet*)
@cl:doc(function interpose)
@cl:doc(function macroexpand-n)
@cl:doc(macro mapv)
@cl:doc(function mkkw)
@cl:doc(function mkstr)
@cl:doc(function mksymb)
@cl:doc(function new-hash-table)
@cl:doc(function new-vector)
@cl:doc(function partial)
@cl:doc(macro sethash)
@cl:doc(function symb)
@cl:doc(function take)
@cl:doc(macro unlesslet)
@cl:doc(macro unlesslet*)
@cl:doc(macro whenlet)
@cl:doc(macro whenlet*)
@cl:doc(macro with-new-hash-table)
@cl:doc(function zip))

@end(section)