538 lines
14 KiB
Plaintext
538 lines
14 KiB
Plaintext
@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.)
|
|
|
|
@iterm(@c(let)-based macros.)
|
|
|
|
@iterm(Macros that simplify common file operations.)
|
|
|
|
@item(Metaobject utilities.)
|
|
|
|
@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)
|
|
@cl:doc(macro with-gensyms)
|
|
)
|
|
|
|
|
|
@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 flip)
|
|
@code(@include[path="flip.lisp"]())
|
|
@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)
|
|
@cl:doc(function partition)
|
|
)
|
|
@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.
|
|
|
|
For example, from @c(kmop/kmop.lisp):
|
|
|
|
@code(@include[path="whenlet.lisp"]())
|
|
|
|
@cl:with-package[name="kutils"](
|
|
@cl:doc(macro condlet)
|
|
@cl:doc(macro condlet*)
|
|
@cl:doc(macro iflet)
|
|
@cl:doc(macro iflet*)
|
|
@cl:doc(macro orlet)
|
|
@code(@include[path="orlet.lisp"]())
|
|
@cl:doc(macro unlesslet)
|
|
@cl:doc(macro unlesslet*)
|
|
@cl:doc(macro whenlet)
|
|
@cl:doc(macro whenlet*)
|
|
)
|
|
|
|
@end(def)
|
|
|
|
@term(File macros)
|
|
@begin(def)
|
|
|
|
These macros abstract common operations on files.
|
|
|
|
@cl:with-package[name="kutils"](
|
|
@cl:doc(macro with-read-from-file)
|
|
@cl:doc(macro with-write-to-file)
|
|
)
|
|
|
|
The following two macros aren't yet able to be documented with
|
|
@link[uri="https://github.com/CommonDoc/codex"](Codex), as they are
|
|
defined using the @c(defmacro!) macro:
|
|
|
|
@code(
|
|
read-file-as-string (path &rest args
|
|
&key (direction nil directionp)
|
|
&allow-other-keys))
|
|
|
|
Read the contents of the file at @c(path) as a string. Any remaining
|
|
arguments are sent to @c(with-open-file).
|
|
|
|
@code(
|
|
with-string-output-to-file
|
|
((path &rest args &key (direction :output directionp)
|
|
&allow-other-keys)
|
|
&body body))
|
|
|
|
Evaluate @c(body), and call @c(mkstr) on the result. Write the
|
|
resulting string to @c(path). Any remaining arguments are sent to
|
|
@c(with-open-file).
|
|
|
|
@end(def)
|
|
|
|
@term(General)
|
|
|
|
@cl:with-package[name="kutils"](
|
|
@cl:doc(macro in))
|
|
|
|
@end(deflist)
|
|
|
|
@end(section)
|
|
|
|
@begin(section)
|
|
@title(Metaobject utilities)
|
|
|
|
The package @c(kutils-mop) contains utilities taking advantage of the
|
|
metaobject protocol.
|
|
|
|
The @c(make-instance-from-hash-table) function will attempt to create
|
|
an instance of an object from a hash table.
|
|
|
|
@cl:with-package[name="kutils-mop"](
|
|
@cl:doc(function make-instance-from-hash-table))
|
|
|
|
This is motivated by the fact that
|
|
@link[uri="http://quickdocs.org/yason/"](Yason) parses JSON as hash
|
|
tables; this function is used to facilitate rapidly parsing CLOS
|
|
objects from JSON.
|
|
|
|
For example, with the following @c(example.json)
|
|
|
|
@code(@include[path=example.json]())
|
|
|
|
the following code will produce an instance of the @c(class-d) class.
|
|
|
|
@code(@include[path=mop-table-demo.lisp]())
|
|
|
|
@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" under "Let macros".)
|
|
|
|
@item(@c(condlet*) is a macro defined in @c(macros.lisp), described in
|
|
"Macros" under "Let 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(flip) is a function defined in @c(kutils.lisp), described in
|
|
"Miscellaneous utilities" under "General".)
|
|
|
|
@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" under "Let macros".)
|
|
|
|
@item(@c(iflet*) is a macro defined in @c(macros.lisp), described in
|
|
"Macros" under "Let macros".)
|
|
|
|
@item(@c(in) is a macro defined in @c(macros.lisp), described in
|
|
"Macros" under "General".)
|
|
|
|
@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(make-instance-from-hash-table) is a function defined in the
|
|
@c(#:kutils-mop) package in @c(kmop/kmop.lisp), described in
|
|
"Metaobject utilities".)
|
|
|
|
@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(orlet) is a macro defined in @c(macros.lisp), described in
|
|
"Macros" under "Let macros".)
|
|
|
|
@item(@c(partial) is a function defined in @c(kutils.lisp), described
|
|
in "Miscellaneous utilities" under "Clojure-inspired functions".)
|
|
|
|
@item(@c(partition) is a function defined in @c(kutils.lisp), described
|
|
in "Miscellaneous utilities" under "Clojure-inspired functions".)
|
|
|
|
@item(@c(read-file-as-string) is a macro defined in @c(macros.lisp),
|
|
described in "Macros" under "File macros".)
|
|
|
|
@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" under "Let macros".)
|
|
|
|
@item(@c(unlesslet*) is a macro defined in @c(macros.lisp), described in
|
|
"Macros" under "Let macros".)
|
|
|
|
@item(@c(whenlet) is a macro defined in @c(macros.lisp), described in
|
|
"Macros" under "Let macros".)
|
|
|
|
@item(@c(whenlet*) is a macro defined in @c(macros.lisp), described in
|
|
"Macros" under "Let macros".)
|
|
|
|
@item(@c(with-gensyms) is a macro defined in @c(on.lisp), described in
|
|
"On Lisp utilities".)
|
|
|
|
@item(@c(with-new-hash-table) is a macro defined in
|
|
@c(kutils-hash-tables.lisp), described in "Hash-table related
|
|
utilities".)
|
|
|
|
@item(@c(with-read-from-file) is a macro defined in @c(macros.lisp),
|
|
described in "Macros" under "File macros".)
|
|
|
|
@item(@c(with-string-output-to-file) is a macro defined in @c(macros.lisp),
|
|
described in "Macros" under "File macros".)
|
|
|
|
@item(@c(with-write-to-file) is a macro defined in @c(macros.lisp),
|
|
described in "Macros" under "File macros".)
|
|
|
|
@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 flip)
|
|
@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(macro in)
|
|
@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(macro orlet)
|
|
@cl:doc(function partial)
|
|
@cl:doc(function partition)
|
|
@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-gensyms)
|
|
@cl:doc(macro with-new-hash-table)
|
|
@cl:doc(macro with-read-from-file)
|
|
@cl:doc(macro with-write-to-file)
|
|
@cl:doc(function zip))
|
|
|
|
The following functions cannot be automatically documented by Codex,
|
|
as they are defined using the @c(defmacro!) macro. Their description
|
|
is in the "Macro" section.
|
|
|
|
@begin(list)
|
|
@item(@c(read-file-as-string))
|
|
@item(@c(with-string-output-to-file))
|
|
@end(list)
|
|
@end(section)
|