documentation

LICENCE

-Alexandria is public domain software: 
+Alexandria software and associated documentation are in the public
+domain:
 
   Authors dedicate this work to public domain, for the benefit of the
   public at large and to the detriment of the authors' heirs and

doc/Makefile

+.PHONY: clean html pdf
+
+clean:
+	rm -rf include *.aux *.cp *.fn *.fns *.ky *.log *.pg *.toc *.tp *.tps *.vr *.pdf *.html
+
+# Hook into the super sekrit texinfo generator in the SBCL tree -- this is just a quick way
+# to bootrap documentation for now.
+include:
+	sbcl --eval '(progn (require :asdf) (require :alexandria) (rename-package :alexandria :alexandria))' \
+	--eval '(load (merge-pathnames "doc/manual/docstrings" (posix-getenv "SBCL_SOURCE_ROOT")))' \
+	--eval '(sb-texinfo:generate-includes "include/" :alexandria)' \
+	--eval '(quit)'
+	mv include/fun-alexandria-type=.texinfo include/fun-alexandria-type-equal.texinfo
+
+pdf: include
+	texi2pdf alexandria.texinfo
+
+html: include
+	texi2html alexandria.texinfo

doc/alexandria.texinfo

+\input texinfo   @c -*-texinfo-*-
+@c %**start of header
+@setfilename alexandria.info
+@settitle Alexandria Manual
+@c %**end of header
+
+@settitle Alexandria Manual -- draft version
+
+@c for install-info
+@dircategory Software development
+@direntry
+* alexandria:           Common Lisp utilities.
+@end direntry
+
+@copying
+@quotation
+Alexandria software and associated documentation are in the public
+domain:
+
+  Authors dedicate this work to public domain, for the benefit of the
+  public at large and to the detriment of the authors' heirs and
+  successors. Authors intends this dedication to be an overt act of
+  relinquishment in perpetuity of all present and future rights under
+  copyright law, whether vested or contingent, in the work. Authors
+  understands that such relinquishment of all rights includes the
+  relinquishment of all rights to enforce (by lawsuit or otherwise)
+  those copyrights in the work.
+
+  Authors recognize that, once placed in the public domain, the work
+  may be freely reproduced, distributed, transmitted, used, modified,
+  built upon, or otherwise exploited by anyone for any purpose,
+  commercial or non-commercial, and in any way, including by methods
+  that have not yet been invented or conceived.
+
+In those legislations where public domain dedications are not
+recognized or possible, Alexandria is distributed under the following
+terms and conditions:
+
+  Permission is hereby granted, free of charge, to any person
+  obtaining a copy of this software and associated documentation files
+  (the "Software"), to deal in the Software without restriction,
+  including without limitation the rights to use, copy, modify, merge,
+  publish, distribute, sublicense, and/or sell copies of the Software,
+  and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+@end quotation
+@end copying
+
+@titlepage
+
+@title Alexandria Manual
+@subtitle draft version
+
+@c The following two commands start the copyright page.
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+
+@end titlepage
+
+@contents
+
+@ifnottex
+
+@menu
+* Hash Table Utilities::        
+* Higher Order Functions::      
+* List Manipulation::           
+* Sequence Manipulation::       
+* Macro Writing Utilities::     
+* Symbol Utilities::            
+* Array Utilities::             
+* Type Designator Manipulation::  
+* Mathematical Utilities::      
+@end menu
+
+@node Top
+@comment  node-name,  next,  previous,  up
+@top sbcl
+
+@insertcopying
+
+@menu
+@end menu
+
+@end ifnottex
+
+@node Hash Table Utilities
+@comment  node-name,  next,  previous,  up
+@section Hash Table Utilities
+
+@include include/fun-alexandria-copy-hash-table.texinfo
+@include include/fun-alexandria-maphash-keys.texinfo
+@include include/fun-alexandria-maphash-values.texinfo
+@include include/fun-alexandria-hash-table-keys.texinfo
+@include include/fun-alexandria-hash-table-values.texinfo
+@include include/fun-alexandria-hash-table-alist.texinfo
+@include include/fun-alexandria-hash-table-plist.texinfo
+@include include/fun-alexandria-alist-hash-table.texinfo
+@include include/fun-alexandria-plist-hash-table.texinfo
+
+@node Higher Order Functions
+@comment  node-name,  next,  previous,  up
+@section Higher Order Functions
+
+@include include/fun-alexandria-disjoin.texinfo
+@include include/fun-alexandria-conjoin.texinfo
+@include include/fun-alexandria-compose.texinfo
+@include include/fun-alexandria-multiple-value-compose.texinfo
+@include include/fun-alexandria-curry.texinfo
+@include include/fun-alexandria-rcurry.texinfo
+
+@node List Manipulation
+@comment  node-name,  next,  previous,  up
+@section List Manipulation
+
+@include include/type-alexandria-proper-list.texinfo
+@include include/type-alexandria-circular-list.texinfo
+@include include/macro-alexandria-appendf.texinfo
+@include include/fun-alexandria-circular-list.texinfo
+@include include/fun-alexandria-circular-list-p.texinfo
+@include include/fun-alexandria-circular-tree-p.texinfo
+@include include/fun-alexandria-proper-list-p.texinfo
+@include include/fun-alexandria-lastcar.texinfo
+@include include/fun-alexandria-make-circular-list.texinfo
+@include include/fun-alexandria-ensure-list.texinfo
+@include include/fun-alexandria-remove-keys.texinfo
+@include include/fun-alexandria-mappend.texinfo
+@include include/fun-alexandria-set-equal.texinfo
+
+@node Sequence Manipulation
+@comment  node-name,  next,  previous,  up
+@section Sequence Manipulation
+
+@include include/type-alexandria-proper-sequence.texinfo
+
+@include include/macro-alexandria-deletef.texinfo
+@include include/macro-alexandria-removef.texinfo
+
+@include include/fun-alexandria-rotate-left.texinfo
+@include include/fun-alexandria-rotate-right.texinfo
+@include include/fun-alexandria-suffle.texinfo
+@include include/fun-alexandria-random-elt.texinfo
+@include include/fun-alexandria-emptyp.texinfo
+@include include/fun-alexandria-sequence-of-length-p.texinfo
+@include include/fun-alexandria-copy-sequence.texinfo
+@include include/fun-alexandria-first-elt.texinfo
+@include include/fun-alexandria-last-elt.texinfo
+@include include/fun-alexandria-starts-with.texinfo
+@include include/fun-alexandria-ends-with.texinfo
+
+@node Macro Writing Utilities
+@comment  node-name,  next,  previous,  up
+@section Macro Writing Utilities
+
+@include include/macro-alexandria-with-unique-names.texinfo
+@include include/macro-alexandria-once-only.texinfo
+
+@node Symbol Utilities
+@comment  node-name,  next,  previous,  up
+@section Symbol Utilities
+
+@include include/fun-alexandria-ensure-symbol.texinfo
+@include include/fun-alexandria-format-symbol.texinfo
+@include include/fun-alexandria-make-keyword.texinfo
+@include include/fun-alexandria-make-gensym-list.texinfo
+
+@node Array Utilities
+@comment  node-name,  next,  previous,  up
+@section Array Utilities
+
+@include include/type-alexandria-array-index.texinfo
+@include include/fun-alexandria-copy-array.texinfo
+
+@node Type Designator Manipulation
+@comment  node-name,  next,  previous,  up
+@section Type Designator Manipulation
+
+@include include/fun-alexandria-of-type.texinfo
+@include include/fun-alexandria-type-equal.texinfo
+
+@node Mathematical Utilities
+@comment  node-name,  next,  previous,  up
+@section Mathematical Utilities
+
+@include include/macro-alexandria-maxf.texinfo
+@include include/macro-alexandria-minf.texinfo
+
+@include include/fun-alexandria-clamp.texinfo
+@include include/fun-alexandria-lerp.texinfo
+@include include/fun-alexandria-gaussian-random.texinfo
+@include include/fun-alexandria-iota.texinfo
+@include include/fun-alexandria-mean.texinfo
+@include include/fun-alexandria-median.texinfo
+@include include/fun-alexandria-variance.texinfo
+@include include/fun-alexandria-standard-deviation.texinfo
+
+@bye

lists.lisp

@@ -52,6 +52,9 @@ argument.")
          nil)))
 
 (deftype proper-list ()
+  "Type designator for proper lists. Implemented as a SATISFIES type, hence
+not recommended for performance intensive use. Main usefullness as a type
+designator of the expexted type in a TYPE-ERROR."
   `(satisfies proper-list-p))
 
 (defun lastcar (list)
@@ -76,7 +79,9 @@ proper list."
     (nconc cycle cycle)))
 
 (deftype circular-list ()
-  "A circular list."
+  "Type designator for circular lists. Implemented as a SATISFIES type, so not
+recommended for performance intensive use. Main usefullness as the
+expected-type designator of a TYPE-ERROR."
   `(satisfies circular-list-p))
 
 (defun ensure-list (list)

numbers.lisp

@@ -47,6 +47,7 @@ from STEP applied), each consequtive number being the sum of the previous one
 and STEP. START defaults to 0 and STEP to 0.
 
 Examples:
+
   (iota 4)                      => (0 1 2 3 4)
   (iota 3 :start 1 :step 1.0)   => (1.0 2.0 3.0)
   (iota 3 :start -1 :step -1/2) => (-1 -3/2 -2)

sequences.lisp

@@ -72,9 +72,10 @@ the result of calling REMOVE with ITEM, place, and the REMOVE-KEYWORDS.")
 the result of calling DELETE with ITEM, place, and the REMOVE-KEYWORDS.")
 
 (deftype proper-sequence ()
-  `(or vector 
-       proper-list
-       (and (not sequence) (not list) sequence)))
+  "Type designator for proper sequences, that is proper lists and sequences
+that are not lists."
+  `(or proper-list
+       (and (not list) sequence)))
 
 (defun emptyp (sequence)
   "Returns true if SEQUENCE is an empty sequence. Signals an error if SEQUENCE
@@ -85,7 +86,7 @@ is not a sequence"
 
 (defun sequence-of-length-p (sequence length)
   "Return true if SEQUENCE is a sequence of length LENGTH. Signals an error if
-SEQUENCE is not a sequence."
+SEQUENCE is not a sequence. Returns FALSE for circular lists."
   (etypecase sequence
     (null
      (zerop length))