├── sections ├── io │ ├── read-pred.md │ ├── pathname-pred.md │ ├── stream-pred.md │ ├── file.md │ ├── read-macro.md │ ├── stream.md │ ├── read.md │ ├── pathname.md │ ├── print.md │ └── format.md ├── package │ ├── pred.md │ ├── advanced.md │ ├── iterate.md │ └── main.md ├── string │ ├── pred.md │ ├── modify.md │ └── compare.md ├── plist-iteration.md ├── symbol │ ├── pred.md │ ├── advanced.md │ └── main.md ├── types │ ├── pred.md │ ├── declare.md │ └── main.md ├── vector │ ├── create.md │ ├── select.md │ └── modify.md ├── sequence │ ├── create.md │ ├── pred.md │ ├── sort.md │ ├── iteration.md │ ├── modify.md │ └── select.md ├── array │ ├── pred.md │ ├── select.md │ └── create.md ├── list │ ├── pred.md │ ├── create.md │ ├── iteration.md │ ├── select.md │ ├── tree.md │ ├── modify.md │ └── set.md ├── hashtable │ ├── pred.md │ ├── iteration.md │ ├── create.md │ ├── values.md │ └── advanced.md ├── system.md ├── math │ ├── compare.md │ ├── pred.md │ └── math.md ├── structure.md ├── do.md ├── bit-vector.md ├── alist.md ├── plist.md ├── equality.md ├── loop.md ├── compose.md ├── macro.md ├── conditions-control.md ├── function.md ├── variable.md ├── character.md ├── control-flow.md ├── datastructures.md └── iterate.md ├── .gitignore ├── pages ├── composition.md ├── control.md ├── structure.md ├── math.md ├── list-structure.md ├── stream.md ├── comparison.md ├── loop-iterate.md ├── types.md ├── compile.md ├── read.md ├── print.md ├── file.md ├── hash-table.md ├── package.md ├── vector.md ├── list.md ├── iteration.md ├── symbol.md ├── string.md ├── regular-expression.md ├── time.md ├── array.md └── object-system.md ├── Makefile └── README.md /sections/io/read-pred.md: -------------------------------------------------------------------------------- 1 | ### [readtablep] object => boolean 2 | -------------------------------------------------------------------------------- /sections/package/pred.md: -------------------------------------------------------------------------------- 1 | ### [packagep] object => boolean 2 | -------------------------------------------------------------------------------- /sections/string/pred.md: -------------------------------------------------------------------------------- 1 | ### [stringp] obj => boolean 2 | 3 | Test if an object is a [string]. 4 | -------------------------------------------------------------------------------- /sections/plist-iteration.md: -------------------------------------------------------------------------------- 1 | ### [alexandria:doplist] \(key val plist &optional values\) forms\* 2 | -------------------------------------------------------------------------------- /sections/symbol/pred.md: -------------------------------------------------------------------------------- 1 | ### [symbolp] object => boolean 2 | 3 | ### [keywordp] object => boolean 4 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | CNAME 2 | tmp/ 3 | html/ 4 | include/ 5 | *.html 6 | !build/* 7 | !sections/* 8 | !pages/* 9 | -------------------------------------------------------------------------------- /pages/composition.md: -------------------------------------------------------------------------------- 1 | ## Composition 2 | 3 | Functional composition. 4 | 5 | m4_include(../sections/compose.md) 6 | -------------------------------------------------------------------------------- /pages/control.md: -------------------------------------------------------------------------------- 1 | # Control Flow 2 | 3 | m4_include(../sections/control-flow.md) 4 | 5 | m4_include(../sections/conditions-control.md) 6 | -------------------------------------------------------------------------------- /sections/types/pred.md: -------------------------------------------------------------------------------- 1 | ### [typep] object type-specifier \[environment\] => boolean 2 | 3 | ### [subtypep] type-1 type-2 \[environment\] => subtype-p, valid-p 4 | -------------------------------------------------------------------------------- /pages/structure.md: -------------------------------------------------------------------------------- 1 | # Structures 2 | 3 | * [CLtL2: Structures](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node168.html) 4 | 5 | m4_include(../sections/structure.md) 6 | -------------------------------------------------------------------------------- /pages/math.md: -------------------------------------------------------------------------------- 1 | ## Numbers and Math 2 | 3 | m4_include(../sections/math/compare.md) 4 | 5 | m4_include(../sections/math/pred.md) 6 | 7 | m4_include(../sections/math/math.md) 8 | -------------------------------------------------------------------------------- /sections/io/pathname-pred.md: -------------------------------------------------------------------------------- 1 | ### [pathnamep] object => boolean 2 | 3 | ### [wild-pathname-p] pathname \[field-key\] => boolean 4 | 5 | ### [pathname-match-p] pathname wildcard => boolean 6 | -------------------------------------------------------------------------------- /sections/vector/create.md: -------------------------------------------------------------------------------- 1 | ### [vector] &rest objects\* => vector 2 | 3 | ### [svref] simple-vector index => element 4 | 5 | Accesses the element of *simple-vector* specified by *index*. 6 | -------------------------------------------------------------------------------- /sections/package/advanced.md: -------------------------------------------------------------------------------- 1 | ### [provide] module-name => implementation-dependent 2 | 3 | Deprecated. 4 | 5 | ### [require] module-name \[pathname-list\] => implementation-dependent 6 | 7 | Deprecated. 8 | -------------------------------------------------------------------------------- /sections/symbol/advanced.md: -------------------------------------------------------------------------------- 1 | ### [\*gensym-counter\*] 2 | 3 | A number used by [gensym] to construct the name of the next symbol. 4 | 5 | ### [gentemp] \[prefix package\] => new-symbol 6 | 7 | Deprecated. 8 | -------------------------------------------------------------------------------- /sections/sequence/create.md: -------------------------------------------------------------------------------- 1 | ### [make-sequence] result-type size &key initial-element => seq 2 | 3 | ~~~ 4 | (make-sequence '(vector double-float) 100 :initial-element 1d0) 5 | ~~~ 6 | 7 | ### [copy-seq] seq => copied-seq 8 | -------------------------------------------------------------------------------- /sections/io/stream-pred.md: -------------------------------------------------------------------------------- 1 | ### [streamp] object => boolean 2 | 3 | ### [input-stream-p] stream => boolean 4 | 5 | ### [output-stream-p] stream => boolean 6 | 7 | ### [interactive-stream-p] stream => boolean 8 | 9 | ### [open-stream-p] stream => boolean 10 | -------------------------------------------------------------------------------- /sections/array/pred.md: -------------------------------------------------------------------------------- 1 | ### [arrayp] 2 | 3 | ### [vectorp] 4 | 5 | ### [simple-vector-p] 6 | 7 | ### [bit-vector-p] 8 | 9 | ### [simple-bit-vector-p] 10 | 11 | ### [adjustable-array-p] 12 | 13 | ### [array-has-fill-pointer-p] 14 | 15 | ### [array-in-bounds-p] 16 | -------------------------------------------------------------------------------- /pages/list-structure.md: -------------------------------------------------------------------------------- 1 | # List Structures 2 | 3 | m4_include(../sections/list/set.md) 4 | 5 | m4_include(../sections/list/tree.md) 6 | 7 | m4_include(../sections/plist.md) 8 | 9 | m4_include(../sections/plist-iteration.md) 10 | 11 | m4_include(../sections/alist.md) 12 | -------------------------------------------------------------------------------- /sections/list/pred.md: -------------------------------------------------------------------------------- 1 | ### [listp] object => boolean 2 | 3 | ### [consp] object => boolean 4 | 5 | ### [atom] object => boolean 6 | 7 | Returns [T] if object is *not* a [cons]. 8 | 9 | ### [null] object => boolean 10 | 11 | ### [endp] object => boolean 12 | 13 | ### [tailp] x list = > boolean 14 | -------------------------------------------------------------------------------- /sections/hashtable/pred.md: -------------------------------------------------------------------------------- 1 | ### [hash-table-p] object => boolean 2 | 3 | Test if *object* is of type [hash-table]. 4 | 5 | ~~~ 6 | (setf ht (make-hash-table)) ;=> # 7 | (hash-table-p ht) ;=> T 8 | (hash-table-p '((:x . 7) (:y . 8))) ;=> NIL 9 | ~~~ 10 | -------------------------------------------------------------------------------- /sections/system.md: -------------------------------------------------------------------------------- 1 | In `example.asd`: 2 | 3 | ~~~ 4 | (asdf:defsystem :example 5 | :serial t ;load files in order 6 | :depends-on (:alexandria :cl-utilities) 7 | :components ((:file "package") 8 | (:file "example"))) 9 | ~~~ 10 | 11 | ~~~ 12 | `(ql:quickload :example)` 13 | ~~~ 14 | -------------------------------------------------------------------------------- /sections/array/select.md: -------------------------------------------------------------------------------- 1 | ### [aref] array &rest subscripts => element 2 | 3 | Access array elements. 4 | Related: [svref] ---Access index of a simple vector. 5 | 6 | ~~~ 7 | (setf a (make-array '(2 2) :initial-contents '((1 2) (3 4)))) 8 | (aref a 1 1) ;=> 4 9 | (setf (aref a 0 1) 99) ; a => #2A((1 99) (3 4)) 10 | ~~~ 11 | -------------------------------------------------------------------------------- /pages/stream.md: -------------------------------------------------------------------------------- 1 | # Streams 2 | 3 | * [HS: Introduction to Streams](http://www.lispworks.com/documentation/HyperSpec/Body/21_aa.htm) 4 | * [PCL: Other Kinds of I/O](http://gigamonkeys.com/book/files-and-file-io.html#other-kinds-of-io) 5 | 6 | m4_include(../sections/io/stream.md) 7 | 8 | ## Predicates 9 | 10 | m4_include(../sections/io/stream-pred.md) 11 | -------------------------------------------------------------------------------- /pages/comparison.md: -------------------------------------------------------------------------------- 1 | ## Equality 2 | 3 | m4_include(../sections/equality.md) 4 | 5 | ### [not] 6 | 7 | m4_include(../sections/math/compare.md) 8 | 9 | m4_include(../sections/string/compare.md) 10 | 11 | ## Predicates 12 | 13 | m4_include(../sections/math/pred.md) 14 | 15 | ### [boundp] 16 | 17 | ### [fboundp] 18 | 19 | ### [constantp] 20 | 21 | ### [functionp] 22 | -------------------------------------------------------------------------------- /pages/loop-iterate.md: -------------------------------------------------------------------------------- 1 | # Loop/Iterate 2 | 3 | m4_include(../sections/loop.md) 4 | 5 | # Iterate 6 | 7 | * [The Iterate Manual](http://common-lisp.net/project/iterate/doc/) 8 | * [Don't Loop, Iterate](http://common-lisp.net/project/iterate/doc/Don_0027t-Loop-Iterate.html) 9 | 10 | ~~~ 11 | (ql:quickload :iterate) 12 | ~~~ 13 | 14 | m4_include(../sections/iterate.md) 15 | -------------------------------------------------------------------------------- /sections/math/compare.md: -------------------------------------------------------------------------------- 1 | ### [=] &rest numbers\* => boolean 2 | 3 | Returns [t] if all numbers are the same in value, otherwise [nil]. 4 | 5 | ~~~ 6 | (= 6 6 6) ;=> T 7 | ~~~ 8 | 9 | ### [/=] &rest numbers\* => boolean 10 | 11 | ### [>] &rest numbers\* => boolean 12 | 13 | ### [>=] &rest numbers\* => boolean 14 | 15 | ### [<] &rest numbers\* => boolean 16 | 17 | ### [<=] &rest numbers\* => boolean 18 | -------------------------------------------------------------------------------- /pages/types.md: -------------------------------------------------------------------------------- 1 | # Types 2 | 3 | * [HS: Types and Classes](http://www.lispworks.com/documentation/HyperSpec/Body/04_.htm) 4 | * [Common Lisp Type Hierarchy](http://sellout.github.io/2012/03/03/common-lisp-type-hierarchy/) 5 | 6 | m4_include(../sections/types/main.md) 7 | 8 | ## Predicates 9 | 10 | m4_include(../sections/types/pred.md) 11 | 12 | # Declarations 13 | 14 | m4_include(../sections/types/declare.md) 15 | -------------------------------------------------------------------------------- /sections/package/iterate.md: -------------------------------------------------------------------------------- 1 | ### [do-symbols] \(var \[package \[result-form\]\]\) declaration\* \{tag | statement\}\* => result 2 | 3 | ### [do-external-symbols] \(var \[package \[result-form\]\]\) declaration\* \{tag | statement\}\* => result 4 | 5 | ### [do-all-symbols] \(var \[result-form\]\) declaration\* \{tag | statement\}\* => result 6 | 7 | ### [with-package-iterator] \(name package-list-form &rest symbol-types\) declaration\* form\* => result 8 | -------------------------------------------------------------------------------- /sections/types/declare.md: -------------------------------------------------------------------------------- 1 | ### [proclaim] 2 | 3 | ### [declaim] 4 | 5 | ### [declare] 6 | 7 | ### [ignore] 8 | 9 | ### [ignorable] 10 | 11 | ### [dynamic-extent] 12 | 13 | ### [type] 14 | 15 | ### [ftype] 16 | 17 | ### [inline] 18 | 19 | ### [notinline] 20 | 21 | ### [declaration] 22 | 23 | ### [optimize] 24 | 25 | ### [special] 26 | 27 | ### [locally] 28 | 29 | ### [the] 30 | 31 | ### [special-operator-p] 32 | 33 | ### [constantp] 34 | -------------------------------------------------------------------------------- /pages/compile.md: -------------------------------------------------------------------------------- 1 | # Compilation 2 | 3 | ### [compile] 4 | 5 | ### [eval] 6 | 7 | ### [eval-when] 8 | 9 | ### [load-time-value] 10 | 11 | ### [quote] 12 | 13 | ### [compiler-macro-function] 14 | 15 | ### [define-compiler-macro] 16 | 17 | ### [defmacro] 18 | 19 | ### [macro-function] 20 | 21 | ### [macroexpand] 22 | 23 | ### [macroexpand-1] 24 | 25 | ### [define-symbol-macro] 26 | 27 | ### [symbol-macrolet] 28 | 29 | ### [*\macroexpand-hook\*] 30 | -------------------------------------------------------------------------------- /pages/read.md: -------------------------------------------------------------------------------- 1 | # Read 2 | 3 | m4_include(../sections/io/read.md) 4 | 5 | # Read Macros 6 | 7 | * [HS: Reader Concepts](http://www.lispworks.com/documentation/HyperSpec/Body/23_a.htm) 8 | * [OL: Read-Macros](http://dunsmor.com/lisp/onlisp/onlisp_21.html) 9 | * [LoL: Read Macros](http://letoverlambda.com/index.cl/guest/chap4.html) 10 | 11 | m4_include(../sections/io/read-macro.md) 12 | 13 | ## Predicates 14 | 15 | m4_include(../sections/io/read-pred.md) 16 | -------------------------------------------------------------------------------- /sections/vector/select.md: -------------------------------------------------------------------------------- 1 | ### [svref] simple-vector index => element 2 | 3 | Accesses the element of *simple-vector* specified by *index*. 4 | 5 | ### [fill-pointer] vector => fill-pointer 6 | 7 | Accesses the fill pointer of *vector*. 8 | 9 | ~~~ 10 | (setf arr (make-array 8 :fill-pointer 4)) ;=> #(NIL NIL NIL NIL) 11 | (fill-pointer arr) ;=> 4 12 | (vector-push 'a arr) 13 | (fill-pointer arr) ;=> 5 14 | ~~~ 15 | -------------------------------------------------------------------------------- /pages/print.md: -------------------------------------------------------------------------------- 1 | # Output 2 | 3 | * [CLtL2: Output Functions](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node197.html) 4 | 5 | ## Print 6 | 7 | m4_include(../sections/io/print.md) 8 | 9 | ## Format 10 | 11 | * [HyperSpec: Formatted Output](http://www.lispworks.com/documentation/HyperSpec/Body/22_c.htm) 12 | * [CLtL2: Formatted Output to Character Streams](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node200.html) 13 | * [PCL: A Few FORMAT Recipes](http://www.gigamonkeys.com/book/a-few-format-recipes.html) 14 | 15 | m4_include(../sections/io/format.md) 16 | -------------------------------------------------------------------------------- /sections/math/pred.md: -------------------------------------------------------------------------------- 1 | ### [zerop] number => boolean 2 | 3 | Returns [t] if *number* is zero ([integer], [float], or [complex]); otherwise [nil]. 4 | 5 | ### [plusp] real => boolean 6 | 7 | ### [minusp] real => boolean 8 | 9 | ### [evenp] integer => boolean 10 | 11 | ### [oddp] integer => boolean 12 | 13 | ### [numberp] object => boolean 14 | 15 | ### [realp] object => boolean 16 | 17 | ### [rationalp] object => boolean 18 | 19 | ### [floatp] object => boolean 20 | 21 | ### [integerp] object => boolean 22 | 23 | ### [complexp] object => boolean 24 | 25 | ### [random-state-p] object => boolean 26 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | IN_DIR=./pages 2 | OUT_DIR=./html 3 | 4 | doc: clean html index 5 | 6 | all: ref doc 7 | 8 | html: 9 | bash ./build/docgen.sh $(IN_DIR) $(OUT_DIR) 10 | 11 | ref: 12 | bash ./build/ref/hyperspec.sh 13 | phantomjs ./build/ref/alexandria.js 14 | phantomjs ./build/ref/cl-ppcre.js 15 | phantomjs ./build/ref/iterate.js 16 | 17 | index: 18 | phantomjs ./build/search-index.js $(OUT_DIR)/* > $(OUT_DIR)/search-index.json 19 | 20 | clean: 21 | rm -rf $(OUT_DIR) 22 | 23 | style: 24 | rm -rf $(OUT_DIR)/include 25 | cp -a ./build/include $(OUT_DIR) 26 | 27 | deploy: 28 | bash ./build/deploy.sh $(OUT_DIR) 29 | -------------------------------------------------------------------------------- /sections/array/create.md: -------------------------------------------------------------------------------- 1 | ### [make-array] dims &key type initial-element initial-contents adjustable fill-pointer displaced-to displaced-index-offset => new-array 2 | 3 | ~~~ 4 | (make-array '(2 3)) ;=> #2A((0 0 0) (0 0 0)) 5 | (make-array 5 :fill-pointer 0 :adjustable t :element-type 'character) ;=> "" 6 | ~~~ 7 | 8 | ### [adjust-array] array new-dims &key type initial-element initial-contents fill-pointer displaced-to displaced-index-offset => adjusted-array 9 | 10 | ### [alexandria:copy-array] array &key element-type fill-pointer adjustable => new-array 11 | 12 | Returns an undisplaced copy of *array*, with same 13 | fill-pointer and adjustability as the original. 14 | -------------------------------------------------------------------------------- /pages/file.md: -------------------------------------------------------------------------------- 1 | # Files 2 | 3 | * [HS: File System Concepts](http://www.lispworks.com/documentation/HyperSpec/Body/20_a.htm) 4 | * [PCL: Files and File I/O](http://www.gigamonkeys.com/book/files-and-file-io.html) 5 | 6 | m4_include(../sections/io/file.md) 7 | 8 | # Pathnames 9 | 10 | * [PCL: Files and File I/O: Filenames](http://www.gigamonkeys.com/book/files-and-file-io.html#filenames) 11 | * [PCL: A Portable Pathname Library](http://www.gigamonkeys.com/book/practical-a-portable-pathname-library.html) 12 | * [CL-FAD](http://weitz.de/cl-fad/) 13 | 14 | m4_include(../sections/io/pathname.md) 15 | 16 | ## Predicates 17 | 18 | m4_include(../sections/io/pathname-pred.md) 19 | -------------------------------------------------------------------------------- /pages/hash-table.md: -------------------------------------------------------------------------------- 1 | # Hash-Tables 2 | 3 | * [HS: Hash-Table Operations](http://www.lispworks.com/documentation/HyperSpec/Body/18_aa.htm) 4 | * [PCL: Collections: Hash Tables](http://gigamonkeys.com/book/collections.html#hash-tables) 5 | * [CLtL2: Hash Tables](https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node154.html) 6 | 7 | ## Create 8 | 9 | m4_include(../sections/hashtable/create.md) 10 | 11 | ## Predicates 12 | 13 | m4_include(../sections/hashtable/pred.md) 14 | 15 | ## Values 16 | 17 | m4_include(../sections/hashtable/values.md) 18 | 19 | ## Iteration 20 | 21 | m4_include(../sections/hashtable/iteration.md) 22 | 23 | ## Advanced 24 | 25 | m4_include(../sections/hashtable/advanced.md) 26 | -------------------------------------------------------------------------------- /sections/io/file.md: -------------------------------------------------------------------------------- 1 | ### [directory] pathspec &key => pathnames 2 | 3 | ### [probe-file] pathspec => truename 4 | 5 | ### [ensure-directories-exist] pathspec \[:verbose\] => pathspec, created 6 | 7 | ### [truename] filespec => truename 8 | 9 | ### [file-author] pathspec => author 10 | 11 | ### [file-write-date] pathspec => date 12 | 13 | ### [rename-file] filespec new-name => defaulted-new-name, old-truename, new-truename 14 | 15 | ### [delete-file] filespec => t 16 | 17 | ### [file-length] 18 | 19 | ### [file-position] 20 | 21 | ### [file-string-length] 22 | 23 | ### [with-open-file] 24 | 25 | ### [file-error-pathname] condition => pathspec 26 | 27 | ### [alexandria:read-file-into-string] pathname \[:buffer-size :external-format\] 28 | 29 | ### [alexandria:read-file-into-byte-vector] pathname 30 | -------------------------------------------------------------------------------- /sections/symbol/main.md: -------------------------------------------------------------------------------- 1 | ### [make-symbol] name => new-symbol 2 | 3 | ### [copy-symbol] symbol \[copy-properties\] => new-symbol 4 | 5 | ### [gensym] \[name\] => new-symbol 6 | 7 | Uses [\*gensym-counter\*] 8 | 9 | ~~~ 10 | (gensym) ;=> #:G1123 (value of *gensym-counter*) 11 | (gensym "name") ;=> #:|name1124| 12 | (gensym 99) ;=> #:G99 13 | ~~~ 14 | 15 | ### [symbol-function] symbol => contents 16 | 17 | ### [symbol-name] symbol => name 18 | 19 | ### [symbol-package] symbol => contents 20 | 21 | ### [symbol-plist] symbol => plist 22 | 23 | ### [symbol-value] symbol => value 24 | 25 | ### [get] symbol indicator \[default\] => value 26 | 27 | ### [set] symbol value => value 28 | 29 | ### [remprop] symbol indicator => boolean 30 | 31 | ### [boundp] symbol => boolean 32 | 33 | ### [makunbound] symbol => symbol 34 | -------------------------------------------------------------------------------- /sections/vector/modify.md: -------------------------------------------------------------------------------- 1 | ### [vector-push] new-element vector => index 2 | 3 | ~~~ 4 | (setf v (make-array 2 :fill-pointer 0)) ;=> #() 5 | (vector-push 'a v) ;=> 0 [v => #(A)] 6 | (vector-push 'b v) ;=> 1 [v => #(A B)] 7 | (vector-push 'c v) ;=> NIL [v => #(A B)] 8 | ~~~ 9 | 10 | ### [vector-push-extend] new-element vector \[extension\] => index 11 | 12 | ~~~ 13 | (setf v (make-array 2 :fill-pointer 0 :adjustable t) ;=> #() 14 | (vector-push 'a v) ;=> 0 [v => #(A)] 15 | (vector-push 'b v) ;=> 1 [v => #(A B)] 16 | (vector-push-extend 'c v) ;=> 2 [v => #(A B C)] 17 | ~~~ 18 | 19 | ### [vector-pop] 20 | 21 | Decreases the fill pointer of vector by one, and retrieves the element of vector that is designated by the new fill pointer. 22 | -------------------------------------------------------------------------------- /sections/structure.md: -------------------------------------------------------------------------------- 1 | ### [defstruct] structure-name \[slot-options\*\] \[doc\] => structure-name 2 | 3 | Defines a named structured type, with named slots as 4 | specified by the *slot-options*. Implictly defines 5 | a constructor function, slot accessors, and convenience 6 | functions for the structure: `make-[struct]`, `[struct]-p`, 7 | `copy-[struct]`, `[struct]-[slotname]`. 8 | 9 | ~~~ 10 | (defstruct point 11 | x 12 | (y 10)) 13 | 14 | (setf pt (make-point :x 5)) ;=> #S(POINT :X 5 :Y 10) 15 | (point-y pt) ;=> 10 16 | (setf (point-y pt) 20) 17 | (point-p pt) ;=> T 18 | (typeof pt 'point) ;=> T 19 | (copy-point pt) ;=> #S(POINT :X 5 :Y 20) 20 | ~~~ 21 | 22 | ### [copy-structure] structure => copy 23 | 24 | Returns a *copy* of the *structure*. Only the structure 25 | itself is copied; not the values of the slots. 26 | -------------------------------------------------------------------------------- /sections/io/read-macro.md: -------------------------------------------------------------------------------- 1 | ### [\*readtable\*] = current-readtable 2 | 3 | Controls the parsing behavior of the reader, and can also 4 | influence the printer. 5 | 6 | ### [copy-readtable] \[from-readtable to-readtable\] => readtable 7 | 8 | ### [make-dispatch-macro-character] char \[non-terminating-p readtable\] => t 9 | 10 | ### [readtable-case] readtable => mode 11 | 12 | `setf`able. 13 | 14 | ### [get-dispatch-macro-character] disp-char sub-char \[readtable\] => function 15 | 16 | ### [set-dispatch-macro-character] disp-char sub-char new-function \[readtable\] => t 17 | 18 | ### [get-macro-character] char \[readtable\] => function, non-terminating-p 19 | 20 | ### [set-macro-character] char new-function \[non-terminating-p readtable\] => t 21 | 22 | ### [set-syntax-from-char] to-char from-char \[to-readtable from-readtable\] => t 23 | 24 | ### [with-standard-io-syntax] form\* => result 25 | -------------------------------------------------------------------------------- /pages/package.md: -------------------------------------------------------------------------------- 1 | # Symbols 2 | 3 | m4_include(../sections/symbol/main.md) 4 | 5 | ## Predicates 6 | 7 | m4_include(../sections/symbol/pred.md) 8 | 9 | ## Advanced 10 | 11 | m4_include(../sections/symbol/advanced.md) 12 | 13 | 14 | # Packages 15 | 16 | * [HS: Introduction to Packages](http://www.lispworks.com/documentation/HyperSpec/Body/11_aa.htm) 17 | * [PCL: Programming in the Large: Packages and Symbols](http://www.gigamonkeys.com/book/programming-in-the-large-packages-and-symbols.html) 18 | 19 | ## Standard Packages 20 | 21 | * `common-lisp` 22 | * `common-lisp-user` 23 | * `keyword` 24 | 25 | m4_include(../sections/package/main.md) 26 | 27 | ## Predicates 28 | 29 | m4_include(../sections/package/pred.md) 30 | 31 | ## Iteration 32 | 33 | m4_include(../sections/package/iterate.md) 34 | 35 | ## Advanced 36 | 37 | m4_include(../sections/package/advanced.md) 38 | 39 | 40 | # Systems 41 | 42 | m4_include(../sections/system.md) 43 | -------------------------------------------------------------------------------- /sections/list/create.md: -------------------------------------------------------------------------------- 1 | ## Create 2 | 3 | ### [cons] x y => cons 4 | 5 | ~~~ 6 | (cons 1 2) ;=> (1 . 2) 7 | (cons 1 '(2 3)) ;=> (1 2 3) 8 | ~~~ 9 | 10 | ### [list] objects\* => list 11 | 12 | Returns a list containing *objects*. 13 | 14 | ~~~ 15 | (list 1 2 3 4) ;=> (1 2 3 4) 16 | ~~~ 17 | 18 | ### [list\*] objects\* list => list 19 | 20 | Returns a list containing *objects* with the last argument 21 | becoming the [cdr] of the last [cons] constructed. 22 | 23 | ~~~ 24 | (list* 'a 'b) ;=> (A . B) 25 | (list* 1 2 '(3 4)) ;=> (1 2 3 4) 26 | ~~~ 27 | 28 | ### [make-list] size &key initial-element => list 29 | 30 | Returns a list of length *size*. 31 | 32 | ~~~ 33 | (make-list 3) ;=> (NIL NIL NIL) 34 | (make-list 2 :initial-element 'a) ;=> (A A) 35 | ~~~ 36 | 37 | ### [copy-list] list => copy 38 | 39 | Returns a copy of *list*. Only the list structure is copied; 40 | the elements of the resulting list are the same as the 41 | corresponding elements of the given list. 42 | -------------------------------------------------------------------------------- /pages/vector.md: -------------------------------------------------------------------------------- 1 | # Vectors 2 | 3 | A vector is a basic integer-indexed collection, a 4 | one-dimensional [array]. Vectors and lists are collectively 5 | considered to be *sequences*. 6 | 7 | * [CLtL2: Vectors](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node30.html) 8 | * [PCL: Vectors](http://www.gigamonkeys.com/book/collections.html#vectors) 9 | 10 | ## Create 11 | 12 | ### [vector] &rest objects\* => vector 13 | 14 | m4_include(../sections/array/create.md) 15 | 16 | ## Select 17 | 18 | m4_include(../sections/vector/select.md) 19 | 20 | m4_include(../sections/array/select.md) 21 | 22 | m4_include(../sections/sequence/select.md) 23 | 24 | ## Modify 25 | 26 | m4_include(../sections/vector/modify.md) 27 | 28 | m4_include(../sections/sequence/modify.md) 29 | 30 | 31 | ## Sort 32 | 33 | m4_include(../sections/sequence/sort.md) 34 | 35 | 36 | ## Predicates 37 | 38 | m4_include(../sections/sequence/pred.md) 39 | 40 | m4_include(../sections/array/pred.md) 41 | 42 | ## Iteration 43 | 44 | m4_include(../sections/sequence/iteration.md) 45 | -------------------------------------------------------------------------------- /sections/sequence/pred.md: -------------------------------------------------------------------------------- 1 | ### [some] fn seq &rest seqs\* => result 2 | 3 | Returns the first non-[nil] value which is returned by an 4 | invocation of the predicate *fn*. 5 | 6 | ~~~ 7 | (some #'evenp '(1 2 3 4)) ;=> T 8 | (some #'1+ '(10 20 30 40)) ;=> 11 9 | (some #'numberp '(a b c)) ;=> NIL 10 | ~~~ 11 | 12 | ### [every] fn seq &rest seqs\* => boolean 13 | 14 | Returns [nil] as soon as any invocation of the predicate 15 | *fn* returns [nil]. 16 | 17 | ~~~ 18 | (every #'numberp '(1 2 3 4)) ;=> T 19 | (every #'evenp '(1 2 3 4)) ;=> NIL 20 | ~~~ 21 | 22 | ### [notevery] fn seq &rest seqs\* => boolean 23 | 24 | Returns [t] as soon as any invocation of predicate *fn* 25 | returns [nil]. 26 | 27 | ~~~ 28 | (notevery #'numberp '(1 2 3 4)) ;=> NIL 29 | (notevery #'evenp '(1 2 3 4)) ;=> T 30 | ~~~ 31 | 32 | ### [notany] fn seq &rest seqs\* => boolean 33 | 34 | Returns [nil] as soon as any invocation of predicate *fn* 35 | returns [t]. 36 | 37 | ~~~ 38 | (notany #'numberp '(1 2 3 4)) ;=> NIL 39 | (notany #'evenp '(1 2 3 4)) ;=> NIL 40 | ~~~ 41 | -------------------------------------------------------------------------------- /sections/io/stream.md: -------------------------------------------------------------------------------- 1 | ### [\*debug-io\*] 2 | 3 | ### [\*error-output\*] 4 | 5 | ### [\*query-io\*] 6 | 7 | ### [\*standard-input\*] 8 | 9 | ### [\*standard-output\*] 10 | 11 | ### [\*trace-output\*] 12 | 13 | ### [\*terminal-io\*] 14 | 15 | ### [stream-element-type] 16 | 17 | ### [open] 18 | 19 | ### [stream-external-format] 20 | 21 | ### [close] 22 | 23 | ### [with-open-stream] 24 | 25 | ### [listen] 26 | 27 | ### [make-synonym-stream] 28 | 29 | ### [synonym-stream-symbol] 30 | 31 | ### [broadcast-stream-streams] 32 | 33 | ### [make-broadcast-stream] 34 | 35 | ### [make-two-way-stream] 36 | 37 | ### [two-way-stream-input-stream] 38 | 39 | ### [two-way-stream-output-stream] 40 | 41 | ### [echo-stream-input-stream] 42 | 43 | ### [echo-stream-output-stream] 44 | 45 | ### [make-echo-stream] 46 | 47 | ### [concatenated-stream-streams] 48 | 49 | ### [make-concatenated-stream] 50 | 51 | ### [get-output-stream-string] 52 | 53 | ### [make-string-input-stream] 54 | 55 | ### [make-string-output-stream] 56 | 57 | ### [stream-error-stream] 58 | -------------------------------------------------------------------------------- /sections/string/modify.md: -------------------------------------------------------------------------------- 1 | ### [string-trim] chars str => new-str 2 | 3 | Returns a substring of *str*, with all characters in *chars* 4 | stripped off the beginning and end. 5 | 6 | ~~~ 7 | (string-trim "abc" "abcaakaaakabcaaa") ;=> "kaaak" 8 | (string-trim '(#\Space #\Tab #\Newline) " garbanzo beans ") ;=> "garbanzo beans" 9 | (string-trim " (*)" " ( *three (silly) words* ) ") ;=> "three (silly) words" 10 | ~~~ 11 | 12 | ### [string-left-trim] chars str => new-str 13 | 14 | ~~~ 15 | (string-left-trim "abc" "labcabcabc") ;=> "labcabcabc" 16 | (string-left-trim " (*)" " ( *three (silly) words* ) ") ;=> "three (silly) words* ) " 17 | ~~~ 18 | 19 | ### [string-right-trim] chars str => new-str 20 | 21 | ~~~ 22 | (string-right-trim " (*)" " ( *three (silly) words* ) ") ;=> " ( *three (silly) words" 23 | ~~~ 24 | 25 | ### [string-upcase] str &key start end => new-str 26 | 27 | Also [nstring-upcase] 28 | 29 | ### [string-downcase] str &key start end => new-str 30 | 31 | Also [nstring-downcase] 32 | 33 | ### [string-capitalize] str &key start end => new-str 34 | 35 | Also [nstring-capitalize] 36 | -------------------------------------------------------------------------------- /pages/list.md: -------------------------------------------------------------------------------- 1 | # Lists 2 | 3 | * [PCL: List Processing](http://www.gigamonkeys.com/book/they-called-it-lisp-for-a-reason-list-processing.html) 4 | 5 | The type [sequence] encompasses both lists and vectors 6 | (one-dimensional arrays). 7 | 8 | * [HyperSpec: Sequences Dictionary](http://www.lispworks.com/documentation/HyperSpec/Body/c_sequen.htm) 9 | * [PCL: Ch 11. Collections](http://www.gigamonkeys.com/book/collections.html) 10 | * [CLtL2: Ch 14. Sequences](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node141.html) 11 | 12 | m4_include(../sections/list/create.md) 13 | 14 | ## Select 15 | 16 | m4_include(../sections/list/select.md) 17 | 18 | m4_include(../sections/sequence/select.md) 19 | 20 | ## Modify 21 | 22 | m4_include(../sections/list/modify.md) 23 | 24 | m4_include(../sections/sequence/modify.md) 25 | 26 | m4_include(../sections/sequence/sort.md) 27 | 28 | ## Predicates 29 | 30 | m4_include(../sections/list/pred.md) 31 | 32 | m4_include(../sections/sequence/pred.md) 33 | 34 | ## Iteration 35 | 36 | m4_include(../sections/list/iteration.md) 37 | 38 | m4_include(../sections/sequence/iteration.md) 39 | -------------------------------------------------------------------------------- /pages/iteration.md: -------------------------------------------------------------------------------- 1 | ## Do Forms 2 | 3 | m4_include(../sections/do.md) 4 | 5 | ## Map/Reduce/Filter 6 | 7 | m4_include(../sections/list/iteration.md) 8 | 9 | m4_include(../sections/sequence/iteration.md) 10 | 11 | m4_include(../sections/plist-iteration.md) 12 | 13 | ## Hash-Tables 14 | 15 | m4_include(../sections/hashtable/iteration.md) 16 | 17 | ## Recursion 18 | 19 | Tesing if a list contains an element using tail-recursion: 20 | 21 | ~~~ 22 | (defun our-member (obj lst) 23 | (if (null lst) ;finished if empty list, return nil 24 | nil 25 | (if (eql (car lst) obj) ;if obj is first list element, return list 26 | lst 27 | (our-member obj (cdr lst))))) ;else, test against rest of list 28 | ~~~ 29 | 30 | Using an accumulator: 31 | 32 | ~~~ 33 | (defun fac (x) 34 | (labels ((fac2 (x acc) ;function takes current step and accumulated results 35 | (if (= x 0) 36 | acc ;if done, return accumulated results list 37 | (fac2 (- x 1) (* acc x))))) ;else, call again with stepped down arg and accumulation 38 | (fac2 x 1))) ;initial call to start 39 | ~~~ 40 | -------------------------------------------------------------------------------- /sections/do.md: -------------------------------------------------------------------------------- 1 | ### [do] ((var \[start \[step\]\])\*) (stop result\*) form\* => result\* 2 | 3 | Iterate over a group of statements while a test condition 4 | holds. Variables are bound within the iteration and stepped 5 | in parallel. 6 | 7 | Using [do\*] causes the variable bindings and steppings to be 8 | performed sequentially rather than in parallel. 9 | 10 | ~~~ 11 | (do ((i 0 (1+ i))) ;init to 0, step 1 12 | ((>= i 4) (print 'done)) ;end test, result-form 13 | (print i)) ;=> NIL [prints 0..3, done] 14 | 15 | (do ((n 0 (1+ n)) ;init to 0, step 1 16 | (current 0 next) ;init to 0, read old value of next 17 | (next 1 (+ current next))) ;init to 1, reads old values 18 | ((= 10 n) current)) ;=> 55 end test and result-form 19 | 20 | (do () 21 | ((> (get-universal-time) *some-future-date*)) 22 | (print "waiting...") 23 | (sleep 60)) 24 | ~~~ 25 | 26 | ### [dotimes] (var i \[result\]) form\* => result\* 27 | 28 | Iterate over a series of integers. Terminate loop immediately with [return]. 29 | 30 | ~~~ 31 | (dotimes (i 10) 32 | (print i)) 33 | 34 | (dotimes (i 10 (print 'done)) 35 | (print i)) 36 | ~~~ 37 | -------------------------------------------------------------------------------- /pages/symbol.md: -------------------------------------------------------------------------------- 1 | # Symbol Definition 2 | 3 | ## Style Guides 4 | 5 | * [Naming Conventions](http://www.cliki.net/Naming%20conventions) 6 | * [Google Style Guide](http://google-styleguide.googlecode.com/svn/trunk/lispguide.xml) 7 | 8 | ## Variables 9 | 10 | m4_include(../sections/variable.md) 11 | 12 | ## Functions 13 | 14 | * [PCL: Functions](http://www.gigamonkeys.com/book/functions.html) 15 | 16 | m4_include(../sections/function.md) 17 | 18 | ## Macros 19 | 20 | The Common Lisp macro facility allows the user to define 21 | arbitrary functions that convert certain Lisp forms into 22 | different forms before evaluating or compiling them. This is 23 | done at the expression level, not at the character-string 24 | level as in most other languages. Macros are important in 25 | the writing of good code: they make it possible to write 26 | code that is clear and elegant at the user level but that is 27 | converted to a more complex or more efficient internal form 28 | for execution. 29 | 30 | * [CLtL2: Macros](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node97.html) 31 | * [PCL: Macros: Defining Your Own](http://www.gigamonkeys.com/book/macros-defining-your-own.html) 32 | 33 | m4_include(../sections/macro.md) 34 | -------------------------------------------------------------------------------- /sections/bit-vector.md: -------------------------------------------------------------------------------- 1 | ## Bit-Vectors 2 | 3 | * [CLtL2: Bit-Vectors](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node161.html) 4 | 5 | ### [bit] bit-array &rest subscripts => bit 6 | 7 | Access the bit-array element specified by *subscripts*. 8 | [sbit] is similar but takes a [simple-bit-vector]. 9 | 10 | ~~~ 11 | (setf b #*00100) 12 | (bit b 2) ;=> 1 13 | (setf (bit b 2) 0) ;=> 0 [b => #\*00000] 14 | ~~~ 15 | 16 | ### [bit-not] bit-arrray \[opt\] => resulting-bit-array 17 | 18 | ### [bit-eqv] bit-array1 bit-array2 \[opt\] => resulting-bit-array 19 | 20 | ### [bit-and] bit-array1 bit-array2 \[opt\] => resulting-bit-array 21 | 22 | ### [bit-andc1] bit-array1 bit-array2 \[opt\] => resulting-bit-array 23 | 24 | ### [bit-andc2] bit-array1 bit-array2 \[opt\] => resulting-bit-array 25 | 26 | ### [bit-nand] bit-array1 bit-array2 \[opt\] => resulting-bit-array 27 | 28 | ### [bit-ior] bit-array1 bit-array2 \[opt\] => resulting-bit-array 29 | 30 | ### [bit-orc1] bit-array1 bit-array2 \[opt\] => resulting-bit-array 31 | 32 | ### [bit-orc2] bit-array1 bit-array2 \[opt\] => resulting-bit-array 33 | 34 | ### [bit-xor] bit-array1 bit-array2 \[opt\] => resulting-bit-array 35 | 36 | ### [bit-nor] bit-array1 bit-array2 \[opt\] => resulting-bit-array 37 | -------------------------------------------------------------------------------- /sections/alist.md: -------------------------------------------------------------------------------- 1 | ## Association List (alist) 2 | 3 | ### [acons] key datum alist => new-alist 4 | 5 | Append a *cons* and return a new *alist*. To modify an 6 | *alist* in place, use `push`. 7 | 8 | ~~~ 9 | (acons :c 3 '((:B . 2) (:A . 1))) ;=> ((:C . 3) (:B . 2) (:A . 1)) 10 | (push (cons :c 3) alist) ;=> ((:C . 3) (:B . 2) (:A . 1)) 11 | ~~~ 12 | 13 | ### [pairlis] keys data &optional alist => new-alist 14 | 15 | Pair up elements in *keys* and *data* lists to make an *alist*. 16 | 17 | ~~~ 18 | (pairlis '(:a :b) '(1 2)) ;=> ((:B . 2) (:A . 1)) 19 | ~~~ 20 | 21 | ### [assoc] item alist &key key test test-not => entry 22 | 23 | Return the alist entry whose *car* satisfies the test, or 24 | *nil*. Functional variants are `assoc-if` and 25 | `assoc-if-not`. `rassoc` uses *cdr* to test. 26 | 27 | ~~~ 28 | (assoc :a '((:A . 1) (:B . 2))) ;=> (:A . 1) 29 | (rassoc 1 '((:A . 1) (:B . 2))) ;=> (:A . 1) 30 | (assoc-if #'evenp '((1 . :A) (2 . :B))) ;=> (2 . :B) 31 | ~~~ 32 | 33 | ### [copy-alist] alist => new-alist 34 | 35 | Copies the *cons* cells that make up the alist structure. 36 | 37 | ### [alexandria:alist-plist] alist 38 | 39 | Converts an *alist* to a *plist* format. 40 | 41 | ~~~ 42 | (alist-plist '((:x . 10) (:y . 20))) ;=> (:x 10 :y 20) 43 | ~~~ 44 | -------------------------------------------------------------------------------- /sections/io/read.md: -------------------------------------------------------------------------------- 1 | ### [\*read-base\*] = 10 2 | 3 | Controls the interpretation of tokens by [read] as being 4 | integers or ratios. 5 | 6 | ### [\*read-default-float-format\*] = 'single-float 7 | 8 | Controls the floating-point format that is to be used when 9 | reading a floating-point number that has no exponent marker. 10 | 11 | ### [\*read-eval\*] = t 12 | 13 | If true, the `#.` reader macro has its normal effect, 14 | otherwise, signals an error. 15 | 16 | ### [\*read-suppress\*] = nil 17 | 18 | Supports the operation of the read-time conditional notations `#+` and `#-`. 19 | 20 | ### [read] \[input-stream eof-error-p eof-value recursive-p\] => object 21 | 22 | ### [read-preserving-whitespace] \[input-stream eof-error-p eof-value recursive-p\] => object 23 | 24 | ### [read-delimited-list] char \[input-stream recursive-p\] => list 25 | 26 | ### [read-from-string] string \[eof-error-p eof-value :start :end :preserve-whitespace\] => object, position 27 | 28 | ### [read-char] 29 | 30 | ### [read-char-no-hang] 31 | 32 | ### [peek-char] 33 | 34 | ### [unread-char] 35 | 36 | ### [read-byte] 37 | 38 | ### [read-line] 39 | 40 | ### [read-sequence] 41 | 42 | ### [yes-or-no-p] 43 | 44 | Or [y-or-n-p]. 45 | 46 | ### [clear-input] 47 | 48 | ### [with-input-from-string] 49 | -------------------------------------------------------------------------------- /sections/sequence/sort.md: -------------------------------------------------------------------------------- 1 | ## Sort 2 | 3 | ### [reverse] seq => reversed-seq 4 | 5 | Reverse the order of elements in a sequence. The destructive 6 | version is [nreverse]. To save the result in place, use [alexandria:reversef]. 7 | 8 | ~~~ 9 | (reverse '(a b c d)) ;=> (D C B A) 10 | ~~~ 11 | 12 | ### [sort] seq fn &key key => sorted-seq 13 | 14 | The sequence is destructively sorted according to an order 15 | determined by the predicate *fn*. [stable-sort] guarantees 16 | equal elements stay in same order. 17 | 18 | ~~~ 19 | (sort '(3 1 4 2) (lambda (x y) (< x y))) ;=> (1 2 3 4) 20 | ~~~ 21 | 22 | ### [merge] result-type seq1 seq2 fn &key key => result-seq 23 | 24 | Destructively concatenates the two sequences and sorts the 25 | combined elements based on the predicate *fn*. 26 | 27 | ~~~ 28 | (merge 'list '(1 3 5) '(2 4 6) #'<) ;=> (1 2 3 4 5 6) 29 | ~~~ 30 | 31 | ### [alexandria:rotate] seq &optional n => result-seq 32 | 33 | Returns a *sequence* with elements rotated by *n*, defaulting to 1. 34 | 35 | ~~~ 36 | (rotate '(a b c)) ;=> (C A B) 37 | (rotate '(a b c) -1) ;=> (B C A) 38 | ~~~ 39 | 40 | ### [alexandria:shuffle] seq &key start end => result-seq 41 | 42 | Returns a random permutation of a sequence bounded by *:start* 43 | and *:end*. The original sequence may be modified. 44 | -------------------------------------------------------------------------------- /sections/plist.md: -------------------------------------------------------------------------------- 1 | ## Property List (plist) 2 | 3 | Lists with alternating keys and values: `(:x 10 :y 20)`. 4 | Uses `#'eq` for `:test`, so should only use symbols as 5 | keywords. 6 | 7 | Every symbol contains metadata on it stored as a plist: 8 | 9 | ~~~ 10 | (symbol-plist 'symbol) ;access plist of symbol 11 | (get 'symbol 'key) ;equivalent to (getf (symbol-plist 'symbol) 12 | (setf (get 'symbol :my-key) "information") ;set value 13 | (remprop 'symbol 'my-key) ;remove property, same as (remf (symbol-plist 'symbol) 'my-key) 14 | ~~~ 15 | 16 | ### [getf] plist indicator &optional default => value 17 | 18 | ~~~ 19 | (getf plist :x) ;=> 10 20 | (setf (getf plist :x) 30) ;=> 30 21 | ~~~ 22 | 23 | ### [remf] place indicator => boolean 24 | 25 | ~~~ 26 | (remf plist :x) ;=> T 27 | ~~~ 28 | 29 | ### [get-properties] plist indicator-list => indicator, value, tail 30 | 31 | Used since [getf] can't distinguish an absent property from 32 | [nil]. Returns on the first key found. 33 | 34 | ~~~ 35 | (get-properties plist '(:x :y)) ;=> :X, 10, (:X 10 :Y 20) 36 | ~~~ 37 | 38 | ### [alexandria:plist-alist] plist 39 | 40 | ### [alexandria:plist-hash-table] plist &rest hash-table-initargs 41 | 42 | ### [alexandria:remove-from-plist] plist &rest keys 43 | 44 | ### [alexandria:remove-from-plistf] plist &rest keys 45 | 46 | destructive 47 | -------------------------------------------------------------------------------- /sections/list/iteration.md: -------------------------------------------------------------------------------- 1 | ### [dolist] (var list \[result\]) form\* => result\* 2 | 3 | Iterate over the elements of a [list]. Terminate loop immediately with [return]. 4 | 5 | ~~~ 6 | (dolist (x '(1 2 3 4)) 7 | (print x)) 8 | 9 | (dolist (x '(1 2 3 4) (print 'done)) 10 | (print x)) 11 | ~~~ 12 | 13 | ### [mapcar] 14 | 15 | Iterates over successive list elements and returns the 16 | accumlated results. **mapc** is similar except the results 17 | are *not* accumulated and the first list is returned. 18 | 19 | ~~~ 20 | (mapcar #'+ '(1 2) '(3 4)) ;=> (4 6) 21 | (mapcar (alexandria:compose #'print #'1+) '(1 2 3)) ;=> (2 3 4) [prints 2,3,4] 22 | ~~~ 23 | 24 | ### [maplist] 25 | 26 | ### [mapcan] 27 | 28 | ### [mapcon] 29 | 30 | ### [mapc] 31 | 32 | ### [mapl] 33 | 34 | ### [alexandria:mappend] fn &rest lists... => list 35 | 36 | Zips up list components and returns a flattened list. *fn* 37 | must return a list. 38 | 39 | ~~~ 40 | (mappend #'list '(1 3) '(2 4)) ;=> ((1 2) (3 4)) => (1 2 3 4) 41 | 42 | (flet ((zipper (x y) (list (+ x y)))) 43 | (mappend #'zipper '(1 3) '(2 4))) ;=> ((+ 1 2) (+ 3 4)) => (3 7) 44 | ~~~ 45 | 46 | ### [alexandria:map-product] fn list &rest lists... => list 47 | 48 | Results of calling `fn` with one argument per list for every combination. 49 | 50 | ~~~ 51 | (map-product #'list '(1 2) '(3 4) '(5 6)) 52 | ;=> ((1 3 5) (1 3 6) (1 4 5) (1 4 6) (2 3 5) (2 3 6) (2 4 5) (2 4 6)) 53 | ~~~ 54 | -------------------------------------------------------------------------------- /sections/equality.md: -------------------------------------------------------------------------------- 1 | 2 | * [CLtL2: Equality Predicates](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node74.html) 3 | * [PCL: Truth, Falsehood, and Equality](http://www.gigamonkeys.com/book/syntax-and-semantics.html#truth-falsehood-and-equality) 4 | 5 | ### [eq] x y => boolean 6 | 7 | Returns [t] if the objects are identical. Should *not* be used 8 | for numbers or characters since those types are 9 | implementation-dependant. 10 | 11 | ~~~ 12 | (eq 3 3.0) ;=> NIL 13 | (eq 3.0 3.0) ;=> T 14 | (eq "Foo" (copy-seq "Foo")) ;=> NIL 15 | (eq "FOO" "foo") ;=> NIL 16 | ~~~ 17 | 18 | ### [eql] x y => boolean 19 | 20 | Returns [t] if the objects are [eq] and also considers two 21 | objects of the same class representing the same value as equivalent, 22 | 23 | ~~~ 24 | (eql 'a 'a) ;=> T 25 | (eql 3 3) ;=> T 26 | (eql 3 3.0) ;=> NIL [int and float are different classes] 27 | ~~~ 28 | 29 | ### [equal] x y => boolean 30 | 31 | Considers lists equivalent if they contain the same 32 | structure and contents. Strings are equivalent if they 33 | contain the same characters. Falls back to [eql] for other types. 34 | 35 | ### [equalp] x y => boolean 36 | 37 | Numbers are equivalent if they represent the same value, 38 | ignores differences in string case. Sequences with [equalp] 39 | elements are equivalent. 40 | 41 | ~~~ 42 | (equalp 1 1.0) ;=> T 43 | (equalp "HeLlo" "hello") ;=> T 44 | ~~~ 45 | -------------------------------------------------------------------------------- /sections/types/main.md: -------------------------------------------------------------------------------- 1 | ## System Classes 2 | 3 | ### [t][t-class] 4 | 5 | The set of all objects. It is a supertype of every type, 6 | including itself. Every [object] is of type [t]. 7 | 8 | ### [nil][nil-type] 9 | 10 | Called an empty type since it contains no objects. It is 11 | a subtype of every type. No [object] is of type [nil]. 12 | 13 | ### [boolean] 14 | 15 | Contains the symbols [t] and [nil], which represent true and 16 | false, respectively. 17 | 18 | ### [function][function-class] 19 | 20 | A function is an [object] that represents code to be 21 | executed when an appropriate number of arguments is 22 | supplied. 23 | 24 | ### [compiled-function] 25 | 26 | ### [generic-function] 27 | 28 | ### [standard-generic-function] 29 | 30 | ### [class] 31 | 32 | ### [built-in-class] 33 | 34 | ### [structure-class] 35 | 36 | ### [standard-class] 37 | 38 | ### [method] 39 | 40 | ### [standard-method] 41 | 42 | ### [structure-object] 43 | 44 | ### [standard-object] 45 | 46 | ### [method-combination][method-combination-class] 47 | 48 | ### [satisfies] 49 | 50 | ### [member][member-type] 51 | 52 | ### [not][not-type] 53 | 54 | ### [and][and-type] 55 | 56 | ### [or][or-type] 57 | 58 | ### [values][values-type] 59 | 60 | ### [eql][eql-type] 61 | 62 | ### [coerce] 63 | 64 | ### [deftype] 65 | 66 | ### [type-of] 67 | 68 | ### [type-error] 69 | 70 | ### [type-error-datum] 71 | 72 | ### [type-error-expected-type] 73 | 74 | ### [simple-type-error] 75 | -------------------------------------------------------------------------------- /sections/list/select.md: -------------------------------------------------------------------------------- 1 | ### [first] 2 | 3 | Also [car] 4 | 5 | ~~~ 6 | (first '(:a :b :c)) ;=> :A 7 | (car '(:a :b :c)) ;=> :A 8 | ~~~ 9 | 10 | ### [rest] 11 | 12 | Also [cdr] 13 | 14 | ~~~ 15 | (rest '(:a :b :c)) ;=> (:B :C) 16 | (cdr '(:a :b :c)) ;=> (:B :C) 17 | ~~~ 18 | 19 | cXr ... cadr, caddr, etc. 20 | 21 | ### [nth] 22 | 23 | Also [first], [second], [third], ... [tenth]. 24 | 25 | ### [nthcdr] 26 | 27 | ~~~ 28 | (nthcdr 2 '(:a :b :c :d)) ;=> (:C :D) 29 | ~~~ 30 | 31 | ### [last] 32 | 33 | ~~~ 34 | (last '(:a :b :c :d)) ;=> (:D) 35 | (last '(:a :b :c :d) 2) ;=> (:C :D) 36 | ~~~ 37 | 38 | ### [butlast] list &optional n => result-list 39 | 40 | Returns a copy of *list* with the last *n* conses omitted, defaults to 1. 41 | The destructive vesion is [nbutlast]. 42 | 43 | ~~~ 44 | (butlast '(a b c d)) ;=> (A B C) 45 | (butlast '(a b c d) 2) ;=> (A B) 46 | ~~~ 47 | 48 | ### [ldiff] list sublist => result-list 49 | 50 | Returns the list difference, in a new list, whose elements 51 | of *list* appear before *sublist*. If *sublist* is not the 52 | tail of *list*, then return a copy of the entire *list*. 53 | 54 | ~~~ 55 | (setf list1 '(a b c d)) 56 | (setf list2 (last list1 2)) ;=> (C D) 57 | (ldiff list1 list2) ;=> (A B) 58 | ~~~ 59 | 60 | ### [list-length] list => length 61 | 62 | Returns the length of *list*. If *list* is a circular list, 63 | return [nil]. 64 | 65 | ~~~ 66 | (list-length '(a b c d)) ;=> 4 67 | (list-length '(a (b c) d)) ;=> 3 68 | ~~~ 69 | -------------------------------------------------------------------------------- /sections/sequence/iteration.md: -------------------------------------------------------------------------------- 1 | ### [map] result-type fn &rest seqs\* => result 2 | 3 | Applies the function to elements of each sequence in 4 | turn. The result sequence is as long as the shortest of the 5 | sequences. 6 | 7 | ~~~ 8 | (map 'list #'cons '(a b) '(c d)) ;=> ((A . C) (B . D)) 9 | (map 'vector #'(lambda (x) (* 2 x)) '(1 2 3)) ;=> #(2 4 6) 10 | ~~~ 11 | 12 | ### [map-into] result-seq fn &rest seqs\* => result-seq 13 | 14 | Destructively modifies *result-seq* to contain the results 15 | of applying the function to each element in the argument 16 | *seqs* in turn. 17 | 18 | ~~~ 19 | (map-into '(a b c) #'oddp '(1 2 3 4 5 6)) ;=> (T NIL T) 20 | ~~~ 21 | 22 | ### [remove-if-not] fn seq &key from-end start end count key => seq 23 | 24 | Filter 25 | 26 | ~~~ 27 | (remove-if-not #'oddp '(0 1 2 3 4)) ;=> (1 3) 28 | (remove-if-not (alexandria:disjoin #'zerop #'oddp) '(0 1 2 3 4)) ;=> (0 1 3) 29 | ~~~ 30 | 31 | ### [remove-if] fn seq &key from-end start end count key => seq 32 | 33 | ~~~ 34 | (remove-if #'oddp '(0 1 2 3 4)) ;=> (0 2 4) 35 | (remove-if (alexandria:disjoin #'zerop #'oddp) '(0 1 2 3 4)) ;=> (2 4) 36 | ~~~ 37 | 38 | ### [reduce] fn seq &key key from-end start end initial-value => result 39 | 40 | ~~~ 41 | (reduce #'* '(1 2 3 4 5)) ;=> 120 42 | ~~~ 43 | 44 | ### [alexandria:map-combinations] fn seq &key start end length copy 45 | 46 | ### [alexandria:map-derangements] fn seq &key start end copy 47 | 48 | ### [alexandria:map-permutations] fn seq &key start end length copy 49 | -------------------------------------------------------------------------------- /sections/list/tree.md: -------------------------------------------------------------------------------- 1 | ## Tree Functions 2 | 3 | Lists of lists. 4 | 5 | * [PCL: Beyond Lists: Other Uses for Cons Cells](http://www.gigamonkeys.com/book/beyond-lists-other-uses-for-cons-cells.html#trees) 6 | 7 | ### [tree-equal] 8 | 9 | Compares two trees, equal if structure is same shape and 10 | leaves are eql (or :test). 11 | 12 | ### [copy-tree] tree => new-tree 13 | 14 | Creates a copy of a *tree* of conses. 15 | 16 | ### [subst] new old tree &key key test test-not => new-tree 17 | 18 | Make a copy of *tree* with each subtree or leaf matching 19 | *old* replaced by *new*, the tree counterpart to 20 | [substitute]. Functional variants are [subst-if] and 21 | [subst-if-not], called on each atomic value in the tree. The 22 | destructive version is [nsubst] and variants. 23 | 24 | ~~~ 25 | (subst "two" 2 '(1 (1 2) (1 (2 3)))) ;=> (1 (1 "two") (1 ("two" 3))) 26 | (subst-if "one" #'(lambda (x) (equal x 1)) '(1 2 (3 2 1))) ;=> ("one" 2 (3 2 "one"))) 27 | ~~~ 28 | 29 | ### [sublis] alist tree &key key test test-not => new-tree 30 | 31 | Make a tree copy and substitute multiple leaves using an *alist*. 32 | 33 | ~~~ 34 | (sublis '((1 . "one") (2 . "two")) '(1 (1 2) (1 (2 3)))) 35 | ;=> ("one" ("one" "two") ("one" ("two" 3)))) 36 | ~~~ 37 | 38 | ### [alexandria:flatten] tree => list 39 | 40 | Collect non-null leaves into a [list]. 41 | 42 | ~~~ 43 | (flatten '(1 2 (3 2 1) ((1 1 nil) (2 2)))) ;=> (1 2 3 2 1 1 1 2 2) 44 | ~~~ 45 | 46 | ### [alexandria:circular-tree-p] object => boolean 47 | 48 | Test if *object* is a circular *tree*. 49 | -------------------------------------------------------------------------------- /sections/list/modify.md: -------------------------------------------------------------------------------- 1 | ### [append] lists\* => list 2 | 3 | Return a new list that is the concatenation of the 4 | arguments. The destructive version is [nconc]. To append in 5 | place, use [alexandria:appendf]. 6 | 7 | ~~~ 8 | (append '(a b) '() '(c d)) ;=> (A B C D) 9 | ~~~ 10 | 11 | ### [revappend] list tail => result-list 12 | 13 | Constructs a copy of *list* with the elements in reverse 14 | order, then append *tail*. The destructive version is [nreconc]. 15 | 16 | ~~~ 17 | (revappend '(1 2 3) '(a b c)) ;=> (3 2 1 A B C) 18 | ~~~ 19 | 20 | ### [push] item list => new-place-value 21 | 22 | Prepend item to the front of the list and store in 23 | place. [pushnew] will only add the item if it does not 24 | already exist in the list. 25 | 26 | ~~~ 27 | (setf lst '(a b c)) 28 | (cons 'd lst) ;=> (D A B C) [lst => (A B C)] 29 | (push 'd lst) ;=> (D A B C) [lst => (D A B C)] 30 | ~~~ 31 | 32 | ### [pop] list => element 33 | 34 | Returns the [car] of a list and store in place. 35 | 36 | ~~~ 37 | (setf lst '(a b c)) 38 | (car lst) ;=> A [lst => (A B C)] 39 | (pop lst) ;=> A [lst => (B C)] 40 | ~~~ 41 | 42 | ### [rplaca] cons object => cons 43 | 44 | Replaces the [car] of the *cons* with *object*. Modifies 45 | *cons* in-place. 46 | 47 | ~~~ 48 | (setf lst '(a b c)) 49 | (rplaca lst 'd) ;=> (D B C) 50 | ~~~ 51 | 52 | ### [rplacd] cons object => cons 53 | 54 | Replaces the [cdr] of the *cons* with *object*. Modifies 55 | *cons* in-place. 56 | 57 | ~~~ 58 | (setf lst '(a b c)) 59 | (rplacd lst '(d e)) ;=> (A D E) 60 | ~~~ 61 | -------------------------------------------------------------------------------- /sections/loop.md: -------------------------------------------------------------------------------- 1 | ## Loop Simple Form 2 | 3 | ### [loop] form\* => result\* 4 | 5 | Evaluate *forms* forever in a loop within an implict block named [nil]. 6 | 7 | ~~~ 8 | (setf i 0) 9 | (loop 10 | (print i) 11 | (if (< i 10) 12 | (incf i) 13 | (return))) ;=> NIL [prints 0...10] 14 | ~~~ 15 | 16 | ## Loop Extended Form 17 | 18 | * [CLtL2: Loop](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node235.html) 19 | * [PCL: LOOP for Black Belts](http://www.gigamonkeys.com/book/loop-for-black-belts.html) 20 | 21 | ### [loop] \[name\] \[variable-clause\*\] \[main-clause\*\] => result\* 22 | 23 | Use *loop keywords* to iterate over forms and accumulate values. 24 | 25 | ~~~ 26 | (loop for item in (list 'a 'b 'c 'd) 27 | do (print item)) ;=> NIL [prints A, B, C, D] 28 | 29 | (loop for item in (list 'a 'b 'c 'd) 30 | collect item) ;=> (A B C D) 31 | 32 | (loop for item across (vector 'a 'b 'c 'd) 33 | collect item) ;=> (A B C D) 34 | 35 | (loop for item in '(1 2 3 4) 36 | for x = (1+ item) 37 | collect (* item x)) ;=> (2 5 12 20) 38 | 39 | (loop for x on (list 10 20 30) 40 | collect x) ;=> ((10 20 30) (20 30) (30)) 41 | ~~~ 42 | 43 | Variables declared using `with` are local and cease to 44 | exists when the loop terminates. 45 | 46 | ~~~ 47 | (loop with x = 0 48 | with y = (1+ x) 49 | return (list x y)) ;=> (0 1) 50 | ~~~ 51 | 52 | ## Counting 53 | 54 | ~~~ 55 | (loop for i upto 4 collect i) ;=> (0 1 2 3 4) 56 | ~~~ 57 | -------------------------------------------------------------------------------- /sections/io/pathname.md: -------------------------------------------------------------------------------- 1 | ### [\*default-pathname-defaults\*] = pathname 2 | 3 | Implementation-dependent *pathname* used as the default 4 | whenever a function needs a [pathname] and one is not 5 | supplied. Typically, the working directory where Common Lisp 6 | was started up. 7 | 8 | ### [user-homedir-pathname] \[host\] => pathname 9 | 10 | ### [pathname] pathspec => pathname 11 | 12 | ### [make-pathname] \[:host :device :directory :name :type :version :defaults :case\] => pathname 13 | 14 | ### [pathname-host] pathname &key case => host 15 | 16 | ### [pathname-device] pathname &key case => device 17 | 18 | ### [pathname-directory] pathname &key case => directory 19 | 20 | ### [pathname-name] pathname &key case => name 21 | 22 | ### [pathname-type] pathname &key case => type 23 | 24 | ### [pathname-version] pathname &key case => version 25 | 26 | ### [load-logical-pathname-translations] host => just-loaded 27 | 28 | ### [logical-pathname-translations] host => translations 29 | 30 | `setf`able. 31 | 32 | ### [logical-pathname] pathspec => logical-pathname 33 | 34 | ### [namestring] pathname => namestring 35 | 36 | ### [file-namestring] pathname => namestring 37 | 38 | ### [directory-namestring] pathname => namestring 39 | 40 | ### [host-namestring] pathname => namestring 41 | 42 | ### [enough-namestring] pathname \[defaults\] => namestring 43 | 44 | ### [parse-namestring] thing \[host default-pathname :start :end :junk-allowed\] => pathname, position 45 | 46 | ### [translate-logical-pathname] pathname &key => physical-pathname 47 | 48 | ### [translate-pathname] source from-wildcard to-wildcard &key => translated-pathname 49 | 50 | ### [merge-pathnames] pathname \[default-pathname default-version\] => merged-pathname 51 | -------------------------------------------------------------------------------- /sections/io/print.md: -------------------------------------------------------------------------------- 1 | ### [write] object \[&key\*\] => object 2 | 3 | ### [write-byte] integer binary-output-stream 4 | 5 | ### [write-char] character \[output-stream\] => character 6 | 7 | ### [write-string] string \[output-stream\] &key :start :end => string 8 | 9 | ### [write-line] string \[output-stream\] &key :start :end => string 10 | 11 | ### [write-sequence] 12 | 13 | ### [terpri] \[output-stream\] => nil 14 | 15 | ### [fresh-line] \[output-stream\] => boolean 16 | 17 | ### [finish-output] \[output-stream\] => nil 18 | 19 | ### [force-output] \[output-stream\] => nil 20 | 21 | ### [clear-output] \[output-stream\] => nil 22 | 23 | ### [with-output-to-string] 24 | 25 | ### [write-to-string] object \[&key\*\] => object 26 | 27 | ### [prin1-to-string] object => object 28 | 29 | ### [princ-to-string] object => object 30 | 31 | ### [prin1] object \[output-stream\] => object 32 | 33 | produces output suitable for input to read. 34 | 35 | ### [print] object \[output-stream\] => object 36 | 37 | like prin1 except that the printed representation of object 38 | is preceded by a newline and followed by a space. 39 | 40 | ### [pprint] object \[output-stream\] => object 41 | 42 | just like print except that the trailing space is omitted 43 | and object is printed with the *print-pretty* flag non-nil 44 | to produce pretty output. 45 | 46 | ### [princ] object \[output-stream\] => object 47 | 48 | is just like prin1 except that the output has no escape 49 | characters. The general rule is that output from princ is 50 | intended to look good to people, while output from prin1 is 51 | intended to be acceptable to read. 52 | 53 | ### [print-unreadable-object] \(object stream &key type identity\) form\* => nil 54 | 55 | ### [\*print-readably\*] 56 | -------------------------------------------------------------------------------- /sections/string/compare.md: -------------------------------------------------------------------------------- 1 | ### [string=] str1 str2 &key start1 end1 start2 end2 => boolean 2 | 3 | Returns [t] if the given strings are of the same length 4 | and contain the same characters, otherwise return 5 | [nil]. Ignore differences in case using [string-equal]. 6 | 7 | ~~~ 8 | (string= "foo" "foo") ;=> T 9 | (string= "foo" "Foo") ;=> NIL 10 | (string= "abcd" "01234abcd9012" :start2 5 :end2 9) ;=> T 11 | (string-equal "foo" "Foo") ;=> T 12 | ~~~ 13 | 14 | ### [string/=] str1 str2 &key start1 end1 start2 end2 => mismatch-idx 15 | 16 | Returns [t] if the given strings are different, otherwise 17 | [nil]. Ignore differences in case using [string-not-equal]. 18 | 19 | ~~~ 20 | (string-not-equal "AAAA" "aaaA") ;=> NIL 21 | ~~~ 22 | 23 | ### [string<] str1 str2 &key start1 end1 start2 end2 => mismatch-idx 24 | 25 | Returns [t] if *str1* is less than *str2*, otherwise 26 | [nil]. Ignore differences in case using [string-lessp]. 27 | 28 | ~~~ 29 | (string< "aaaa" "aaab") ;=> 3 30 | (string-lessp "012AAAA789" "01aaab6" :start1 3 :end1 7 :start2 2 :end2 6) ;=> 6 31 | ~~~ 32 | 33 | ### [string>] str1 str2 &key start1 end1 start2 end2 => mismatch-idx 34 | 35 | Returns [t] if *str1* is greater than *str2*, otherwise 36 | [nil]. Ignore differences in case using [string-greaterp]. 37 | 38 | ### [string<=] str1 str2 &key start1 end1 start2 end2 => mismatch-idx 39 | 40 | Returns [t] if *str1* is less than or equal to *str2*, 41 | otherwise [nil]. Ignore differences in case using [string-not-greaterp]. 42 | 43 | ~~~ 44 | (string>= "aaaaa" "aaaa") ;=> 4 45 | (string-not-greaterp "Abcde" "abcdE") ;=> 5 46 | ~~~ 47 | 48 | ### [string>=] str1 str2 &key start1 end1 start2 end2 => mismatch-idx 49 | 50 | Returns [t] if *str1* is greater than or equal to *str2*, 51 | otherwise [nil]. Ignore differences in case using 52 | [string-not-lessp]. 53 | -------------------------------------------------------------------------------- /pages/string.md: -------------------------------------------------------------------------------- 1 | # Strings 2 | 3 | Inherits: [vector] => [array] => [sequence] => [t] 4 | 5 | A string is a specialized vector (one-dimensional array) 6 | whose elements are characters. 7 | 8 | * [CLtL2](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node164.html) 9 | * [PCL: Ch 10. Numbers, Characters, and Strings](http://www.gigamonkeys.com/book/numbers-characters-and-strings.html) 10 | * [HyperSpec: Strings Dictionary](http://www.lispworks.com/documentation/HyperSpec/Body/c_string.htm) 11 | 12 | ## Create 13 | 14 | ### [string] x => string 15 | 16 | Convert [symbol], [keyword], or [character] to a [string]. 17 | 18 | ~~~ 19 | (string :hello) ;=> "hello" 20 | ~~~ 21 | 22 | ### [make-string] size &key initial-element element-type => string 23 | 24 | Return a [simple-string] of length *size*. 25 | 26 | ~~~ 27 | (make-string 10 :initial-element #\5) ;=> "5555555555" 28 | ~~~ 29 | 30 | ### [parse-integer] str &key start end radix junk-allowed => int, idx 31 | 32 | Parses an [integer] in the specified *:radix*. 33 | 34 | ~~~ 35 | (parse-integer "24h" :junk-allowed t) ;=> 24, 2 36 | ~~~ 37 | 38 | m4_include(../sections/array/create.md) 39 | 40 | 41 | ## Select 42 | 43 | ### [char] str idx => character 44 | 45 | Specialized element accessor for type [string]. Is [setf]able. 46 | 47 | ~~~ 48 | (char "hello" 1) ;=> #\e 49 | (elt "hello" 1) ;=> #\e 50 | ~~~ 51 | 52 | m4_include(../sections/array/select.md) 53 | 54 | m4_include(../sections/sequence/select.md) 55 | 56 | 57 | ## Modify 58 | 59 | m4_include(../sections/string/modify.md) 60 | 61 | m4_include(../sections/vector/modify.md) 62 | 63 | m4_include(../sections/sequence/modify.md) 64 | 65 | ## Comparison 66 | 67 | m4_include(../sections/string/compare.md) 68 | 69 | ## Predicates 70 | 71 | m4_include(../sections/string/pred.md) 72 | 73 | m4_include(../sections/sequence/pred.md) 74 | -------------------------------------------------------------------------------- /sections/hashtable/iteration.md: -------------------------------------------------------------------------------- 1 | ### [maphash] function hash-table => nil 2 | 3 | Iterate over *hash-table* entries, calling *function* with 4 | two arguments, the key and value of that entry. 5 | 6 | ~~~ 7 | (setf ht (alexandria:plist-hash-table '(:x 10 :y 20)) 8 | buf (list)) 9 | (maphash #'(lambda (key val) 10 | (push (list key val) buf)) ht) ;=> NIL 11 | buf ;=> ((:Y 20) (:X 10)) 12 | ~~~ 13 | 14 | ### [alexandria:maphash-keys] function hash-table => nil 15 | 16 | Like [maphash], but calls *function* with each key in the *hash-table*. 17 | 18 | ~~~ 19 | (setf buf (list)) 20 | (alexandria:maphash-keys #'(lambda (key) 21 | (push key buf)) ht) ;=> NIL 22 | buf ;=> (:Y :X) 23 | ~~~ 24 | 25 | ### [alexandria:maphash-values] function hash-table => nil 26 | 27 | Like [maphash], but calls *function* with each value in the *hash-table*. 28 | 29 | ~~~ 30 | (setf buf (list)) 31 | (alexandria:maphash-values #'(lambda (val) 32 | (push val buf)) ht) ;=> NIL 33 | buf ;=> (20 10) 34 | ~~~ 35 | 36 | ### [loop] for \[key|value\] being the \[__hash-keys__|__hash-values__\] in hash-table 37 | 38 | Using the extended form of [loop](./loop-iterate.html#loop-extended-form), 39 | iterate over *hash-table* entries binding to *key* and *value*. 40 | 41 | ~~~ 42 | (loop 43 | for key being the hash-keys in ht 44 | for val being the hash-values in ht 45 | collect (list key val)) ;=> ((:X 10) (:Y 20)) 46 | ~~~ 47 | 48 | ### [iterate][iterate:for...in-hashtable] for \(key value\) __in-hashtable__ hash-table 49 | 50 | Using the [iterate](./loop-iterate.html#iterate) package, 51 | iterate over *hash-table* entries binding to *key* and *value*. 52 | 53 | ~~~ 54 | (iter (for (key val) in-hashtable ht) 55 | (collect (list key val))) ;=> ((:X 10) (:Y 20)) 56 | ~~~ 57 | -------------------------------------------------------------------------------- /sections/compose.md: -------------------------------------------------------------------------------- 1 | ### [alexandria:compose] fn &rest fns\* => function 2 | 3 | Compose function that applies its arguments to each in turn. 4 | 5 | ~~~ 6 | (compose #'fn2 #'fn1) ;=> (lambda (x) (fn2 (fn1 x))) 7 | ~~~ 8 | 9 | ### [alexandria:multiple-value-compose] fn &rest fns\* => function 10 | 11 | Compose functions that return multiple values. *fn1(x,y)* => *fn2(x1,y1)* => x2,y2 12 | 13 | ~~~ 14 | (funcall (multiple-value-compose #'fn2 #'fn1) x y) ;=> x2,y2 15 | ~~~ 16 | 17 | ### [alexandria:disjoin] pred &rest preds\* => function 18 | 19 | ~~~ 20 | (disjoin #'zerop #'oddp) ;≈ (lambda (x) (or (zerop x) (oddp x))) 21 | ~~~ 22 | 23 | ### [alexandria:conjoin] pred &rest preds\* => function 24 | 25 | ~~~ 26 | (conjoin #'zerop #'oddp) ;≈ (lambda (x) (and (zerop x) (oddp x))) 27 | ~~~ 28 | 29 | ### [alexandria:curry] fn &rest args\* => function 30 | 31 | ~~~ 32 | (funcall (curry #'list 'a 'b) 'c 'd) ;=> (A B C D) 33 | ~~~ 34 | 35 | ### [alexandria:rcurry] fn &rest args\* => function 36 | 37 | ~~~ 38 | (funcall (rcurry #'list 'a 'b) 'c 'd) ;=> (C D A B) 39 | ~~~ 40 | 41 | ### [complement] function => complement-function 42 | 43 | Return new [function] with same arguments and side effects 44 | as *function*, but with the opposite truth value. 45 | 46 | ~~~ 47 | (funcall (complement #'numberp) 1) ;=> NIL 48 | (funcall (complement #'member) 'd '(a b c)) ;=> T 49 | 50 | (complement fn) ;≈ #'(lambda (&rest args) (not (apply fn args))) 51 | ~~~ 52 | 53 | ### [constantly] value => function 54 | 55 | Return a [function] taking any number of arguments, which 56 | always returns *value*. 57 | 58 | ~~~ 59 | (setf f (constantly "hi")) 60 | (funcall f) ;=> "hi" 61 | (mapcar (constantly 3) '(a b c d)) ;=> (3 3 3 3) 62 | ~~~ 63 | 64 | ### [identity] object => object 65 | 66 | Returns its own argument *object*. Intended for functions 67 | that require a [function] argument. 68 | 69 | ~~~ 70 | (identity 23) ;=> 23 71 | (mapcan #'identity (list (list 1 2 3) '(4 5 6))) ;=> (1 2 3 4 5 6) 72 | ~~~ 73 | -------------------------------------------------------------------------------- /sections/hashtable/create.md: -------------------------------------------------------------------------------- 1 | ### [make-hash-table] \[:test :size :rehash-size :rehash-threshold\] => hash-table 2 | 3 | Create and return a new [hash-table]. Default *test* is `#'eql`. 4 | 5 | ~~~ 6 | (defparameter ht (make-hash-table)) ;=> # 7 | (setf (gethash :foo ht) 'bar) ;=> BAR 8 | ~~~ 9 | 10 | ### [alexandria:copy-hash-table] hash-table \[:key :test :size :rehash-size :rehash-threshold\] => hash-table 11 | 12 | Returns a shallow copy of *hash-table* with the same keys, values, and properties as the original. 13 | 14 | ~~~ 15 | (setf ht2 (alexandria:copy-hash-table ht)) ;=> # 16 | (gethash :foo ht2) ;=> BAR, T 17 | ~~~ 18 | 19 | ### [alexandria:alist-hash-table] alist \[:test :size :rehash-size :rehash-threshold\] => hash-table 20 | 21 | Return a [hash-table] containing the keys and values of the 22 | association-list *alist*. Takes the same arguments as [make-hash-table]. 23 | 24 | ~~~ 25 | (setf ht (alexandria:alist-hash-table '((:x . 7) (:y . 8)))) ;=> # 26 | (gethash :x ht) ;=> 7, T 27 | ~~~ 28 | 29 | ### [alexandria:plist-hash-table] plist \[:test :size :rehash-size :rehash-threshold\] => hash-table 30 | 31 | Return a [hash-table] containing the keys and values of the 32 | property-list *plist*. Takes the same arguments as [make-hash-table]. 33 | 34 | ~~~ 35 | (setf ht (alexandria:plist-hash-table '(:x 10 :y 20))) ;=> # 36 | (gethash :y ht) ;=> 20, T 37 | ~~~ 38 | 39 | ### [alexandria:hash-table-alist] hash-table => list 40 | 41 | Return an association-list containing the keys and values of *hash-table*. 42 | 43 | ~~~ 44 | (alexandria:hash-table-alist ht) ;=> ((:Y . 20) (:X . 10)) 45 | ~~~ 46 | 47 | ### [alexandria:hash-table-plist] hash-table => list 48 | 49 | Return a property-list containing the keys and values of *hash-table*. 50 | 51 | ~~~ 52 | (alexandria:hash-table-plist ht) ;=> (:Y 8 :X 7) 53 | ~~~ 54 | -------------------------------------------------------------------------------- /pages/regular-expression.md: -------------------------------------------------------------------------------- 1 | # Regular Expressions 2 | 3 | * [CL-PPCRE](http://weitz.de/cl-ppcre/) 4 | 5 | ## Install 6 | 7 | ~~~ 8 | (ql:quickload :cl-ppcre) 9 | ~~~ 10 | 11 | ## Scanning 12 | 13 | ### [cl-ppcre:create-scanner] 14 | 15 | * __create-scanner__ (string string) &key 16 | case-insensitive-mode multi-line-mode single-line-mode 17 | extended-mode destructive => scanner, register-names 18 | * __create-scanner__ (function function)&key 19 | case-insensitive-mode multi-line-mode single-line-mode 20 | extended-mode destructive => scanner 21 | * __create-scanner-__ (parse-tree t)&key 22 | case-insensitive-mode multi-line-mode single-line-mode 23 | extended-mode destructive => scanner, register-names 24 | 25 | ### [cl-ppcre:scan] 26 | 27 | ### [cl-ppcre:scan-to-strings] 28 | 29 | ### [cl-ppcre:register-groups-bind] 30 | 31 | ### [cl-ppcre:do-scans] 32 | 33 | ### [cl-ppcre:do-matches] 34 | 35 | ### [cl-ppcre:do-matches-as-strings] 36 | 37 | ### [cl-ppcre:all-matches] 38 | 39 | ### [cl-ppcre:all-matches-as-strings] 40 | 41 | 42 | ## Splitting and Replacing 43 | 44 | ### [cl-ppcre:split] 45 | 46 | ### [cl-ppcre:regex-replace] 47 | 48 | ### [cl-ppcre:regex-replace-all] 49 | 50 | 51 | ## Modifying Scanner Behaviour 52 | 53 | ### [cl-ppcre:\*property-resolver\*] 54 | 55 | ### [cl-ppcre:parse-tree-synonym] 56 | 57 | ### [cl-ppcre:\*regex-char-code-limit\*] 58 | 59 | ### [cl-ppcre:\*use-bmh-matchers\*] 60 | 61 | ### [cl-ppcre:\*optimize-char-classes\*] 62 | 63 | ### [cl-ppcre:\*allow-quoting\*] 64 | 65 | ### [cl-ppcre:\*allow-names-registers\*] 66 | 67 | 68 | ## Misc 69 | 70 | ### [cl-ppcre:parse-string] 71 | 72 | ### [cl-ppcre:create-optimized-test-function] 73 | 74 | ### [cl-ppcre:quote-meta-chars] 75 | 76 | ### [cl-ppcre:regex-apropos] 77 | 78 | ### [cl-ppcre:regex-apropos-list] 79 | 80 | 81 | ## Conditions 82 | 83 | ### [cl-ppcre:ppcre-error] 84 | 85 | ### [cl-ppcre:ppcre-invocation-error] 86 | 87 | ### [cl-ppcre:ppcre-syntax-error] 88 | 89 | ### [cl-ppcre:ppcre-syntax-error-string] 90 | 91 | ### [cl-ppcre:ppcre-syntax-error-pos] 92 | 93 | 94 | ## Unicode 95 | 96 | ### [cl-ppcre:unicode-property-resolver] 97 | -------------------------------------------------------------------------------- /sections/package/main.md: -------------------------------------------------------------------------------- 1 | ### [\*package\*] 2 | 3 | ### [\*modules\*] 4 | 5 | ### [load] filespec \[:verbose :print :if-does-not-exist :external-format\] => boolean 6 | 7 | ### [defpackage] name \[options...\] => package 8 | 9 | *options* are: 10 | 11 | * :nicknames 12 | * :use 13 | * :import-from 14 | * :shadow 15 | * :shadowing-import-from 16 | * :export 17 | * :intern 18 | * :size 19 | * :documentation 20 | 21 | ~~~ 22 | (defpackage :example-package 23 | (:nicknames :expkg :ex-pkg) 24 | (:use 25 | :cl 26 | :text-db 27 | :text) 28 | (:import-from :email :parse-email-address) 29 | (:shadow :my-name) ;ignore import version, use local 30 | (:shadowing-import-from :text-db ;resolve conflicting imports 31 | :save) 32 | (:export 33 | :my-fn)) 34 | (in-package :example-package) 35 | (load "./src/example-package") 36 | *package* ;=> # 37 | ~~~ 38 | 39 | ### [export] symbols \[package\] => t 40 | 41 | ### [find-symbol] string \[package\] => symbol, status 42 | 43 | ### [find-package] name => package 44 | 45 | ### [find-all-symbols] string => symbols 46 | 47 | ### [import] symbols \[package\] => t 48 | 49 | ### [list-all-packages] => packages 50 | 51 | ### [rename-package] package new-name \[new-nicknames\] => package-object 52 | 53 | ### [shadow] symbol-names \[package\] => t 54 | 55 | ### [shadowing-import] symbols \[package\] => t 56 | 57 | ### [delete-package] package => boolean 58 | 59 | ### [make-package] package-name \[:nicknames :use\] => package 60 | 61 | ### [unexport] symbols \[package\] => t 62 | 63 | ### [unintern] symbol \[package\] => boolean 64 | 65 | ### [in-package] name => package 66 | 67 | ### [unuse-package] packages-to-unuse \[package\] => t 68 | 69 | ### [use-package] packages-to-use \[package\] => t 70 | 71 | ### [intern] string \[package\] => symbol, status 72 | 73 | ### [package-name] package => name 74 | 75 | ### [package-nicknames] package => nicknames 76 | 77 | ### [package-shadowing-symbols] package => symbols 78 | 79 | ### [package-use-list] package => use-list 80 | 81 | ### [package-used-by-list] package => used-by-list 82 | 83 | ### [package-error-package] condition => package 84 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The Common Lisp MiniSpec 2 | 3 | This is a *Work in Progress* that still requires much 4 | filling-out. Contributing is easy and would be appreciated. 5 | 6 | The *MiniSpec* started out as a cheat-sheet that evolved 7 | into something more. The project's goal is to help Common 8 | Lisp programmers quickly find what they need. To that end, 9 | its focus is on navigation and usability, using 10 | example-driven documentation paired with concise 11 | descriptions and readily available links to more exhaustive 12 | references. 13 | 14 | ## Project Structure 15 | 16 | * `sections` ---Collections of symbol defintions documented 17 | in [Markdown](http://daringfireball.net/projects/markdown/). 18 | These files are split up so that each definition is only 19 | listed once (hopefully). 20 | * `pages` ---Pages navigable from the website. These can be 21 | built out of *sections* which can appear in multiple pages. 22 | * `build` ---Build scripts, HTML templates, and 23 | reference links used to generate the documentation. 24 | * `html` ---The output directory of the generated documentation. 25 | 26 | ## Build 27 | 28 | Building a copy of the documentation requires 29 | [Pandoc](http://johnmacfarlane.net/pandoc/) and 30 | [M4](http://www.gnu.org/software/m4/). [PhantomJS](http://phantomjs.org/) 31 | is required to generate all the reference links. 32 | 33 | ~~~ 34 | $ make 35 | ~~~ 36 | 37 | To re-generate all of the supporting reference links before building: 38 | 39 | ~~~ 40 | $ make all 41 | ~~~ 42 | 43 | ## Frontend Dependencies 44 | 45 | * [jQuery](http://jquery.com/) 46 | * [Bootstrap](http://twitter.github.io/bootstrap/) 47 | * [Highlight-Lisp](https://github.com/orthecreedence/highlight-lisp) 48 | * [Typeahead.js](https://github.com/twitter/typeahead.js) 49 | 50 | ## Style Guide 51 | 52 | # Page Level Heading 53 | 54 | ## Section Level Heading 55 | 56 | Description of the section. 57 | 58 | * [Supporting Link 1](http://example.com/section1) 59 | * [Supporting Link 2](http://example.com/section2) 60 | 61 | ### [fn-name] arg \[optional-arg\] many-args\* => return-type 62 | 63 | Short description. Links to a valid [fn-name] are resolved 64 | through external reference links. Here's a `code snippet` in 65 | the description. 66 | 67 | ~~~ 68 | (fn-name 'a '(b c) 'd) ;=> (A B C D) [prints B, C] 69 | ~~~ 70 | -------------------------------------------------------------------------------- /sections/list/set.md: -------------------------------------------------------------------------------- 1 | ## Set Functions 2 | 3 | * [PCL: Beyond Lists: Other Uses for Cons Cells](http://www.gigamonkeys.com/book/beyond-lists-other-uses-for-cons-cells.html#sets) 4 | 5 | ### [alexandria:setp] object &key test key => boolean 6 | 7 | Test if *object* is a [list] containing unique elements. 8 | 9 | ~~~ 10 | (setp '(a b c)) ;=> T 11 | (setp '(a b b)) ;=> NIL 12 | (setp '((10 :a) (10.0 :b)) :key #'car) ;=> T 13 | (setp '((10 :a) (10.0 :b)) :key #'car :test #'=) ;=> NIL 14 | ~~~ 15 | 16 | ### [subsetp] list1 list2 &key key test test-not => boolean 17 | 18 | Test if every element of *list1* matches an element in *list2*. 19 | 20 | ~~~ 21 | (subsetp '(c b a) '(a b c d)) ;=> T 22 | (subsetp '(a b c d) '(c b a)) ;=> NIL 23 | ~~~ 24 | 25 | ### [alexandria:set-equal] list1 list2 &key test key => boolean 26 | 27 | Test if every element in *list1* matches an element in 28 | *list2*, and vice-versa. 29 | 30 | ~~~ 31 | (set-equal '(a b c) '(c b a)) ;=> T 32 | (set-equal '(a b) '(a b c)) ;=> NIL 33 | ~~~ 34 | 35 | ### [member] item list &key key test test-not => tail 36 | 37 | Similiar to [find], but if the item is in the list return 38 | the tail, otherwise [nil]. Functional variants are 39 | [member-if] and [member-if-not]. 40 | 41 | ~~~ 42 | (member 'c '(a b c d)) ;=> (C D) 43 | (member-if #'evenp '(1 2 3 4)) ;=> (2 3 4) 44 | (member-if-not #'evenp '(1 2 3 4)) ;=> (1 2 3 4) 45 | ~~~ 46 | 47 | ### [adjoin] item list &key key test test-not => new-list 48 | 49 | Add item to *list* if not already there, otherwise return 50 | original list. Use [pushnew] to modify the original list. 51 | 52 | ### [union] list1 list2 &key key test test-not => result-list 53 | 54 | To save the result in place, use [alexandria:unionf]. 55 | 56 | ~~~ 57 | (union '(a b c) '(f a d)) ;=> (A B C D F) 58 | ~~~ 59 | 60 | ### [intersection] list1 list2 &key key test test-not => result-list 61 | 62 | Return a list that contains every element in both *list1* and *list2*. 63 | 64 | ~~~ 65 | (intersection '(a b c) '(b c d)) ;=> (B C) 66 | ~~~ 67 | 68 | ### [set-difference] list1 list2 &key key test test-not => result-list 69 | 70 | Returns a list of elements of *list1* that do not appear in *list2*. 71 | 72 | ~~~ 73 | (set-difference '(a b c e) '(b c d)) ;=> (A E) 74 | ~~~ 75 | 76 | ### [set-exclusive-or] list1 list2 &key key test test-not => result-list 77 | 78 | Returns a list of elements that appear in exactly one of *list1* and *list2*. 79 | 80 | ~~~ 81 | (set-exclusive-or '(a b c e) '(b c d)) ;=> (A D E) 82 | ~~~ 83 | -------------------------------------------------------------------------------- /sections/hashtable/values.md: -------------------------------------------------------------------------------- 1 | ### [hash-table-count] hash-table => n 2 | 3 | Return the number of entries in *hash-table*. 4 | 5 | ~~~ 6 | (setf ht (make-hash-table)) ;=> # 7 | (hash-table-count ht) ;=> 0 8 | (setf (gethash :foo ht) 'bar) 9 | (hash-table-count ht) ;=> 1 10 | ~~~ 11 | 12 | ### [gethash] key hash-table \[default\] => value, present-p 13 | 14 | Return a *key*'s entry value in *hash-table*, or *default* 15 | if none. If entry is found, *present-p* is [t]. Store values with [setf]. 16 | 17 | ~~~ 18 | (gethash :foo ht) ;=> NIL, NIL 19 | (gethash :foo ht 'default) ;=> DEFAULT, NIL 20 | (setf (gethash :foo ht) 'bar) 21 | (gethash :foo ht) ;=> BAR, T 22 | ~~~ 23 | 24 | ### [alexandria:ensure-gethash] key hash-table \[default\] => value, present-p 25 | 26 | Like [gethash], but if *key* is not found in *hash-table*, 27 | save *default* as an entry before returning it. 28 | 29 | ~~~ 30 | (setf ht (make-hash-table)) ;=> # 31 | (alexandria:ensure-gethash :z ht 99) ;=> 99, NIL 32 | (gethash :z ht) ;=> 99, T 33 | ~~~ 34 | 35 | ### [remhash] key hash-table => present-p 36 | 37 | Removes entry for *key* in *hash-table*. Returns [t] if 38 | there was such an entry, or [nil] otherwise. 39 | 40 | ~~~ 41 | (setf ht (alexandria:plist-hash-table '(:x 10 :y 20))) 42 | (remhash :x ht) ;=> T 43 | (remhash :z ht) ;=> NIL 44 | ~~~ 45 | 46 | ### [clrhash] hash-table => hash-table 47 | 48 | Removes all entries from *hash-table*, and then returns that empty *hash-table*. 49 | 50 | ~~~ 51 | (setf ht (alexandria:plist-hash-table '(:x 10 :y 20))) 52 | (hash-table-count ht) ;=> 2 53 | (clrhash ht) ;=> # 54 | (hash-table-count ht) ;=> 0 55 | ~~~ 56 | 57 | ### [alexandria:hash-table-keys] hash-table => list 58 | 59 | Returns a [list] containing the keys of *hash-table*. 60 | 61 | ~~~ 62 | (setf ht (alexandria:plist-hash-table '(:x 10 :y 20))) 63 | (alexandria:hash-table-keys ht) ;=> (:Y :X) 64 | ~~~ 65 | 66 | ### [alexandria:hash-table-values] hash-table => list 67 | 68 | Returns a list containing the values of *hash-table*. 69 | 70 | ~~~ 71 | (setf ht (alexandria:plist-hash-table '(:x 10 :y 20))) 72 | (alexandria:hash-table-values ht) ;=> (20 10) 73 | ~~~ 74 | -------------------------------------------------------------------------------- /sections/hashtable/advanced.md: -------------------------------------------------------------------------------- 1 | ### [with-hash-table-iterator] \(iter hash-table) form\* => result\* 2 | 3 | Generates an iterator [function] *iter* to successively step 4 | through entries in a *hash-table*. The *iter* function returns 5 | three values: a [boolean] if an entry was returned, the key 6 | from the *hash-table* entry, and the value from the 7 | *hash-table* entry. 8 | 9 | ~~~ 10 | (setf ht (alexandria:plist-hash-table '(:x 10 :y 20)) 11 | buf (list)) 12 | (with-hash-table-iterator (next-entry ht) 13 | (loop 14 | (multiple-value-bind (entry-p key val) (next-entry) 15 | (if entry-p 16 | (push (list key val) buf) 17 | (return))))) ;=> NIL 18 | buf ;=> ((:Y 20) (:X 10)) 19 | ~~~ 20 | 21 | ### [hash-table-test] hash-table => test 22 | 23 | Return the equality test used for comparing keys in *hash-table*. 24 | 25 | ~~~ 26 | (setf ht (make-hash-table)) ;=> # 27 | (setf test (hash-table-test ht)) ;=> EQL 28 | (funcall test 6 6) ;=> T 29 | ~~~ 30 | 31 | ### [hash-table-size] hash-table => size 32 | 33 | Return the current size of *hash-table*, an 34 | implementation-dependent value used to determine the amount 35 | of entries a [hash-table] can hold before it has to grow. 36 | 37 | ~~~ 38 | (setf ht (make-hash-table)) ;=> # 39 | (hash-table-size ht) ;=> 16 (implementation-dependent) 40 | ~~~ 41 | 42 | ### [hash-table-rehash-size] hash-table => rehash-size 43 | 44 | Return the current rehash size of *hash-table*, an 45 | implementation-dependent value used to determine the minimum 46 | amount to increase the size of the [hash-table] when it 47 | becomes full enough to require rehashing. 48 | 49 | ~~~ 50 | (setf ht (make-hash-table)) ;=> # 51 | (hash-table-rehash-size ht) ;=> 1.5 (implementation-dependent) 52 | ~~~ 53 | 54 | ### [hash-table-rehash-threshold] hash-table => rehash-threshold 55 | 56 | Return the current rehash threshold of *hash-table*, an 57 | implementation-dependent value used to determine how full 58 | the [hash-table] can get before it must grow. 59 | 60 | ~~~ 61 | (setf ht (make-hash-table)) ;=> # 62 | (hash-table-rehash-threshold ht) ;=> 1.0 (implementation-dependent) 63 | ~~~ 64 | 65 | ### [sxhash] object => hash-code 66 | 67 | Returns a hash-code for the *object*. The manner in which it 68 | is computed is implementation-dependent. 69 | 70 | ~~~ 71 | (eql (sxhash 'a) (sxhash 'a)) ;=> T 72 | (eql (sxhash 'a) (sxhash 'b)) ;=> NIL 73 | ~~~ 74 | -------------------------------------------------------------------------------- /sections/sequence/modify.md: -------------------------------------------------------------------------------- 1 | ### [concatenate] result-type &rest seqs... => result-seq 2 | 3 | ~~~ 4 | (concatenate 'list '(a b) '(c d)) ;=> (A B C D) 5 | (concatenate 'string "hello" "world") ;=> "helloworld" 6 | ~~~ 7 | 8 | ### [cl-utilities:split-sequence] delimiter seq &key count remove-empty-subseqs from-end start end test test-not key => list, idx 9 | 10 | Splits sequence into a *list* of subsequences delimited by 11 | objects satisfying the test. Also returns the lenbth of the 12 | sequence *idx*. Functional variants are 13 | [cl-utilities:split-sequence-if] and [cl-utilities:split-sequence-if-not]. 14 | 15 | ~~~ 16 | (split-sequence #\Space "hello world") ;=> ("hello" "world"), 11 17 | (split-sequence-if #'evenp '(1 1 2 1 3 4 1 3 5)) ;=> ((1 1) (1 3) (1 3 5)), 9 18 | ~~~ 19 | 20 | ### [fill] seq item &key start end => seq 21 | 22 | Destructively replaces the elements of *seq* bounded by 23 | *:start* and *:end* with *item*. 24 | 25 | ~~~ 26 | (fill '(a b c d) 'x :start 1 :end 3) ;=> (A X X D) 27 | ~~~ 28 | 29 | ### [replace] seq1 seq2 &key start1 end1 start2 end2 => seq1 30 | 31 | Destructively replaces the elements of *se1* bounded by 32 | *:start1* and *:end1* with the elements of *seq2* bounded by 33 | *:start2* and *:end2*. 34 | 35 | ~~~ 36 | (replace "abcde" "98765" :start1 1 :end1 3 :start2 3) ;=> "a65de" 37 | ~~~ 38 | 39 | To remove an element from a sequence at a given position: 40 | 41 | ~~~ 42 | (setf lst '(a b c d e)) 43 | (setf i (position 'b lst)) ;=> 1 44 | (replace lst lst :start1 i :start2 (1+ i)) ;=> (A C D E E) 45 | (butlast lst) ;=> (A C D E) 46 | ~~~ 47 | 48 | ### [substitute] new old seq &key from-end test test-not start end count key 49 | 50 | Functional variants are [substitute-if], 51 | [substitute-if-not]. Destructive variants are [nsubstitute], 52 | [nsubstitute-if], and [nsubstitute-if-not]. [subst] performs 53 | substitutions throughout a *tree*. 54 | 55 | ~~~ 56 | (substitute 10 1 '(1 2 1 3 1 4)) ;=> (10 2 10 3 10 4) 57 | (substitute-if 0 #'oddp '(1 2 3 4 5)) ;=> (0 2 0 4 0) 58 | ~~~ 59 | 60 | ### [remove] item seq &key from-end test test-not start end count key => result-seq 61 | 62 | Functional variants are [remove-if] and [remove-if-not]. The 63 | destructive variants are [delete], [delete-if], and 64 | [delete-if-not]. To remove in place, use 65 | [alexandria:removef] or [alexandria:deletef]. 66 | 67 | ~~~ 68 | (remove 4 '(1 2 4 1 3 4 5)) ;=> (1 2 1 3 5) 69 | (remove-if #'oddp '(1 2 4 1 3 4 5)) ;=> (2 4 4) 70 | (remove-if-not #'oddp '(1 2 1 3 4 5)) ;=> (1 1 3 5) 71 | ~~~ 72 | 73 | ### [remove-duplicates] seq &key from-end test test-not start end key 74 | 75 | Destructive variant is [delete-duplicates]. 76 | 77 | ~~~ 78 | (remove-duplicates '(1 2 1 2 3 1 2 3 4)) ;=> (1 2 3 4) 79 | ~~~ 80 | -------------------------------------------------------------------------------- /sections/sequence/select.md: -------------------------------------------------------------------------------- 1 | ### [elt] seq idx => element 2 | 3 | Related: `nth`, `nthcdr`, `car`, `cdr`, `first` ... `tenth` 4 | 5 | ~~~ 6 | (setf seq '(a b c)) 7 | (elt seq 1) ;=> B 8 | (setf (elt seq 1) "hi") ; seq => (A "hi" C) 9 | ~~~ 10 | 11 | ### [alexandria:random-elt] 12 | 13 | Return a random element from a sequence. 14 | 15 | ### [length] seq => n 16 | 17 | ~~~ 18 | (length '(a b c)) ;=> 3 19 | (length "hello") ;=> 5 20 | ~~~ 21 | 22 | ### [find] item seq &key from-end test test-not start end key => element 23 | 24 | If the sequence *seq* contains an element satisfying *test*, 25 | then the leftmost such element is returned; otherwise [nil] 26 | is returned. Functional variants are [find-if] and [find-if-not]. 27 | 28 | ~~~ 29 | (find 3 '(1 2 3 4 5)) ;=> 3 30 | (find-if #'oddp '(1 2 3 4 5) :end 3 :from-end t) ;=> 3 31 | ~~~ 32 | 33 | ### [position] item seq &key from-end test test-not start end key => idx 34 | 35 | Return the first index position of an item in the sequence, 36 | otherwise [nil]. 37 | 38 | ~~~ 39 | (position #\a "baobab" :from-end t) ;=> 4 40 | (position-if #'oddp '((1) (2) (3) (4)) :start 1 :key #'car) ;=> 2 41 | ~~~ 42 | 43 | ### [count] item seq &key from-end start end key test test-not => n 44 | 45 | The number of elements in the specified subsequence of 46 | *seq*. Functional variants are [count-if] and [count-if-not]. 47 | 48 | ~~~ 49 | (count 'a '(a b c a)) ;=> 2 50 | (count-if #'oddp '(1 2 3)) ;=> 2 51 | ~~~ 52 | 53 | ### [cl-utilities:extremum] seq fn &key key (start 0) end => smallest-element 54 | 55 | Returns first element of *sequence* if it were ordered by 56 | `sort` using the predicate *fn*. `extrema` is similar but 57 | returns a list of values since there may be more than one 58 | extremum determined by the predicate. `n-most-extreme` 59 | returns a list of *n* values of a sorted sequence. [ref](http://common-lisp.net/project/cl-utilities/doc/extremum.html) 60 | 61 | ~~~ 62 | (extremum '(1 2 9 7 3 2) #'>) ;=> 9 63 | (extrema '(1 2 9 7 3 2) #'>) ;=> (9) 64 | (n-most-extreme 3 '(1 2 9 7 3 2) #'>) ;=> (9 7 3) 65 | ~~~ 66 | 67 | ### [subseq] seq start &optional end => sub-seq 68 | 69 | Returns the sub-sequence of *seq* specified by *start* and *end*. 70 | 71 | ~~~ 72 | (setf str "hello") 73 | (subseq str 2 4) ;=> "ll" 74 | (setf (subseq str 2 4) "ad") ; str => "heado" 75 | ~~~ 76 | 77 | ### [search] seq1 seq2 &key from-end test test-not key start1 start2 end1 end2 => idx 78 | 79 | Searches sequence *seq2* for a sub-sequence that matches 80 | *seq1*. Returns its index position. 81 | 82 | ~~~ 83 | (search '(c d) '(a b c d)) ;=> 2 84 | (search "bar" "foobarbaz") ;=> 3 85 | ~~~ 86 | 87 | ### [mismatch] seq1 seq2 &key from-end test test-not key start1 start2 end1 end2 => idx 88 | 89 | Return the index position where two sequences diverge. 90 | 91 | ~~~ 92 | (mismatch "foobarbaz" "foom") ;=> 3 93 | ~~~ 94 | -------------------------------------------------------------------------------- /pages/time.md: -------------------------------------------------------------------------------- 1 | # Time 2 | 3 | * [HyperSpec: Time](http://www.lispworks.com/documentation/HyperSpec/Body/25_ad.htm) 4 | * [CLtL2: Time Functions](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node232.html) 5 | 6 | ### [get-universal-time] => universal-time 7 | 8 | Returns the current universal time, which is the number of 9 | seconds that have elapsed since 00:00 of January 1, 1900 in 10 | the GMT time zone. 11 | 12 | ~~~ 13 | (get-universal-time) ;=> 3574524644 14 | ~~~ 15 | 16 | ### [decode-universal-time] universal-time \[zone\] => sec, min, hr, day, m, yr, day-of-week, daylight-p, zone 17 | 18 | Returns the decoded time represented by the given *universal time*. 19 | 20 | ~~~ 21 | (defconstant +months+ '(1 "Jan" 2 "Feb" 3 "Mar" 4 "Apr" 5 "May" 6 "Jun" 22 | 7 "Jul" 8 "Aug" 9 "Sep" 10 "Oct" 11 "Nov" 12 "Dec")) 23 | (defconstant +days+ '(0 "Mon" 1 "Tue" 3 "Wed" 4 "Thu" 5 "Fri" 6 "Sat" 7 "Sun")) 24 | 25 | (defun universal-time-to-rfc822 (ut) 26 | (multiple-value-bind (s m h d month y weekday dst-p tz) (decode-universal-time ut) 27 | (declare (ignore dst-p)) 28 | (let ((day (getf +days+ weekday)) 29 | (mon (getf +months+ month)) 30 | (tzsign (if (minusp tz) "-" "+"))) 31 | (format nil "~a, ~2,'0d ~a ~d ~2,'0d:~2,'0d:~2,'0d ~a~2,'0d00" day d mon y h m s tzsign tz)))) 32 | 33 | (universal-time-to-rfc822 (get-universal-time)) ;=> "Tue, 09 Apr 2013 14:04:52 +0800" 34 | ~~~ 35 | 36 | ### [get-decoded-time] => sec, min, hour, day, month, year, day-of-week, daylight-p, zone 37 | 38 | Equivalent to `(decode-universal-time (get-universal-time))`. 39 | 40 | ~~~ 41 | (multiple-value-bind (sec min hr day m yr day-of-week dst-p tz) (get-decoded-time) 42 | (list sec min hr date m yr day-of-week dst-p tz)) ;=> (51 31 12 9 4 2013 1 T 8) 43 | ~~~ 44 | 45 | ### [encode-universal-time] sec min hr day m yr \[zone\] => universal-time 46 | 47 | Converts from decoded time format to a universal time. 48 | 49 | ### [get-internal-run-time] => internal-time 50 | 51 | Returns as an [integer] the current run time in internal 52 | time units. Its precise meaning is implementation-dependant, 53 | but the intent is that the difference between two calls to 54 | this function return the amount of time expended on behalf 55 | of the executing program. 56 | 57 | ### [get-internal-real-time] => internal-time 58 | 59 | Returns as an [integer] the current time in internal time 60 | units, relative to an arbitrary time base. The difference 61 | between the values of two calls to this function is the 62 | amount of elapsed real time (i.e., clock time) between the 63 | two calls. 64 | 65 | ### [sleep] seconds => nil 66 | 67 | Causes execution to cease and become dormant for 68 | approximately the *seconds* of real time indicated by 69 | seconds, whereupon execution is resumed. 70 | 71 | ~~~ 72 | (let ((then (get-universal-time))) 73 | (sleep 10) 74 | (- (get-universal-time) then)) ;=> 5 [secs elapsed] 75 | ~~~ 76 | 77 | ### [internal-time-units-per-second] 78 | 79 | Constant, a positive integer. The number of internal time 80 | units in one second. 81 | -------------------------------------------------------------------------------- /pages/array.md: -------------------------------------------------------------------------------- 1 | ## Arrays 2 | 3 | An array is an object with components arranged according to 4 | a rectilinear coordinate system. One-dimensional arrays are 5 | called *vectors*. 6 | 7 | A *general array* may contain any Lisp object, whereas a 8 | *specialized array* contains elements restricted to a 9 | specified type. Vectors whose elements are restricted to 10 | type *string-char* are called *strings*. Vectors whose 11 | elements are restricted to type *bit* are called 12 | *bit-vectors*. 13 | 14 | * [HyperSpec: Arrays](http://www.lispworks.com/documentation/HyperSpec/Body/15_.htm) 15 | * [CLtL2](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node157.html) 16 | * [PCL](http://www.gigamonkeys.com/book/collections.html) 17 | 18 | ## Create 19 | 20 | m4_include(../sections/array/create.md) 21 | 22 | ## Select 23 | 24 | m4_include(../sections/array/select.md) 25 | 26 | 27 | ### [row-major-aref] array index => element 28 | 29 | Considers array as a vector by viewing its elements in 30 | row-major order, and returns the element of that vector 31 | which is referred to by the given index. 32 | 33 | ### [array-row-major-index] array subscripts\* => index 34 | 35 | Computes the position according to the row-major ordering of 36 | array for the element that is specified by subscripts, and 37 | returns the offset of the element in the computed position 38 | from the beginning of array. 39 | 40 | ### [array-dimensions] array => dimensions 41 | 42 | Returns a list of the dimensions of array. (If array is a 43 | vector with a fill pointer, that fill pointer is ignored.) 44 | 45 | ~~~ 46 | (array-dimensions (make-array 4)) ;=> (4) 47 | (array-dimensions (make-array '(2 3))) ;=> (2 3) 48 | (array-dimensions (make-array 4 :fill-pointer 2)) ;=> (4) 49 | ~~~ 50 | 51 | ### [array-dimension] array axis-number => dimension 52 | 53 | Returns the axis-number dimension[1] of array. (Any fill 54 | pointer is ignored.) 55 | 56 | ~~~ 57 | (array-dimension (make-array 4) 0) ;=> 4 58 | (array-dimension (make-array '(2 3)) 1) ;=> 3 59 | ~~~ 60 | 61 | ### [array-total-size] array => size 62 | 63 | Returns the array total size of the array. 64 | 65 | ~~~ 66 | (array-total-size (make-array 4)) ;=> 4 67 | (array-total-size (make-array 4 :fill-pointer 2)) ;=> 4 68 | (array-total-size (make-array 0)) ;=> 0 69 | (array-total-size (make-array '(4 2))) ;=> 8 70 | (array-total-size (make-array '(4 0))) ;=> 0 71 | (array-total-size (make-array '())) ;=> 1 72 | ~~~ 73 | 74 | ### [array-rank] array => rank 75 | 76 | Returns the number of dimensions of array. 77 | 78 | ~~~ 79 | (array-rank (make-array '())) ;=> 0 80 | (array-rank (make-array 4)) ;=> 1 81 | (array-rank (make-array '(4))) ;=> 1 82 | (array-rank (make-array '(2 3))) ;=> 2 83 | ~~~ 84 | 85 | ### [array-displacement] array => displaced-to, displaced-index-offset 86 | 87 | If the array is a displaced array, returns the values of the 88 | :displaced-to and :displaced-index-offset options for the 89 | array (see the functions make-array and adjust-array). If 90 | the array is not a displaced array, nil and 0 are returned. 91 | 92 | ### [array-rank-limit] 93 | 94 | Constant. 95 | 96 | ### [array-dimension-limit] 97 | 98 | Constant. 99 | 100 | ### [array-total-size-limit] 101 | 102 | Constant variable. The upper exclusive bound on the array 103 | total size of an array. 104 | 105 | 106 | m4_include(../sections/sequence/select.md) 107 | -------------------------------------------------------------------------------- /sections/macro.md: -------------------------------------------------------------------------------- 1 | ### [defmacro] name lambda-list \[\[declare\* | doc\]\] forms\* => name 2 | 3 | Define a macro with a given *name*, which acts as an 4 | implicit [block] when evaluating 5 | *forms*. `define-compiler-macro` is similar with a few 6 | differences. 7 | 8 | 9 | ~~~ 10 | (defmacro adder (a b) 11 | "Sums two numbers and returns the result" 12 | `(+ ,a ,b)) 13 | 14 | (adder 4 5) ;=> 9 15 | ~~~ 16 | 17 | ### [macrolet] \(\(name lambda-list \[\[local-declare\ | local-doc\]\] local-forms\*)\*\) \[declare\*\] forms\* => result\* 18 | 19 | Defines local macro definitions, using the same format used by [defmacro]. 20 | 21 | ~~~ 22 | (macrolet ((adder (a b) `(+ ,a ,b))) 23 | (adder 4 5)) ;=> 9 24 | ~~~ 25 | 26 | ### [define-symbol-macro] symbol expansion => symbol 27 | 28 | Defines a macro expansion for *symbol*. `setf`able. 29 | 30 | ~~~ 31 | (setf a '(1 2 3)) 32 | (define-symbol-macro b (car a)) ;=> B 33 | b ;=> 1 34 | (setf b 5) 35 | a ;=> (5 2 3) 36 | b ;=> 5 37 | ~~~ 38 | 39 | ## Advanced 40 | 41 | ### [symbol-macrolet] \(\(symbol expansion\)\*\) declare\* forms\* => result\* 42 | 43 | Evaluate *forms* with locally defined symbol macros. 44 | 45 | ~~~ 46 | (symbol-macrolet ((x 'foo)) 47 | (list x (let ((x 'bar)) x))) ;=> (FOO BAR) 48 | ~~~ 49 | 50 | ### [define-modify-macro] name lambda-list function \[doc\] => name 51 | 52 | Defines a macro to read and write a place. 53 | 54 | ~~~ 55 | (define-modify-macro new-incf (&optional (delta 1)) +) 56 | (setf a 1) 57 | (new-incf a) ;=> 2 58 | ~~~ 59 | 60 | ### [defsetf] access-fn update-fn \[doc\] => access-fn 61 | 62 | Specify how to `setf` a place accessed by function. There is 63 | a "short form" and "long form" of [defsetf] as distinguished 64 | by the type of arguments. 65 | 66 | ~~~ 67 | (defun middle (x) 68 | (nth (truncate (* (list-length x) 0.5)) x)) 69 | (defun set-middle (x val) 70 | (let ((idx (truncate (* (list-length x) 0.5)))) 71 | (setf (nth idx x) val))) 72 | (defsetf middle set-middle) 73 | 74 | (setf a '(a b c)) ;=> (A B C) 75 | (middle a) ;=> B 76 | (setf (middle a) 2) 77 | a ;=> (A 2 C) 78 | ~~~ 79 | 80 | ### [get-setf-expansion] place &optional env => vars, vals, store-vars, writer-form, reader-form 81 | 82 | Returns lists of temporary variables, values, and get and 83 | set forms for [setf] to read *place*. 84 | 85 | ~~~ 86 | (defvar x) 87 | (get-setf-expansion 'x) ;=> NIL, NIL, (#:G6725), (SETQ X #:G6725), X 88 | ~~~ 89 | 90 | * [Setf Expansions](http://www.lispworks.com/documentation/HyperSpec/Body/05_aab.htm) 91 | 92 | ### [define-setf-expander] access-fn lambda-list \[\[declaration* | doc\]\] form\* => access-fn 93 | 94 | Specifies the means by which [setf] updates a place that is referenced by *access-fn*. 95 | 96 | ~~~ 97 | (defun last-element (x) (car (last x))) 98 | (define-setf-expander last-element (x &environment env) 99 | "Set the last element in a list to the given value." 100 | (multiple-value-bind (dummies vals newval setter getter) (get-setf-expansion x env) 101 | (let ((store (gensym))) 102 | (values dummies 103 | vals 104 | `(,store) 105 | `(progn (rplaca (last ,getter) ,store) ,store) 106 | `(lastguy ,getter))))) 107 | 108 | (setf l '(a b c d)) ;=> (A B C D) 109 | (last-element l) ;=> D 110 | (setf (last-element l) 4) 111 | l ;=> (A B C 4) 112 | ~~~ 113 | -------------------------------------------------------------------------------- /sections/conditions-control.md: -------------------------------------------------------------------------------- 1 | ## Condition Control Flow 2 | 3 | * [HyperSpec: Condition System Concepts](http://www.lispworks.com/documentation/HyperSpec/Body/09_a.htm) 4 | * [CLtL2: Conditions](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node312.html) 5 | * [PCL: Beyond Exception Handling: Conditions and Restarts](http://www.gigamonkeys.com/book/beyond-exception-handling-conditions-and-restarts.html) 6 | 7 | ### [handler-case] expr \[\[{error-clause\}\* | no-error-clause\]\] => result\* 8 | 9 | Executes *expr* in a dynamic environment where various 10 | condition handlers are active. Each *error-clause* specifies 11 | how to handle a matching condition type. A *no-error-clause* 12 | allows a particular action if control returns normally. 13 | 14 | ~~~ 15 | (defun adder-test (a b) 16 | (handler-case (+ a b) 17 | (type-error () :wrong-type) 18 | (error (condition) (list :any-other-error condition)) 19 | (:no-error (val) (list :success val)))) 20 | 21 | (adder-test 6 7) ;=> (:SUCCESS 13) 22 | (adder-test 6 'a) ;=> :WRONG-TYPE 23 | ~~~ 24 | 25 | ### [handler-bind] \(\(condition-type handler-function\)*\) forms\* => result\* 26 | 27 | Executes *forms* in a dynamic environment where the 28 | condition *handler-function* bindings are active. 29 | 30 | ~~~ 31 | (handler-bind ((simple-error #'(lambda (condition) 32 | (print (list :got-error condition))))) 33 | (error 'simple-error) 34 | (print 'not-printed)) ;=> [prints (:GOT-ERROR #) and throws error 35 | ~~~ 36 | 37 | ### [restart-case] form \{restarts\*\} => result\* 38 | 39 | Return values of *form* or, if during its evaluation one of 40 | the dynamically established *restarts* is called, the values 41 | of its restart-forms. 42 | 43 | ~~~ 44 | (restart-case (error 'simple-error) 45 | (do-nothing () nil) 46 | (do-something () (print 'doing-something))) 47 | ~~~ 48 | 49 | ~~~ 50 | (defun run-test () 51 | (print 'a) 52 | (error 'simple-error)) 53 | 54 | (defun run-handler (condition) 55 | (print 'b) 56 | (invoke-restart (find-restart :do-something)) 57 | (print 'not-printed)) 58 | 59 | (defun run-restart () 60 | (print 'c)) 61 | 62 | (handler-bind ((simple-error #'run-handler)) ;catch and run, invoke restart 63 | (restart-case (run-test) ;throws error 64 | (:do-nothing () nil) 65 | (:do-something () (run-restart)))) ;=> C [prints A, B, C] 66 | ~~~ 67 | 68 | ### [with-simple-restart] (name format-control format-arg*) forms\* => result* 69 | 70 | Return value of *forms* unless a restart is invoked, at 71 | which control is transferred to [with-simple-restart], which 72 | returns two values, [nil] and [t]. The restart is a prompt 73 | at the debugger which serves as a position to resume from. 74 | 75 | ~~~ 76 | (with-simple-restart (abort "Return to command level.") 77 | (print 'a) 78 | (error "an error") 79 | (print 'not-printed)) 80 | ~~~ 81 | 82 | Provide multiple restarts and prompt user for direction: 83 | 84 | ~~~ 85 | (defun collect-all-or-half (n) 86 | (let ((nums '()) 87 | (halfway (floor (/ n 2)))) 88 | (with-simple-restart (collect-half "Only collect ~a ?" halfway) 89 | (dotimes (i n) 90 | (with-simple-restart (collect-all "Collect all ~a ?" n) 91 | (if (= i halfway) 92 | (error "Prompt for number")) 93 | (push i nums)))) 94 | (reverse nums))) 95 | 96 | (collect-all-or-half 8) ;=> (0 1 2 3 4 5 6 7) [user selects COLLECT-ALL restart] 97 | (collect-all-or-half 8) ;=> (0 1 2 3) [user selects COLLECT-HALF restart] 98 | ~~~ 99 | 100 | ### [restart-bind] 101 | 102 | ### [invoke-restart] 103 | 104 | ### [invoke-restart-interactively] 105 | 106 | ### [find-restart] 107 | 108 | ### [compute-restarts] 109 | 110 | ### [restart-name] 111 | 112 | ### [with-condition-restarts] 113 | -------------------------------------------------------------------------------- /sections/function.md: -------------------------------------------------------------------------------- 1 | ### [defun] name lambda-list \[\[declare\* | doc\]\] form* => name 2 | 3 | Define a [function] with a given *name*, which acts as an 4 | implicit [block] when evaluating *forms*. Optionally 5 | [declare] type information about the function parameters. 6 | 7 | ~~~ 8 | (defun adder (a b) 9 | (declare (number a b)) 10 | "Sum numbers and return the result." 11 | (+ a b)) 12 | 13 | (adder 3 4) ;=> 7 14 | ~~~ 15 | 16 | ### [lambda] lambda-list \[\[declare\* | doc\]\] form* => function 17 | 18 | Return an anonymous [function]. 19 | 20 | ~~~ 21 | (funcall #'(lambda (x) (* x x)) 3) ;=> 9 22 | ~~~ 23 | 24 | ### [labels] \(\(name lambda-list \[\[local-declare\ | local-doc\]\] local-forms\*)\*\) \[declare\*\] forms\* => result\* 25 | 26 | Evaluate *forms* with a locally defined function. Functions 27 | defined by [labels] are visible within *local-forms*, 28 | functions defined by [flet] are not. 29 | 30 | ~~~ 31 | (labels ((adder (a b) 32 | (+ a b)) 33 | (adder1 (a b) 34 | (1+ (adder a b)))) 35 | (adder1 4 3)) ;=> 8 36 | 37 | (flet ((adder (a b) 38 | (+ a b))) 39 | (adder 4 3)) ;=> 7 40 | ~~~ 41 | 42 | ### [function] name => function 43 | 44 | The shorthand notation is `#'`. Return the [function] for *name*. 45 | 46 | ~~~ 47 | (funcall #'list 'a 'b) ;=> (A B) 48 | ~~~ 49 | 50 | ### [funcall] function args\* => result 51 | 52 | Apply values as arguments to *function*. 53 | 54 | ~~~ 55 | (funcall #'+ 1 2 3) ;=> 6 56 | ~~~ 57 | 58 | ### [apply] function \[args\*\] arg-list => result 59 | 60 | Apply values as arguments to *function*, the final one a [list]. 61 | 62 | ~~~ 63 | (apply #'+ '(1 2 3)) ;=> 6 64 | (apply #'+ 1 2 '(3 4)) ;=> 10 65 | ~~~ 66 | 67 | ### [multiple-value-call] function forms\* => result 68 | 69 | Apply all values returned from *forms* as arguments to *function*. 70 | 71 | ~~~ 72 | (multiple-value-call #'+ (floor 5.5) (floor 4.3)) ;= (+ 5 0.5 4 0.3) => 9.8 73 | ~~~ 74 | 75 | ### [values] objects\* => objects\* 76 | 77 | Return *objects* as multiple values. `setf`able. 78 | 79 | ~~~ 80 | (values 'a 'b) ;=> A, B 81 | (list (values 'a 'b)) ;=> (A) 82 | 83 | (setf (values a b) (floor 7.5)) 84 | (list a b) ;=> (7 0.5) 85 | ~~~ 86 | 87 | ### [values-list] list => objects\* 88 | 89 | Return *list* elements as multiple values. 90 | 91 | ~~~ 92 | (values-list '(A B)) ;=> A, B 93 | 94 | (multiple-value-bind (a b) (values-list '(1 2)) 95 | (list a b)) ;=> (1 2) 96 | ~~~ 97 | 98 | ### [multiple-value-list] form => list 99 | 100 | Evaluates *form* returning multiple values and returns a 101 | [list] containing them. 102 | 103 | ~~~ 104 | (multiple-value-list (floor 7.5)) ;=> (7 0.5) 105 | ~~~ 106 | 107 | ### [fmakunbound] name => name 108 | 109 | Removes the function or macro definition. 110 | 111 | ~~~ 112 | (defun add-some (x) (+ x 19)) ;=> ADD-SOME 113 | (fboundp 'add-some) ;=> T 114 | (flet ((add-some (x) (+ x 37))) 115 | (fmakunbound 'add-some) 116 | (add-some 1)) ;=> 38 117 | (fboundp 'add-some) ;=> NIL 118 | ~~~ 119 | 120 | ## Advanced 121 | 122 | ### [flet] \(\(name lambda-list \[\[local-declare\ | local-doc\]\] local-forms\*)\*\) \[declare\*\] forms\* => result\* 123 | 124 | ### [nth-value] n form => object 125 | 126 | Return the *n*th value yielded by *form*, zero-indexed. 127 | 128 | ~~~ 129 | (nth-value 0 (values 'a 'b)) ;=> A 130 | (nth-value 1 (values 'a 'b)) ;=> B 131 | ~~~ 132 | 133 | ### [function-lambda-expression] function => lambda-expression, closure-p, name 134 | 135 | If available, return lambda expression of *function*, `[nil] 136 | if *function* was defined in an environment without 137 | bindings, and name of *function*. 138 | 139 | ~~~ 140 | (function-lambda-expression (funcall #'(lambda (x) #'(lambda () x)) nil)) ;=> NIL, T, NIL 141 | ~~~ 142 | 143 | ### [fdefinition] name => definition 144 | 145 | Definition of global function foo; `setf`able. 146 | 147 | ~~~ 148 | (fdefinition 'list) ;=> # 149 | ~~~ 150 | -------------------------------------------------------------------------------- /sections/variable.md: -------------------------------------------------------------------------------- 1 | ### [defparameter] name value \[doc-string\] => name 2 | 3 | Unconditionally assign *value* to a global dynamic 4 | variable. The convention for naming a (global) special 5 | variable is `*name*`. 6 | 7 | ~~~ 8 | (defparameter *x* 1) ;=> *X* 9 | ~~~ 10 | 11 | ### [defvar] name \[value doc-string\] => name 12 | 13 | Unless bound already, assign *value* to a global dynamic variable. 14 | 15 | ~~~ 16 | (defvar *x* 'a) ;=> *X* 17 | (defvar *x* 'b) 18 | *x* ;=> A 19 | ~~~ 20 | 21 | ### [defconstant] name value \[doc-string\] => name 22 | 23 | Assign *value* to a global constant variable. A constant can 24 | be redefined by [defconstant]. The convention for naming a 25 | constant is `+name+`. 26 | 27 | ~~~ 28 | (defconstant +x+ 'a) ;=> +X+ 29 | (setf +x+ 'b) ;=> [error] 30 | ~~~ 31 | 32 | ### [setf] \{place value\}\* => result 33 | 34 | Sets the value of *place* to *value*. Multiple pairs are set 35 | sequentially, use `psetf` to set in parallel. `setf` works 36 | with symbols and forms, and is preferred, while [setq] and 37 | [psetq] can only set symbols. 38 | 39 | ### [let] \(\{var | \(var \[value\]\)\}\*\) forms\* => result\* 40 | 41 | Evaluate *forms* with *vars* lexically bound (or [NIL]) to 42 | values, assigned in parallel. Use [let\*] to assign sequentially. 43 | 44 | ~~~ 45 | (let ((x 1)) 46 | (list x)) ;=> (1) 47 | 48 | (let* ((x 1) 49 | (y (+1 x))) 50 | (list x y)) ;=> (1 2) 51 | ~~~ 52 | 53 | ### [multiple-value-bind] \(vars\*\) values-form body-forms\* => result\* 54 | 55 | Evaluate *body-forms* with *vars* lexically bound to the 56 | return values of *values-form*. Return values of *body-forms*. 57 | 58 | ~~~ 59 | (multiple-value-bind (q r) (floor 7.5) 60 | (list q r)) ;=> (7 0.5) 61 | ~~~ 62 | 63 | ### [destructuring-bind] lambda-list expression forms\* => result\* 64 | 65 | Evaluate *forms* with variables from tree *lambda-list* 66 | bound to corresponding elements of tree *expression*, and 67 | return their values. 68 | 69 | * [HyperSpec: Destructuring Lambda Lists](http://www.lispworks.com/documentation/HyperSpec/Body/03_de.htm) 70 | * [PCL: Destructuring-Bind](http://www.gigamonkeys.com/book/beyond-lists-other-uses-for-cons-cells.html#destructuring-bind) 71 | 72 | ~~~ 73 | (destructuring-bind (a b c) (list 1 (list 2 20) 3) 74 | (list a b c)) ;=> (1 (2 20) 3) 75 | 76 | (destructuring-bind (a (b &optional c) d) (list 1 (list 2) 3) 77 | (list a b c d)) ;=> (1 2 NIL 3) 78 | 79 | (destructuring-bind (&whole whole &key a b c) (list :c 3 :b 2 :a 1) 80 | (list a b c whole)) ;=> (1 2 3 (:C 3 :B 2 :A 1)) 81 | ~~~ 82 | 83 | ### [shiftf] place\* newvalue => first-value 84 | 85 | Store *newvalue* in rightmost *place*, shifting values of 86 | places left, returning first *place*. 87 | 88 | ~~~ 89 | (setf a :a b :b) 90 | (shiftf a b :c) ;=> :A 91 | (list a b) ;=> (:B :C) 92 | ~~~ 93 | 94 | ### [rotatef] places\* => nil 95 | 96 | Rotate values of *places* left, the first becoming new last place’s value. 97 | 98 | ~~~ 99 | (setf a :a b :b c :c) 100 | (rotatef a b c) ;=> NIL 101 | (list a b c) ;=> (:B :C :A) 102 | ~~~ 103 | 104 | ### [makunbound] symbol => symbol 105 | 106 | Makes *symbol* unbound, regardless of whether it was previously bound. 107 | 108 | ~~~ 109 | (setf a 1) 110 | (boundp 'a) ;=> T 111 | (makunbound 'a) ;=> A 112 | (boundp 'a) ;=> NIL 113 | ~~~ 114 | 115 | ## Advanced 116 | 117 | ### [psetf] \{place value\}\* => nil 118 | 119 | ### [setq] \{place value\}\* => result 120 | 121 | ### [psetq] \{place value\}\* => nil 122 | 123 | ### [multiple-value-setq] \(vars\) form => result 124 | 125 | Assign multiple values returned by *form* to *vars*. 126 | 127 | ~~~ 128 | (multiple-value-setq (a b) (values 1 2)) 129 | ~~~ 130 | 131 | ### [progv] symbols values forms\* => result\* 132 | 133 | Evaluate *forms* with locally established dynamic bindings of 134 | *symbols* to *values*. 135 | 136 | ~~~ 137 | (setf *a* 1) 138 | (progv '(*a*) '(2) 139 | (print *a*)) ;=> [prints 2] 140 | ~~~ 141 | -------------------------------------------------------------------------------- /sections/io/format.md: -------------------------------------------------------------------------------- 1 | ### [format] destination control-string args\* => result 2 | 3 | Creates formatted output using the *control-string* and 4 | observing tilde indicated directives. If *destination* is a 5 | [string], a [stream], or [t], then the *result* is 6 | [nil]. Otherwise, the *result* is a [string] containing the 7 | formatted output. 8 | 9 | ~~~ 10 | (format nil "Hello, ~a" 'lisp) ;=> "Hello, LISP!" 11 | ~~~ 12 | 13 | #### Basic Directives: 14 | 15 | * [`~A`] ---Aesthetic. Print without escape characters ([princ]). 16 | * [`~S`] ---Standard. Print with escape characters ([prin1]). 17 | * [`~%`] ---Newline character. `~n%` outputs *n* newlines. 18 | 19 | #### Number Directives: 20 | 21 | * [`~D`] ---Decimal. 22 | * [`~B`] ---Binary. Prints radix 2. 23 | * [`~O`] ---Octal. Prints radix 8. 24 | * [`~X`] ---Hexadecimal. Prints radix 16. 25 | * [`~R`] ---Radix. `~nR` prints in radix *n*. 26 | * [`~F`] ---Float. `~width,count,scale,overflowchar,padcharF` 27 | * [`~E`] ---Exponential notation. `~width,count,scale,overflowchar,padchar,exptcharE.` 28 | * [`~G`] ---General floating-point. `~width,count,scale,overflowchar,padchar,exptcharG.` 29 | * [`~$`] ---Dollars. `~count,min-count,min-width,padchar$` 30 | 31 | The `@` modifer causes the sign to always print. `:` adds 32 | commas between groups of digits. The most general form of 33 | `~D` is `~mincol,padchar,commachar,comma-intervalD.` 34 | 35 | #### Formatting Directives: 36 | 37 | * [`~W`] ---Write. Obey every printer-control variable ([write]). 38 | * [`~C`] ---Character. 39 | * [`~~`] ---Escape tilde character. 40 | * [`~&`] ---Fresh line. 41 | * [`~`] ---Ignores the newline and any whitespace that follows. 42 | * [`~_`] ---Conditional newline. 43 | * [`~|`] ---Page separator character. 44 | * [`~T`] ---Tabulate. 45 | * [`~I`] ---Indent. 46 | 47 | #### Control Directives: 48 | 49 | * [`~:>`] ---Logical Block. 50 | * [`~/`] ---Call function. 51 | * [`~<`] ---Justification. 52 | * [`~>`] ---End justifcation. 53 | * [`~*`] ---Go-To. 54 | * [`~[`] ---Conditional expression. 55 | * [`~]`] ---End conditional expression. 56 | * [`~{`] ---Iteration. 57 | * [`~}`] ---End iteration. 58 | * [`~?`] ---Recursive processing. 59 | * [`~(`] ---Case conversion. 60 | * [`~)`] ---End case conversion. 61 | * [`~P`] ---Plural. 62 | * [`~;`] ---Clause separator. 63 | * [`~^`] ---Escape upward. 64 | 65 | [`~C`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_caa.htm 66 | [`~%`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cab.htm 67 | [`~&`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cac.htm 68 | [`~|`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cad.htm 69 | [`~~`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cae.htm 70 | [`~R`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cba.htm 71 | [`~D`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cbb.htm 72 | [`~B`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cbc.htm 73 | [`~O`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cbd.htm 74 | [`~X`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cbe.htm 75 | [`~F`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cca.htm 76 | [`~E`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_ccb.htm 77 | [`~G`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_ccc.htm 78 | [`~$`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_ccd.htm 79 | [`~A`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cda.htm 80 | [`~S`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cdb.htm 81 | [`~W`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cdc.htm 82 | [`~_`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cea.htm 83 | [`~:>`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_ceb.htm 84 | [`~I`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cec.htm 85 | [`~/`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_ced.htm 86 | [`~T`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cfa.htm 87 | [`~<`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cfb.htm 88 | [`~>`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cfc.htm 89 | [`~*`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cga.htm 90 | [`~[`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cgb.htm 91 | [`~]`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cgc.htm 92 | [`~{`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cgd.htm 93 | [`~}`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cge.htm 94 | [`~?`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cgf.htm 95 | [`~(`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cha.htm 96 | [`~)`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_chb.htm 97 | [`~P`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_chc.htm 98 | [`~;`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cia.htm 99 | [`~^`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cib.htm 100 | [`~`]: http://www.lispworks.com/documentation/HyperSpec/Body/22_cic.htm 101 | -------------------------------------------------------------------------------- /sections/character.md: -------------------------------------------------------------------------------- 1 | # Characters 2 | 3 | The [standard-char] type comprises a-z, A-Z, 0-9, Newline, 4 | Space, and !?$"’‘.:,;*+-/|\~^<=>#%@&()[]{}. 5 | 6 | * [HyperSpec: Characters Dictionary](http://www.lispworks.com/documentation/HyperSpec/Body/c_charac.htm) 7 | * [CLtL2: Ch 13. Characters](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node135.html) 8 | * [PCL: Ch 10. Numbers, Characters, and Strings](http://www.gigamonkeys.com/book/numbers-characters-and-strings.html#characters) 9 | 10 | 11 | ## Comparison 12 | 13 | ### [characterp] object => boolean 14 | 15 | Test if *object* is of type [character]. 16 | 17 | ### [standard-char-p] char => boolean 18 | 19 | Test if *char* is of type [standard-char]. 20 | 21 | * [List of standard characters](http://www.lispworks.com/documentation/HyperSpec/Body/02_ac.htm). 22 | 23 | ### [graphic-char-p] char => boolean 24 | 25 | Test if *char* is a graphic (printing) [character]. 26 | 27 | ~~~ 28 | (graphic-char-p #\Space) ;=> T 29 | ~~~ 30 | 31 | ### [alpha-char-p] char => boolean 32 | 33 | Test if *char* is an alphabetic [character]. 34 | 35 | ~~~ 36 | (alpha-char-p #\a) ;=> T 37 | (alpha-char-p #\5) ;=> NIL 38 | ~~~ 39 | 40 | ### [alphanumericp] char => boolean 41 | 42 | Test if *char* is an alphabetic or numeric [character]. 43 | 44 | ~~~ 45 | (alpha-char-p #\a) ;=> T 46 | (alpha-char-p #\5) ;=> T 47 | ~~~ 48 | 49 | ### [upper-case-p] char => boolean 50 | 51 | Test if *char* is an uppercase [character]. 52 | 53 | ~~~ 54 | (upper-case-p #\A) ;=> T 55 | ~~~ 56 | 57 | ### [lower-case-p] char => boolean 58 | 59 | Test if *char* is an lowercase [character]. 60 | 61 | ~~~ 62 | (lower-case-p #\A) ;=> NIL 63 | ~~~ 64 | 65 | ### [both-case-p] char => boolean 66 | 67 | Test if *char* is a [character] with case. 68 | 69 | ~~~ 70 | (both-case-p #\5) ;=> NIL 71 | ~~~ 72 | 73 | ### [digit-char-p] char &optional radix => weight 74 | 75 | Return its weight if *char* is a digit, or [nil] otherwise. 76 | 77 | ~~~ 78 | (digit-char-p #\5) ;=> 5 79 | (digit-char-p #\a) ;=> NIL 80 | (digit-char-p #\a 11) ;=> 10 81 | ~~~ 82 | 83 | ### [char=] &rest chars... => boolean 84 | 85 | Returns [t] if all characters are the same, otherwise 86 | [nil]. Ignore differences in case using [char-equal]. 87 | 88 | ~~~ 89 | (char= #\d #\d) ;=> T 90 | (char= #\A #\a) ;=> NIL 91 | (char-equal #\A #\a) ;=> T 92 | ~~~ 93 | 94 | ### [char/=] &rest chars... => boolean 95 | 96 | Returns [t] if all characters are different, otherwise 97 | [nil]. Ignore differences in case using [char-not-equal]. 98 | 99 | ~~~ 100 | (char/= #\d #\d) ;=> NIL 101 | (char/= #\A #\a) ;=> T 102 | (char-not-equal #\A #\a) ;=> NIL 103 | ~~~ 104 | 105 | ### [char<] &rest chars... => boolean 106 | 107 | Returns [t] if the characters are monotonically 108 | increasing, otherwise [nil]. Ignore differences in case 109 | using [char-lessp]. 110 | 111 | ~~~ 112 | (char< #\a #\e #\e #\y) ;=> T 113 | ~~~ 114 | 115 | ### [char<=] &rest chars... => boolean 116 | 117 | Returns [t] if the characters are monotonically 118 | non-decreasing, otherwise, it [nil]. Ignore differences in 119 | case using [char-not-greaterp]. 120 | 121 | ~~~ 122 | (char<= #\a #\e #\e #\y) ;=> T 123 | ~~~ 124 | 125 | ### [char>] &rest chars... => boolean 126 | 127 | Returns [t] if the characters are monotonically 128 | decreasing, otherwise [nil]. Ignore differences in case 129 | using [char-greaterp]. 130 | 131 | ~~~ 132 | (char> #\e #\d) ;=> T 133 | ~~~ 134 | 135 | ### [char>=] &rest chars... => boolean 136 | 137 | Returns [t] if the characters are monotonically 138 | non-increasing, otherwise, it [nil]. Ignore differences in 139 | case using [char-not-lessp]. 140 | 141 | ~~~ 142 | (char>= #\e #\d) ;=> T 143 | ~~~ 144 | 145 | 146 | ## Conversion 147 | 148 | ### [character] char => denoted-char 149 | 150 | Returns the [character] denoted by the character 151 | designator. This is equivalent to `(coerce char 'character)`. 152 | 153 | ~~~ 154 | (character "a") ;=> #\a 155 | ~~~ 156 | 157 | ### [digit-char] i &optional radix => char 158 | 159 | Return a [character] representing non-negative [integer] *i*. 160 | 161 | ~~~ 162 | (digit-char 10 11) ;=> #\A 163 | ~~~ 164 | 165 | ### [char-name] char => name 166 | 167 | Returns a [string] that is the name of the character, or [nil]. 168 | 169 | ~~~ 170 | (char-name #\Space) ;=> "Space" 171 | ~~~ 172 | 173 | ### [name-char] name => char 174 | 175 | Return character name, as determined by [string-equal], or [nil]. 176 | 177 | ~~~ 178 | (name-char " ") ;=> #\Space 179 | ~~~ 180 | 181 | ### [char-code] char => code 182 | 183 | Returns the encoding of a [character]. If the character has no 184 | implementation-defined attributes, the result of [char-int] 185 | is the same. 186 | 187 | ~~~ 188 | (char-code #\A) ;=> 65 189 | ~~~ 190 | 191 | ### [code-char] code => char 192 | 193 | Return the [character] given its code. 194 | 195 | ~~~ 196 | (code-char 65) ;=> #\A 197 | ~~~ 198 | 199 | ### [char-upcase] char => corresponding-char 200 | 201 | If *char* is lowercase return the corresponding 202 | uppercase [character], or the given character. 203 | 204 | ~~~ 205 | (char-upcase #\a) ;=> #\A 206 | ~~~ 207 | 208 | ### [char-downcase] char => corresponding-char 209 | 210 | If *char* is lowercase return the corresponding 211 | uppercase [character], or the given character. 212 | 213 | ~~~ 214 | (char-downcase #\A) ;=> #\a 215 | ~~~ 216 | -------------------------------------------------------------------------------- /sections/control-flow.md: -------------------------------------------------------------------------------- 1 | ## Conditionals 2 | 3 | ### [if] test then \[else\] => result\* 4 | 5 | Return values of *then* if *test* is [t], otherwise return *else*. 6 | 7 | ~~~ 8 | (if (evenp 2) 'a) ;=> A 9 | (if (evenp 3) 10 | 'b 11 | 'c) ;=> C 12 | ~~~ 13 | 14 | ### [and] forms\* => result\* 15 | 16 | Evaluate *forms* from left to right. Immediately return 17 | [nil] if one form’s value is [nil], otherwise return the 18 | value of the last form. 19 | 20 | ~~~ 21 | (and (numberp 2) (evenp 2)) ;=> T 22 | ~~~ 23 | 24 | ### [or] forms\* => results\* 25 | 26 | Evaluate *forms* from left to right. Immediately return 27 | value of the first non-[nil] evaluating form, or all values 28 | if last form is reached. Return [nil] if no form returns [t]. 29 | 30 | ~~~ 31 | (or (numberp 3) (evenp 3)) ;=> T 32 | ~~~ 33 | 34 | ### [when] test forms\* => result\* 35 | 36 | Evaluate *forms* if *test* returns [t]. 37 | 38 | ~~~ 39 | (when (evenp 2) 40 | (print 'a) 41 | 'b) ;=> B [prints A] 42 | ~~~ 43 | 44 | ### [unless] test forms\* => result\* 45 | 46 | Evaluate *forms* if *test* returns [nil]. 47 | 48 | ~~~ 49 | (unless (evenp 3) 50 | (print 'a) 51 | 'b) ;=> B [prints A] 52 | ~~~ 53 | 54 | ### [cond] \(test then\*\)\* => result\* 55 | 56 | Return the values of the first *then* whose *test* returns 57 | [t], otherwise return [nil] if no tests pass. 58 | 59 | ~~~ 60 | (defun test (x) 61 | (cond ((= x 1) 'clause1) 62 | ((= x 2) 'clause2) 63 | (t 'clause3))) 64 | 65 | (test 2) ;=> CLAUSE2 66 | (test 9) ;=> CLAUSE3 67 | ~~~ 68 | 69 | ### [case] test \(key | \(key\*\) | otherwise form) => result\* 70 | 71 | Return the *form* for the first clause whose *key* is [eql] 72 | to *test*. If there is no *otherwise* clause, return [nil]. 73 | 74 | If no clause matches using [ccase], a *correctable* [error] 75 | is signaled allowing a [store-value] restart to be invoked. 76 | 77 | If no clause matches using [ecase], a *non-correctable* 78 | [error] is signaled. 79 | 80 | ~~~ 81 | (defun test (x) 82 | (case x 83 | (:a 'clause1) 84 | ((:b :c) 'clause2) 85 | (otherwise 'clause3))) 86 | 87 | (test :a) ;=> CLAUSE1 88 | (test :g) ;=> CLAUSE3 89 | ~~~ 90 | 91 | 92 | ## Sequencing 93 | 94 | ### [progn] forms\* => result\* 95 | 96 | Evaluates *forms*, in the order in which they are given. 97 | 98 | ~~~ 99 | (progn 100 | (print 'a) 101 | 'b) ;=> B [prints A] 102 | ~~~ 103 | 104 | ### [multiple-value-prog1] first-form forms\* => first-form-results 105 | 106 | Save values from *first-form*, evaluate remaining *forms*, 107 | then return the the saved values from *first-form*. 108 | 109 | ~~~ 110 | (multiple-value-prog1 111 | (values 1 2 3) 112 | (+ 2 2)) ;=> 1, 2, 3 113 | ~~~ 114 | 115 | ### [prog1] first-form forms\* => first-form-result 116 | 117 | Evaluates *first-form* and then remaining *forms*, yielding 118 | the value from *first-form*. 119 | 120 | ~~~ 121 | (prog1 'a 'b 'c) ;=> A 122 | ~~~ 123 | 124 | ### [prog2] first-form second-form forms\* => second-form-result 125 | 126 | Evaluates *first-form*, then *second-form*, and then remaining *forms*, yielding 127 | the value from *second-form*. 128 | 129 | ~~~ 130 | (prog2 'a 'b 'c) ;=> B 131 | ~~~ 132 | 133 | ### [prog] \(\{name | \(name \[value\]\)\}\*\) declare\* \{tag | form\}\* => result\* 134 | 135 | Evaluate [tagbody]-like body with *names* lexically bound in 136 | parallel. [prog] permits the use of the [return] and [go] 137 | statements. Use [prog\*] to bind local variables sequentially. 138 | 139 | ~~~ 140 | (prog ((x 1)) 141 | tag1 142 | (go tag3) 143 | tag2 144 | (return x) 145 | tag3 146 | (go tag2)) ;=> 1 147 | ~~~ 148 | 149 | ## Blocks and Exits 150 | 151 | * [HyperSpec: Transfer of Control to an Exit Point](http://www.lispworks.com/documentation/HyperSpec/Body/05_b.htm) 152 | * [PCL: Local Flow of Control](http://www.gigamonkeys.com/book/the-special-operators.html#local-flow-of-control) 153 | 154 | ### [block] name forms\* => result\* 155 | 156 | Establishes a named block and then evaluates forms as an 157 | implicit [progn] unless interrupted by [return-from]. 158 | 159 | ~~~ 160 | (block test 161 | (print 'printed) 162 | (return-from test) 163 | (print 'not-printed)) ;=> NIL [prints PRINTED] 164 | ~~~ 165 | 166 | ### [return-from] name \[result\] => result\* 167 | 168 | Returns control to the nearest enclosing [block] *name*, returning *results*. 169 | 170 | ~~~ 171 | (defun test () 172 | (return-from test 'done) 173 | 'a) 174 | 175 | (test) ;=> DONE 176 | ~~~ 177 | 178 | ### [return] \[result\] => result\* 179 | 180 | Returns, as if by [return-from], from a [block] named 181 | [nil], which many standard control structures 182 | generate. Equivalent to `(return-from nil ...)`. 183 | 184 | ~~~ 185 | (dotimes (i 10) 186 | (print i) 187 | (if (> i 5) (return 'done))) ;=> DONE [prints 0..6] 188 | ~~~ 189 | 190 | ### [tagbody] \{tag | form\}* => nil 191 | 192 | Evaluates *forms* in a lexical environment that provides 193 | *tags* for control transfers which are targets for [go]. Not 194 | often used since it's easier to write iterative constructs 195 | using existing looping macros. 196 | 197 | ~~~ 198 | (tagbody 199 | tag1 200 | (if (zerop (random 2)) 201 | (go tag2) 202 | (go tag3)) 203 | tag2 204 | (print 'counting) 205 | (go tag1) 206 | tag3 207 | (print 'exiting)) 208 | ~~~ 209 | 210 | ### [go] tag 211 | 212 | Transfers control to an enclosing [tagbody] form labeled by a tag [eql] to *tag*. 213 | 214 | ~~~ 215 | (tagbody 216 | (print 'printed) 217 | (go skip) 218 | (print 'not-printed) 219 | skip (print 'leaving)) ;=> NIL [prints PRINTED and LEAVING] 220 | ~~~ 221 | 222 | ### [catch] tag forms\* => result\* 223 | 224 | Evaluate *forms* and return their values unless interrupted by [throw]. 225 | 226 | ~~~ 227 | (defun foo () 228 | (catch 'exit 229 | (print 'enter-foo) 230 | (bar) 231 | (print 'not-printed-foo)) 232 | (print 'leave-foo)) 233 | 234 | (defun bar () 235 | (print 'enter-bar) 236 | (throw 'exit nil) 237 | (print 'not-printed-bar)) 238 | 239 | (foo) ;=> [prints ENTER-FOO, ENTER-BAR, LEAVE-FOO 240 | ~~~ 241 | 242 | ### [throw] tag form 243 | 244 | Have the nearest dynamically enclosing [catch] with a tag 245 | [eq] *tag* return with the values of *form*. 246 | 247 | ~~~ 248 | (catch 'tag 249 | (print 'printed) 250 | (throw 'tag 'done) 251 | (print 'not-printed)) ;=> DONE [prints PRINTED] 252 | ~~~ 253 | 254 | ### [unwind-protect] protected-form cleanup-forms\* => protected-form-result\* 255 | 256 | Evaluate *protected-form* and then, no matter how control 257 | leaves *protected-form*, evaluate *cleanup-form*. Return 258 | values of *protected-form*. 259 | 260 | ~~~ 261 | (catch 'exit 262 | (unwind-protect 263 | (progn 264 | (print 'printed) 265 | (throw 'exit 'a) 266 | (print 'not-printed)) 267 | (print 'also-printed) 268 | (print 'another-printed))) ;=> A [prints PRINTED, ALSO-PRINTED, ANOTHER-PRINTED] 269 | ~~~ 270 | -------------------------------------------------------------------------------- /sections/math/math.md: -------------------------------------------------------------------------------- 1 | ### [+] &rest numbers\* => sum 2 | 3 | ### [\*] &rest numbers\* => product 4 | 5 | ### [-] &rest numbers\* => difference 6 | 7 | Also used for negation, as in `(- 3) => -3`. 8 | 9 | ### [/] &rest numbers\* => quotient 10 | 11 | Also used for the reciprocal, as in `(/ 3) => 1/3`. 12 | 13 | ### [1+] number => successor 14 | 15 | ### [1-] number => predecessor 16 | 17 | ### [incf] place [delta] => new-value 18 | 19 | ### [decf] place [delta] => new-value 20 | 21 | ### [exp] number => result 22 | 23 | ### [expt] base-number power-number => result 24 | 25 | ### [log] number &optional base => logarithm 26 | 27 | ### [sqrt] number => root 28 | 29 | ### [isqrt] natural => natural-root 30 | 31 | ### [lcm] &rest integers => least-common-multiple 32 | 33 | ### [gcd] &rest integers => greatest-common-denominator 34 | 35 | ### [pi] 36 | 37 | Constant variable. The long float approximation to the mathematical constant *PI*. 38 | 39 | ~~~ 40 | pi ;=> 3.141592653589793D0 41 | ~~~ 42 | 43 | ### [sin] radians => number 44 | 45 | ### [cos] radians => number 46 | 47 | ### [tan] radians => number 48 | 49 | ### [asin] number => radians 50 | 51 | ### [acos] number => radians 52 | 53 | ### [atan] number1 &optional number2 => radians 54 | 55 | ### [sinh] number => result 56 | 57 | ### [cosh] number => result 58 | 59 | ### [tanh] number => result 60 | 61 | ### [asinh] number => result 62 | 63 | ### [acosh] number => result 64 | 65 | ### [atanh] number => result 66 | 67 | ### [cis] radians => number 68 | 69 | ### [conjugate] number => conjugate 70 | 71 | ### [max] &rest reals\* => max-real 72 | 73 | ### [alexandria:maxf] place &rest numbers env 74 | 75 | ### [min] &rest reals\* => min-real 76 | 77 | ### [alexandria:minf] place &rest numbers env 78 | 79 | ### [round] number &optional divisor => quotient, remainder 80 | 81 | Returns an [integer] quotient, [fround] returns a [float]. 82 | 83 | ### [floor] number &optional divisor => quotient, remainder 84 | 85 | Returns an [integer] quotient, [ffloor] returns a [float]. 86 | 87 | ### [ceiling] number &optional divisor => quotient, remainder 88 | 89 | Returns an [integer] quotient, [fceiling] returns a [float]. 90 | 91 | ### [truncate] number &optional divisor => quotient, remainder 92 | 93 | Returns an [integer] quotient, [ftruncate] returns a [float]. 94 | 95 | ### [mod] number divisor => modulus 96 | 97 | ### [rem] number divisor => remainder 98 | 99 | ### [random] limit &optional random-state => random-number 100 | 101 | ### [make-random-state] &optional state => new-state 102 | 103 | ### [\*random-state\*] 104 | 105 | The current *random state*, which is used, for example, by 106 | the function random when a random state is not explicitly 107 | supplied. 108 | 109 | ### [signum] number => signed-prototype 110 | 111 | ### [numerator] rational => numerator 112 | 113 | ### [denominator] rational => denominator 114 | 115 | ### [realpart] number => real 116 | 117 | ### [imagpart] number => real 118 | 119 | ### [complex] realpart &optional imagpart => complex 120 | 121 | ### [phase] number => phase 122 | 123 | ### [abs] number => absolute-value 124 | 125 | ### [rational] number => rational 126 | 127 | ### [rationalize] number => rational 128 | 129 | ### [float] number &optional prototype => float 130 | 131 | 132 | ## Logic Functions 133 | 134 | ### [boole] op integer1 integer2 => integer 135 | 136 | ### [lognot] integer => integer 137 | 138 | ### [logeqv] &rest integers => integer 139 | 140 | ### [logand] &rest integers => integer 141 | 142 | ### [logandc1] integer1 integer2 => integer 143 | 144 | ### [logandc2] integer1 integer2 => integer 145 | 146 | ### [lognand] integer1 integer2 => integer 147 | 148 | ### [logxor] &rest integers => integer 149 | 150 | ### [logior] &rest integers => integer 151 | 152 | ### [logorc1] integer1 integer2 => integer 153 | 154 | ### [logorc2] integer1 integer2 => integer 155 | 156 | ### [lognor] integer1 integer2 => integer 157 | 158 | ### [logbitp] index integer => boolean 159 | 160 | ### [logtest] integer1 integer2 => boolean 161 | 162 | ### [logcount] integer => number-of-on-bits 163 | 164 | 165 | ## Integer Functions 166 | 167 | ### [integer-length] integer => number-of-bits 168 | 169 | ### [ldb-test] bytespec integer => boolean 170 | 171 | ### [ash] integer count => shifted-integer 172 | 173 | ### [ldb] bytespec integer => byte 174 | 175 | ### [deposit-field] newbyte bytespec integer => integer 176 | 177 | ### [dpb] newbyte bytespec integer => integer 178 | 179 | ### [mask-field] bytespec integer => masked-integer 180 | 181 | ### [byte] size position => bytespec 182 | 183 | ### [byte-size] bytespec => size 184 | 185 | ### [byte-position] bytespec => position 186 | 187 | 188 | ## Implementation Dependent 189 | 190 | ### [short-float-epsilon] 191 | ### [short-float-negative-epsilon] 192 | 193 | ### [single-float-epsilon] 194 | ### [single-float-negative-epsilon] 195 | 196 | ### [double-float-epsilon] 197 | ### [double-float-negative-epsilon] 198 | 199 | ### [long-float-epsilon] 200 | ### [long-float-negative-epsilon] 201 | 202 | ### least-negative-{short-float|single-float|double-float|long-float} 203 | 204 | ### least-negative-normalized-{short-float|single-float|double-float|long-float} 205 | 206 | ### least-positive-{short-float|single-float|double-float|long-float} 207 | 208 | ### least-positive-normalized-{short-float|single-float|double-float|long-float} 209 | 210 | ### most-negative-{short-float|single-float|double-float|long-float|fixnum} 211 | 212 | ### most-positive-{short-float|single-float|double-float|long-float|fixnum} 213 | 214 | ### [decode-float] float => significand, exponent, sign 215 | 216 | ### [integer-decode-float] float => significand, exponent, integer-sign 217 | 218 | ### [scale-float] float integer => scaled-float 219 | 220 | ### [float-radix] float => float-radix 221 | 222 | ### [float-sign] float-1 &optional float-2 => signed-float 223 | 224 | ### [float-digits] float => digits1 225 | 226 | ### [float-precision] float => digits2 227 | 228 | ### [upgraded-complex-part-type] 229 | 230 | 231 | ## Extras 232 | 233 | ### [alexandria:binomial-coefficient] n k => integer 234 | 235 | ### [alexandria:count-permutations] n &optional k => integer 236 | 237 | ### [alexandria:clamp] number min max => number 238 | 239 | ### [alexandria:lerp] v a b => number 240 | 241 | ### [alexandria:factorial] n => number 242 | 243 | ### [alexandria:subfactorial] n => number 244 | 245 | ### [alexandria:gaussian-random] &optional min max => number, number 246 | 247 | ### [alexandria:iota] n &key start step => list 248 | 249 | ~~~ 250 | (iota 4) ;=> (0 1 2 3) 251 | (iota 3 :start 1 :step 1.0) ;=> (1.0 2.0 3.0) 252 | (iota 3 :start -1 :step -1/2) ;=> (-1 -3/2 -2) 253 | ~~~ 254 | 255 | ### [alexandria:map-iota] function n &key start step => number 256 | 257 | ~~~ 258 | (map-iota #'print 3 :start 10 :step 2) ;=> 3 [prints 10,12,14] 259 | ~~~ 260 | 261 | ### [alexandria:mean] sample => number 262 | 263 | *sample* is a [sequence] of numbers. 264 | 265 | ### [alexandria:median] sample => number 266 | 267 | *sample* is a [sequence] of real numbers. 268 | 269 | ### [alexandria:variance] sample &key biased => number 270 | 271 | *sample* is a [sequence] of numbers. 272 | 273 | ### [alexandria:standard-deviation] sample &key biased => number 274 | 275 | *sample* is a [sequence] of numbers. 276 | 277 | ### [cl-utilities:extremum] sequence fn &key key start end => smallest-element 278 | 279 | ### [cl-utilities:extrema] sequence fn &key key start end => smallest-elements 280 | 281 | ### [cl-utilities:n-most-extreme] n sequence fn &key key (start 0) end => n-smallest-elements 282 | 283 | ### [cl-utilities:expt-mod] n exponent divisor => result 284 | 285 | Returns *n* raised to the *exponent* power, modulo *divisor*. 286 | -------------------------------------------------------------------------------- /pages/object-system.md: -------------------------------------------------------------------------------- 1 | # Common Lisp Object System 2 | 3 | * [HyperSpec: Objects](http://www.lispworks.com/documentation/HyperSpec/Body/07_.htm) 4 | * [CLtL2: Common Lisp Object System](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node260.html) 5 | * [PCL: Generic Functions](http://www.gigamonkeys.com/book/object-reorientation-generic-functions.html) 6 | * [PCL: Classes](http://www.gigamonkeys.com/book/object-reorientation-classes.html) 7 | 8 | ## Classes 9 | 10 | ### [defclass] name ([superclass]) definitions\* => new-class 11 | 12 | Defines a named [class], returning the new class object as its result. 13 | 14 | ~~~ 15 | (defclass mammal () 16 | (legs sound)) 17 | 18 | (defclass dog (mammal) 19 | ((name 20 | :initarg :name 21 | :initform (error "A dog needs a name.") 22 | :reader title ;getter 23 | :writer (setf name) ;setter 24 | :documentation "Dog name.") 25 | (sound 26 | :accessor sound ;getter/setter 27 | :initform "woof")) 28 | (:documentation "Man's best friend.")) 29 | ~~~ 30 | 31 | And to pretty-print the object at the REPL: 32 | 33 | ~~~ 34 | (defmethod print-object ((dog dog) stream) 35 | (print-unreadable-object (dog stream :type t :identity t) 36 | (with-slots (name) dog 37 | (format stream ":NAME ~S" name)))) 38 | ~~~ 39 | 40 | ### [make-instance] class => instance 41 | 42 | ~~~ 43 | (setf mydog (make-instance 'dog :name "Sparky")) 44 | ~~~ 45 | 46 | ### [class-of] instance => class 47 | 48 | ~~~ 49 | (class-of mydog) ;=> # 50 | ~~~ 51 | 52 | ### [find-class] symbol \[error-p environment\] => class 53 | 54 | ~~~ 55 | (find-class 'dog) ;=> # 56 | ~~~ 57 | 58 | ### [class-name] class => name 59 | 60 | Returns the name of the given [class]. 61 | 62 | ~~~ 63 | (class-name (find-class 'dog)) ;=> DOG 64 | (setf (class-name (find-class 'dog)) 'doggie) 65 | ~~~ 66 | 67 | ### [slot-value] instance slot => value 68 | 69 | ~~~ 70 | (setf (slot-value mydog 'legs) 4) 71 | (slot-value mydog 'legs) ;=> 4 72 | (slot-value mydog 'breed) ;=> [throws error] 73 | ~~~ 74 | 75 | ### [with-slots] \(slots\*\) instance forms\* => result 76 | 77 | ~~~ 78 | (with-slots (name sound) mydog 79 | (list name sound)) ;=> ("Sparky" "woof") 80 | 81 | (with-slots ((n name) (l legs)) mydog 82 | (list n l)) ;=> ("Sparky" 4) 83 | ~~~ 84 | 85 | ### [with-accessors] \(accessors\*\) instance forms\* => result 86 | 87 | ~~~ 88 | (with-accessors (sound) mydog 89 | (list sound)) ;=> ("woof") 90 | 91 | (with-accessors ((s sound)) mydog 92 | (list s)) ;=> ("woof") 93 | ~~~ 94 | 95 | ### [slot-exists-p] instance name => boolean 96 | 97 | Test if object instance has a given slot. 98 | 99 | ### [slot-boundp] instance name => boolean 100 | 101 | Test if a slot is bound on a given object instance. Throw 102 | error if no such slot. 103 | 104 | ### [slot-makunbound] instance name => instance 105 | 106 | Unbind the slot on the given object instance. 107 | 108 | ## Methods 109 | 110 | ### [defgeneric] name lambda-list ...options-and-methods => generic-function 111 | 112 | Define or modify a *generic function*. 113 | 114 | ~~~ 115 | (defgeneric say-hello (mammal) 116 | (:documentation "Say hi.")) 117 | 118 | (defgeneric say-hello (mammal) 119 | (:method ((m mammal)) (print "blink")) 120 | (:method ((d dog)) (print "wag tail"))) 121 | ~~~ 122 | 123 | ### [defmethod] name lambda-list ...forms\* => method 124 | 125 | Defines a method on a *generic function*. 126 | 127 | ~~~ 128 | (defgeneric make-sound (dog)) 129 | 130 | (defmethod make-sound ((dog dog)) 131 | (slot-value dog 'sound)) 132 | 133 | (make-sound mydog) ;=> "woof" 134 | ~~~ 135 | 136 | Use [setf] to define a class setter method: 137 | 138 | ~~~ 139 | (defmethod (setf make-sound) (noise (dog dog)) 140 | (setf (slot-value dog 'sound) noise)) 141 | 142 | (setf (make-sound mydog) "bark!") 143 | ~~~ 144 | 145 | ### [initialize-instance] instance ...initargs &key &allow-other-keys => instance 146 | 147 | Called by [make-instance] to initialize a newly created 148 | instance. Use with method combination to create a 149 | constructor-like function. 150 | 151 | ~~~ 152 | (defmethod initialize-instance :after ((dog dog) &key) 153 | (setf (slot-value dog 'legs) 4)) 154 | ~~~ 155 | 156 | ## Advanced 157 | 158 | ### [add-method] generic-function method => generic-function 159 | 160 | Adds a [method] to a *generic-function*. 161 | 162 | ### [remove-method] generic-function method => generic-function 163 | 164 | Removes a [method] from a *generic-function*. 165 | 166 | ### [ensure-generic-function] name &key... => generic-function 167 | 168 | Define or modify a *generic-function*. 169 | 170 | ### [invalid-method-error] method format-control ...args => implementation-dependent 171 | 172 | Signal error on applicable method with invalid qualifiers. 173 | 174 | ### [method-combination-error] format-control ...args => implementation-dependent 175 | 176 | Signal error on applicable method with invalid method combination. 177 | 178 | 179 | ## Method Combination 180 | 181 | * [PCL: Method Combination](http://www.gigamonkeys.com/book/object-reorientation-generic-functions.html#method-combination) 182 | * [CLtL2: Method Selection and Combination](http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node283.html) 183 | 184 | Using standard method combination: 185 | 186 | ~~~ 187 | (defgeneric bedtime (dog)) 188 | 189 | (defmethod bedtime ((d dog)) 190 | (print 'zzzzz)) 191 | 192 | (defmethod bedtime :before ((d dog)) 193 | (print 'lay-down)) 194 | 195 | (defmethod bedtime :after ((d dog)) 196 | (print 'wake-up)) 197 | 198 | (defmethod bedtime :around ((d dog)) 199 | (print 'yawn) 200 | (let ((val (call-next-method))) ;=> save original return value 201 | (print 'get-up) 202 | val)) 203 | 204 | (bedtime mydog) ;=> ZZZZZ [prints YAWN, LAY-DOWN, ZZZZZ, WAKE-UP, GET-UP] 205 | ~~~ 206 | 207 | ### [define-method-combination] name lambda-list ...forms\* => name 208 | 209 | Define a new [method-combination] type. 210 | 211 | Combination options: progn|+|list|and|or|max|min|append|nconc 212 | Default is *progn*, this executes all applicable methods in 213 | most-specific to least-specific order. 214 | 215 | ~~~ 216 | (defgeneric eat (mammal) 217 | (:method-combination progn)) 218 | 219 | (defmethod eat progn ((m mammal)) 220 | (print 'digest)) 221 | 222 | (defmethod eat progn ((d dog)) 223 | (print 'lick)) 224 | 225 | (eat mydog) ;=> DIGEST [prints LICK, DIGEST] 226 | ~~~ 227 | 228 | ### [next-method-p] => boolean 229 | 230 | Called within a *method* to determine whether a *next method* exists. 231 | 232 | ### [call-next-method] ...args => result 233 | 234 | Used within a method to call the *next method*. 235 | 236 | ~~~ 237 | (defgeneric itch (mammal body-part)) 238 | 239 | (defmethod itch ((m mammal) body-part) 240 | (format t "twitch ~a" body-part)) 241 | 242 | (defmethod itch ((d dog) body-part) 243 | (format t "scratch ~a~%" body-part) 244 | (if (next-method-p) 245 | (call-next-method))) 246 | 247 | (itch mydog "leg") ;=> [prints "scratch leg" then "twitch leg"] 248 | ~~~ 249 | 250 | ### [call-method] method-name \[next-method-list\] => result 251 | 252 | From within a [method], call *method-name* with the 253 | arguments of the generic function and with information about 254 | its next-methods; return its values. 255 | 256 | 257 | ## Method Selection 258 | 259 | ## Advanced 260 | 261 | ### [find-method] generic-function method-qualifiers specializers \[error-p\] => method 262 | 263 | Return suitable method, or signal *error*. 264 | 265 | ~~~ 266 | (find-method #'say-hello '() '(mammal)) ;=> # 267 | ~~~ 268 | 269 | ### [compute-applicable-methods] generic-function args => methods 270 | 271 | List of methods suitable for *args*, most specific first. 272 | 273 | ~~~ 274 | (compute-applicable-methods #'say-hello (list mydog)) 275 | ;=> (# #) 276 | ~~~ 277 | 278 | ### [function-keywords] method => keys, allow-other-keys-p 279 | 280 | Returns the keyword parameter specifiers for a method. 281 | 282 | ### [method-qualifiers] method => qualifiers 283 | 284 | Returns the keyword parameter specifiers for a method. 285 | 286 | 287 | ## Redefine 288 | 289 | ## Advanced 290 | 291 | ### [reinitialize-instance] instance ...initargs &key &allow-other-keys => instance 292 | 293 | Change the values of local slots of an object instance according to *initargs*. 294 | 295 | ### [change-class] instance new-class &key &allow-other-keys => instance 296 | 297 | Changes the class of an instance to *new-class*. It 298 | destructively modifies and returns the instance. 299 | 300 | ### [make-instances-obsolete] class => class 301 | 302 | Update all existing instances of class using [update-instance-for-redefined-class]. 303 | 304 | ### [allocate-instance] class ...initargs &key &allow-other-keys => new-instance 305 | 306 | Creates and returns a new instance of the class, without 307 | initializing it. Called by [make-instance]. 308 | 309 | ### [shared-initialize] instance slot-names ...initargs &key &allow-other-keys => instance 310 | 311 | Fill the slots of an object instance using *initargs* and 312 | *:initform* forms. Called when an instance is created. 313 | 314 | ## Internal 315 | 316 | ## Advanced 317 | 318 | ### [slot-missing] class instance slot-name operation \[new-value\] => result 319 | 320 | Called on attempted access to non-existing slot. 321 | 322 | ### [slot-unbound] class instance slot-name => result 323 | 324 | Called on attempted access to unbound slot. 325 | 326 | ### [update-instance-for-redefined-class] instance args... => result 327 | 328 | Set any initarg slots to their corresponding values. 329 | 330 | ### [update-instance-for-different-class] previous current ... => implementation-dependent 331 | 332 | Set slots on behalf of [change-class] by means of [shared-initialize]. 333 | 334 | ### [no-applicable-method] generic-function ...args => result 335 | 336 | Called on invocation of generic-function on args if there is no applicable method. 337 | 338 | ### [no-next-method] generic-function method ...args => result 339 | 340 | Called on invocation of [call-next-method] when there is no next method. 341 | -------------------------------------------------------------------------------- /sections/datastructures.md: -------------------------------------------------------------------------------- 1 | # Data Structures 2 | 3 | ## Array 4 | 5 | Fixed-size/resizable vectors and multi-dimensional arrays. 6 | 7 | ### make-array dimensions [&keys...] 8 | 9 | Params: 10 | 1. `dimensions` ---[valid array dimension](http://www.lispworks.com/documentation/HyperSpec/Body/26_glo_v.htm#valid_array_dimension) 11 | 12 | Keys: 13 | * `element-type` 14 | * `initial-element` 15 | * `initial-contents` 16 | * `adjustable` 17 | * `fill-pointer` 18 | * `displaced-to` 19 | * `displaced-index-offset` 20 | 21 | ~~~ 22 | (make-array 3 :initial-element nil) => #(nil nil nil) ;array length with init value 23 | (make-array 3 :fill-pointer 0) => #() ;resizable, holds 3 elements. adds to pointer position 24 | (make-array 3 :fill-pointer 0 :adjustable t) ;arbitrarily resizable vector 25 | (make-array '(3 3)) => #2A((0 0 0) (0 0 0) (0 0 0)) ;3x3 multi-dimensional array 26 | ~~~ 27 | 28 | ### vector [values...] 29 | 30 | One-dimensional array with a fixed length. 31 | 32 | Inherits: 33 | 1. array 34 | 2. sequence 35 | 3. t 36 | 37 | Params: 38 | 1. `values` 39 | 40 | * [HS](http://www.lispworks.com/documentation/HyperSpec/Body/t_vector.htm) 41 | * [PCL](http://gigamonkeys.com/book/collections.html#vectors) 42 | 43 | ~~~ 44 | (vector 1 2 3) ;=> #(1 2 3) 45 | #(1 2 3) ;literal notation 46 | ~~~ 47 | 48 | 49 | ### Typed Array 50 | 51 | Create specialized vector of certain type, this creates an adjustable string: 52 | 53 | ~~~ 54 | (make-array 5 :fill-pointer 0 :adjustable t :element-type 'character) => "" 55 | ~~~ 56 | 57 | ~~~ 58 | (vector-push 'a *vector*) => 0 ;returns index where added, *vector* => #(A) 59 | (vector-pop *vector*) => A ;returns most recently added item, decrements fill-pointer 60 | (vector-push-extend 'b *vector*) => 3 ;auto-expand vector to hold additional element, return position 61 | ~~~ 62 | 63 | 64 | Used with sequences, vectors and lists: 65 | 66 | ~~~ 67 | (defvar *v* (vector 'a 'b 'c)) 68 | (length *v*) => 3 69 | (elt *v* 0) => A 70 | (elt *v* 3) => error 71 | 72 | (setf (elt *v* 1) 'two) => TWO ;*v* => #(A TWO C) 73 | 74 | (aref *v* 0) => A ;get array position reference 75 | (svref *v* 2) => C ;simple vector reference, faster then general array ref 76 | ~~~ 77 | 78 | Basic sequence functions (vectors, lists, strings): 79 | 80 | ~~~ 81 | (defparameter *seq* #(1 2 3 1)) 82 | (count 1 *seq*) => 2 ;number of times item appears in sequence 83 | (find 1 *seq*) => 1 ;return first item found, nil if not found 84 | (position 1 *seq*) => 0 ;position of first item in sequence, nil if not found 85 | (remove 1 *seq*) => #(2 3) ;sequence with instances of items removed 86 | 87 | (substitute 7 1 *seq*) => #(7 2 3 7) ;sequence with items replaced 88 | ~~~ 89 | 90 | Recycling versions of remove (non-consing): 91 | `delete`, `delete-if`, `delete-if-not`, `delete-duplicates` 92 | 93 | Recycling versions of substitute: `nsubstitute`, `nsubstitute-if`, `nsubstitute-if-not` 94 | 95 | Standard sequence function keyword arguments 96 | 97 | * `:test = #'eql` 2 arg function to compare item (or value extracted by `:key` function) 98 | * `:key = nil` 1 arg function to extract key value from sequence element 99 | * `:start = 0` Starting index of subsequence 100 | * `:end = nil` Ending index of subsequence, nil indicates end of sequence 101 | * `:from-end = nil` If true, sequence will be traversed in reverse order 102 | * `:count = nil` Number or elements to effect (remove or substitute only) 103 | 104 | The *example-test* function takes 2 args and returns a boolean: 105 | 106 | ~~~ 107 | (count x *seq* :test #'example-test) ;default is #'eql 108 | (count x *seq* :test (complement #'example-test)) ;opposite, instead of :test-not 109 | (count "foo" '("foo" "bar" "baz") :test #'string=) ;=> 1 110 | ~~~ 111 | 112 | `:key` takes a 1 arg function for each sequence element to return val to be compared: 113 | 114 | ~~~ 115 | (find 'b #((a 10) (b 20) (c 30)) :key #'first) => (C 30) 116 | ~~~ 117 | 118 | Higher-order function variants, each has a `*-if`, and `*-if-not suffix` takes same keyword arguments as vanilla versions, except `:test`: 119 | 120 | ~~~ 121 | (defparameter *seq* #(1 2 3 1) 122 | (count-if #'evenp *seq*) => 1 123 | (count-if-not #'evenp *seq*) => 3 124 | (find-if #'evenp *seq*) => 2 125 | (find-if-not #'evenp *seq*) => 1 126 | (position-if #'digit-char-p "abcd0001") => 4 127 | (remove-if #'(lambda (x) (char= (elt x 0) #\f)) '("foo" "bar")) => ("bar") 128 | (remove-if-not #'(lambda (x) (char= (elt x 0) #\f)) '("foo" "bar")) => ("foo") ;filter 129 | (remove-if-not #'alpha-char-p '("foo" "0bar") :key #'(lambda (x) (elt x 0))) => ("foo") 130 | (remove-duplicates *seq*) => #(1 2 3) ;doesn't take :count keyword 131 | (substitute-if 0 #'evenp '(1 2 3 4)) => (1 0 3 0) 132 | (substitute-if-not #'evenp '(1 2 3 4)) => (0 2 0 4) 133 | ~~~ 134 | 135 | Whole sequence manipulations: 136 | 137 | ~~~ 138 | (copy-seq *seq*) ;returns new sequence of same type with same elements 139 | (reverse *seq*) ;returns new sequence of same type with elements reversed 140 | (setf *seq* (nreverse *seq*)) ;recycling function 141 | ;return new sequence of type specified from sequences. usually 'vector, 'list, or 'string 142 | (concatenate 'vector *seq1* *seq2* ...) 143 | ~~~ 144 | 145 | Copying 146 | 147 | ~~~ 148 | copy-seq 149 | copy-list ;makes copy of cons cells, references underlying structure, doesn't copy sub-lists 150 | copy-tree ;makes new cons cell for each, copies sub-lists, copies references to atomic values 151 | copy-alist 152 | ~~~ 153 | 154 | ;;sorting and merging, also takes :key argument 155 | ;;sort is destructive, use copy-seq or copy-list to pass copy 156 | (sort *seq* #'>) => #(3 2 1 1) ;takes sequence and 2 arg predicate function 157 | (stable-sort *seq* #'>) ;guaranteed not to reorder any elements considered equivalent 158 | ;;if both sequences are sorted by given predicate, then result will also be sorted 159 | (merge 'list *seq* '(6 5 2) #'>) => '(6 5 3 2 2 1 1) 160 | 161 | ;;subsequence manipulations 162 | (subseq "foobarbaz" 3) => "barbaz" 163 | (subseq "foobarbaz" 3 6) => "bar" 164 | (setf (subseq "foobarbaz" 3 6) "xxx") => "fooxxxbaz" ;ignores extra or short values 165 | 166 | (fill "foobar" #\x :start 1 :end 3) => "fxxbar" 167 | 168 | (search "bar" "foobarbaz") => 3 ;same as position, except first arg is a sequence 169 | ;;standard keyword args, :key, :test, :from-end, :start1, :end1, :start2, :end2 170 | (mismatch "foobarbaz" "foom") => 3 ;index where 2 sequences first diverge, nil if match 171 | 172 | ;;sequence predicates 173 | ;;predicate should take as many args as sequences passed 174 | (every #'evenp '(1 2 3)) => NIL 175 | (some #'evenp '(1 2 3)) => T 176 | (notany #'evenp '(1 2 3)) => NIL 177 | (notevery #'evenp '(1 2 3) => T 178 | 179 | (every #'> '(1 2 3) '(4 3 2)) => NIL 180 | (some #'> '(1 2 3) '(4 3 2)) => T 181 | (notany #'> '(1 2 3) '(4 3 2)) => NIL 182 | (notevery #'> '(1 2 3) '(4 3 2)) => T 183 | 184 | ;;sequence mapping functions 185 | ;;takes n-arg function and n sequences, returns new sequence applying elements of each 186 | (map 'vector #'* #(1 2 3) #(10 9 8)) => #(10 18 24) 187 | ;;like map, instead it places results in sequence passed as first arg 188 | (map-into *seq* #'+ '(1 2 3) '(4 5 6)) => #(5 7 9) 189 | 190 | ;;map over a sequence, apply 2 arg func to first 2 elements, then returned value with next 191 | ;;takes keyword args, :key :from-end :start :end and :initial-value 192 | (reduce #'+ '(1 2 3 4)) => 10 193 | 194 | 195 | ;;working with lists 196 | 197 | ;;slicing and dicing 198 | (destructuring-bind (x y z) '(1 2 3) 199 | (list :x x :y y :z z)) => (:X 1 :Y 2 :Z 3) 200 | 201 | ;;lists 202 | ;;cons cell 203 | (cons 1 2) => (1 . 2) 204 | (car (cons 1 2)) => 1 205 | (cdr (cons 1 2)) => 2 206 | (defparameter *cons* (cons 1 2)) 207 | (setf (car *cons*) 10 => 10 ;*cons* => (10 . 2) 208 | 209 | ;;building lists 210 | (cons 1 nil) => (1) 211 | (cons 1 (cons 2 nil)) => (1 2) 212 | (list 1) => (1) 213 | (list 1 2) => (1 2) 214 | (defparameter *list* (list 1 2 3)) 215 | (first *list*) => 1 216 | (rest *list*) => (2 3) 217 | (first (rest *list*)) => 2 218 | 219 | (append '(1 2) '(3 4)) => (1 2 3 4) ;takes any number of lists 220 | (nconc '(1 2) '(3 4)) => (1 2 3 4) ;recycling version of append, builds on first list 221 | 222 | (revappend x y) ;same as (append (reverse x) y) 223 | (nreconc x y) ;same as (nconc (reverse x) y) 224 | 225 | (defparameter *list0* '(1 2)) 226 | (defparameter *list1* '(3 4)) 227 | (defparameter *list2* (append *list0* *list1*)) 228 | *list2* => '(1 2 3 4) 229 | ;shares structure of given lists by returning pointers to them 230 | (setf (first *list1*) 0) => 0 231 | *list1* => (0 4) 232 | *list2* => (1 2 0 4) 233 | 234 | (push 3 *list0*) => (3 1 2) ;push on front of place 235 | (pushnew 2 *list0*) => (3 2 1) ;push onto list if not already there 236 | (pop *list0*) => 3 ;*list* => (1 2) 237 | 238 | ;;build list and return, recycling idiom 239 | (let ((result nil)) 240 | (dotimes (i 4) 241 | (push i result)) 242 | (nreverse result)) => (0 1 2 3) 243 | 244 | *list1* => (0 4) 245 | *list2* => (1 2 0 4) 246 | ;;idiomatic use of recycling remove, changes shared structure as well 247 | (setf *list2* (delete 4 *list2*)) => (1 2 0) 248 | *list1* => (0) 249 | 250 | ;;list manipulating functions, all setf'able 251 | car, cdr, caar, cadr, caadr ... 252 | first ... tenth 253 | (first '(1 2 3)) => 1 254 | (rest '(1 2 3)) => (2 3) 255 | (nth 0 '(1 2 3)) => 1 256 | (nthcdr 1 '(1 2 3)) => (2 3) 257 | 258 | (defparameter *list* '(1 2 3 4)) 259 | (last *list*) => 4 260 | (butlast *list*) => (1 2 3) ;recycling version is nbutlast 261 | (defparameter *list2* (cddr *list*)) ;*list2* => (3 4) 262 | (ldiff *list* *list2*) => (1 2) ;list difference, checks shared structure, returns up to 263 | (ldiff *list* '(3 4)) => (1 2 3 4) ;no match, sunlist not eq to part of list 264 | (tailp *list2* *list*) => T ;returns true if object shares structure of list 265 | (tailp '(3 4) *list*) => nil ;not eq 266 | 267 | (list* 1 2 3 '(4 5)) => (1 2 3 4 5) ;list/append, builds list with final list as cdr 268 | 269 | (consp '(1 . 2)) => T ;test if cons cell 270 | (atom '(1 . 2)) => nil ;tests if not a cons cell 271 | (listp '(1 . 2)) => T ;test if cons cell or nill 272 | (null '()) => T ;test if nill, same as not, but preferable when testing empty list 273 | 274 | ;;mapping functions for lists 275 | (mapcar #'(lambda (x) (* 2 x)) '(1 2 3)) => (2 4 6) ;apply function to each element 276 | (mapcar #'+ '(1 2 3) '(4 5 6)) => (5 7 9) ;takes as many lists as function args 277 | (mapcar #'cons '(1 2) '(3 4)) => ((1 . 3) (2 . 4)) 278 | 279 | (mapcan #'cons '(1 2) '(3 4)) => (1 2 . 4) ;like mapcar, but uses nconc to build list 280 | ;;returns first list, useful for side effects 281 | (mapc #'(lambda (x y) (format t "~a " (* x y))) '(1 2) '(3 4)) => (1 2) ;prints 3 8 282 | 283 | (maplist #'append '(1 2 3) '(4 5 6) '(7 8 9)) ;applied to successive sublists 284 | => ((1 2 3 4 5 6 7 8 9) (2 3 5 6 8 9) (3 6 9)) 285 | (mapcon #'list '(1 2 3)) => ((1 2 3) (2 3) (3)) ;like maplist, but uses nconc to build list 286 | ;;returns first list, use rest of list 287 | (defparameter *acc* nil) 288 | (mapl #'(lambda (x) (push x *acc*)) '(1 2 3)) => (1 2 3) ;*acc* => ((3) (2 3) (1 2 3)) 289 | -------------------------------------------------------------------------------- /sections/iterate.md: -------------------------------------------------------------------------------- 1 | ### [iterate:iter] \[clauses\*\] forms\* 2 | 3 | A powerful iteration facility that provides abstractions for 4 | many common iteration patterns and allows for the definition 5 | of additional patterns. While it is similar to [loop], 6 | *iterate* offers a more Lisp-like syntax and enhanced 7 | extensibility. 8 | 9 | ## Numerical Iteration 10 | 11 | #### [repeat][iterate:repeat] n 12 | 13 | Iterate loop *n* times. If *n* is <= 0 the loop will not execute. 14 | 15 | ~~~ 16 | (iter (repeat 5) 17 | (print 'hello)) ;=> NIL [prints HELLO five times] 18 | ~~~ 19 | 20 | #### [for][iterate:for] var sequence-keywords 21 | 22 | Iterate over a sequence of numbers with a variable and one 23 | or more keywords that provide the bounds and step size of 24 | the iteration. Valid *sequence-keywords* are: `from`, 25 | `upfrom`, `downfrom`, `to`, `downto`, `above`, `below` and `by`. 26 | 27 | ~~~ 28 | (for i from 5) ;i => 5 6 7 ... (same as upfrom) 29 | (for i downfrom 0) ;i => 0 -1 -2 ... 30 | (for i from 1 to 3) ;i => 1 2 3 31 | (for i from 5 downto 3) ;i => 5 4 3 32 | (for i from 1 below 3) ;i => 1 2 33 | (for i from 3 above 1) ;i => 3 2 34 | (for i from 1 to 3 by 2) ;i => 1 3 35 | (for i from 1 below 3 by 2) ;i => 1 36 | ~~~ 37 | 38 | 39 | ## Sequence Iteration 40 | 41 | The *step-function*, which defaults to [cdr], is used to 42 | obtain the next sublist. 43 | 44 | Valid *sequence-keywords* are as before: `from`, `upfrom`, 45 | `downfrom`, `to`, `downto`, `above`, `below` and 46 | `by`. In addition, `with-index` takes a symbol as argument 47 | and uses it for the index variable. 48 | 49 | #### [for][iterate:for...in] var __in__ list \[__by__ step-function\] 50 | 51 | Set *var* to successive elements of *list*. 52 | 53 | ~~~ 54 | (iter (for x in '(a b c d) by #'cddr) 55 | (collect x)) ;=> (A C) 56 | ~~~ 57 | 58 | #### [for][iterate:for...on] var __on__ list \[__by__ step-function\] 59 | 60 | Set *var* to successive sublists of *list*. 61 | 62 | ~~~ 63 | (iter (for x on '(a b c)) 64 | (collect x)) ;=> ((A B C) (B C) (C)) 65 | ~~~ 66 | 67 | #### [for][iterate:for...in-sequence] var __in-sequence__ seq sequence-keywords 68 | 69 | Set *var* to successive elements of *seq*. 70 | 71 | ~~~ 72 | (iter (for x in-sequence '(a b c) with-index i) 73 | (collect (list i x))) ;=> ((0 A) (1 B) (2 C)) 74 | ~~~ 75 | 76 | #### [for][iterate:for...index-of-sequence] var __index-of-sequence__ sequence sequence-keywords 77 | 78 | Set *var* to the index number of *sequence* element. 79 | 80 | ~~~ 81 | (iter (for i index-of-sequence #(a b c)) 82 | (collect i)) ;=> (0 1 2) 83 | ~~~ 84 | 85 | #### [for][iterate:for...in-vector] var __in-vector__ vector sequence-keywords 86 | 87 | Set *var* to successive elements of *vector*. 88 | 89 | ~~~ 90 | (iter (for x in-vector #(a b c)) 91 | (collect x)) ;=> (A B C) 92 | ~~~ 93 | 94 | #### [for][iterate:for...index-of-vector] var __index-of-vector__ vector sequence-keywords 95 | 96 | Set *var* to the index number of *vector* element. 97 | 98 | ~~~ 99 | (iter (for i index-of-vector #(a b c)) 100 | (collect i)) ;=> (0 1 2) 101 | ~~~ 102 | 103 | #### [for][iterate:for...in-string] var __in-string__ string sequence-keywords 104 | 105 | Set *var* to successive elements of *string*. 106 | 107 | ~~~ 108 | (iter (for x in-string "hello" downfrom 4) 109 | (collect x)) ;=> (#\o #\l #\l #\e #\h) 110 | ~~~ 111 | 112 | #### [for][iterate:for...index-of-string] var __index-of-string__ string sequence-keywords 113 | 114 | Set *var* to the index number of *string* character. 115 | 116 | ~~~ 117 | (iter (for i index-of-string "hello" downfrom 4) 118 | (collect i)) ;=> (4 3 2 1 0) 119 | ~~~ 120 | 121 | #### [for][iterate:for...in-hashtable] \(key value\) __in-hashtable__ table 122 | 123 | Iterate over the *keys* and *values* of a [hash-table]. 124 | 125 | ~~~ 126 | (setf ht (alexandria:plist-hash-table '(:a 1 :b 2))) 127 | (iter (for (key val) in-hashtable ht) 128 | (collect (list key val))) ;=> ((:A 1) (:B 2)) 129 | ~~~ 130 | 131 | #### [for][iterate:for...in-package] var __in-package__ package \[__external-only__ ext\] 132 | 133 | Iterate over all symbols in a [package], or only external 134 | symbols if specified. 135 | 136 | ~~~ 137 | (iter (for sym in-package :iterate external-only t) 138 | (collect sym)) :=> (SUM FIRST-ITERATION-P NCONCING FIRST-TIME-P ...) 139 | ~~~ 140 | 141 | #### [for][iterate:for...in-packages] \(sym access-type pkg\) __in-packages__ \(packages\) \[__having-access__ \(symbol-types\)\] 142 | 143 | Iterates over all symbols from the list of *packages* and 144 | having visibility given by *symbol-types*, which defaults to 145 | the list `(:external :internal :inherited)`. 146 | 147 | ~~~ 148 | (iter (for (sym access-type pkg) in-packages '(:iterate) having-access (:external)) 149 | (collect (list sym access-type pkg))) 150 | ~~~ 151 | 152 | #### [for][iterate:for...in-file] var __in-file__ name \[__using__ reader\] 153 | 154 | Opens the file *name* ([string] or [pathname]) and iterate 155 | over its contents. *reader* defaults to [read] and will bind 156 | *var* to successive forms in the file. The file is closed no 157 | matter how the iterate loop exits. 158 | 159 | ~~~ 160 | (iter (for line in-file "/etc/passwd" using #'read-line) 161 | (collect line)) ;=> ("root:*:0:0:System Administrator:/var/root:/bin/sh" ...) 162 | ~~~ 163 | 164 | #### [for][iterate:for...in-stream] var __in-stream__ stream \[__using__ reader\] 165 | 166 | Like [for...in-file][iterate:for...in-file] except that 167 | *stream* should be an existing [stream] object that supports 168 | input operations. 169 | 170 | ~~~ 171 | (with-input-from-string (in "hello 1 2 three") 172 | (iter (for sym in-stream in) 173 | (collect line))) ;=> (HELLO 1 2 THREE) 174 | ~~~ 175 | 176 | ## Variable Binding 177 | 178 | #### [with][iterate:with] var \[__=__ value\] 179 | 180 | Causes *var* to be bound to *value* before the loop body is entered. 181 | 182 | ~~~ 183 | (setf n 0) 184 | (iter (for x in '(a b c)) 185 | (with i = n) 186 | (incf n) 187 | (collect (list i x))) ;=> ((0 A) (0 B) (0 C)) 188 | ~~~ 189 | 190 | #### [for][iterate:for...=] var __=__ form 191 | 192 | On each iteration, *form* is evaluated and *var* is set to its value. 193 | 194 | ~~~ 195 | (setf n 0) 196 | (iter (for x in '(a b c)) 197 | (for i = n) 198 | (incf n) 199 | (collect (list i x))) ;=> ((0 A) (1 B) (2 C)) 200 | ~~~ 201 | 202 | #### [for][iterate:for...initially...then] var __initially__ init-expr __then__ then-expr 203 | 204 | Before loop begins, *var* is set to *init-expr*; after the 205 | first iteration, it is set to *then-expr*. 206 | 207 | ~~~ 208 | (iter (repeat 4) 209 | (for i initially 10 then (1+ i)) 210 | (collect i)) ;=> (10 11 12 13) 211 | ~~~ 212 | 213 | #### [for][iterate:for...first...then] var __first__ first-expr __then__ then-expr 214 | 215 | On the first iteration, *var* is set to *init-form*; on 216 | subsequent iterations, it is set to *then-expr*. This 217 | differs from [for...initially][iterate:for...initially...then] 218 | in that *var* is set inside the loop body. 219 | 220 | 221 | #### [for][iterate:for...previous] pvar __previous__ var \[__initially__ init\] \[__back__ n\] 222 | 223 | Sets *pvar* to the previous value of *var*, another loop variable. 224 | 225 | ~~~ 226 | (iter (for x in '(1 2 3)) 227 | (for y previous x initially 0) 228 | (collect (list x y))) ;=> ((1 0) (2 1) (3 2)) 229 | ~~~ 230 | 231 | 232 | ## Accumulate 233 | 234 | #### [collect][iterate:collect] value \[__into__ var __at__ place __result-type__ type\] 235 | 236 | Returns a sequence of *values* produced from each 237 | iteration. Each value is *placed* in the collected sequence 238 | at the `start` or `end` (default). 239 | 240 | ~~~ 241 | (iter (for i in '(1 2 3)) 242 | (collect x) ;=> (1 2 3) 243 | 244 | (iter (for i in '(1 2 3)) 245 | (collect x at start) ;=> (3 2 1) 246 | ~~~ 247 | 248 | #### [adjoining][iterate:adjoining] value \[__into__ var __test__ test __at__ place __result-type__ type\] 249 | 250 | Like [collect][iterate:collect], but only adds the *value* 251 | if it is not already present. 252 | 253 | ~~~ 254 | (iter (for i in '(1 2 3 2 3 3 1)) 255 | (adjoining i)) ;=> (1 2 3) 256 | ~~~ 257 | 258 | #### [appending][iterate:appending] value \[__into__ var __at__ place\] 259 | 260 | Like [collect][iterate:collect], but using [append]. 261 | 262 | #### [nconcing][iterate:nconcing] value \[__into__ var __at__ place\] 263 | 264 | Like [collect][iterate:collect], but using [nconc]. 265 | 266 | #### [unioning][iterate:unioning] value \[__into__ var __test__ test __at__ place\] 267 | 268 | Like [collect][iterate:collect], but using [union]. Assumes 269 | that the *value* contains no duplicates. 270 | 271 | #### [nunioning][iterate:nunioning] value \[__into__ var __test__ test __at__ place\] 272 | 273 | Like [collect][iterate:collect], but using [nunion]. Assumes 274 | that the *value* contains no duplicates. 275 | 276 | #### [accumulate][iterate:accumulate] value __by__ fn \[__initial-value__ init-val __into__ var\] 277 | 278 | The general-purpose accumulation clause. Function *fn* takes 279 | two arguments, the *value* and the value accumulated so far 280 | in the iteration, and it should return the updated value. If 281 | no *initial-value* is supplied, [nil] is used. 282 | 283 | 284 | ## Reduce 285 | 286 | An iteration pattern in which the results of successive 287 | applications of a binary operation are accumulated. 288 | 289 | #### [sum][iterate:sum] value \[__into__ var\] 290 | 291 | On each iteration, *value* is added to a variable, which is 292 | initially bound to zero. 293 | 294 | ~~~ 295 | (iter (for i in '(1 2 3 4)) 296 | (sum i)) ;=> 10 297 | ~~~ 298 | 299 | #### [multiply][iterate:multiply] value \[__into__ var\] 300 | 301 | Like [sum][iterate:sum], but the initial value of the result 302 | is 1, and is updated by multiplying *value* into it. 303 | 304 | ~~~ 305 | (iter (for i in '(1 2 3 4)) 306 | (multiply i)) ;=> 24 307 | ~~~ 308 | 309 | #### [counting][iterate:counting] value \[__into__ var\] 310 | 311 | On each iteration, if *value* evaluates to non-[nil], 312 | increment the counter, which initially starts at zero. 313 | 314 | ~~~ 315 | (iter (for x in '(a 2 nil d)) 316 | (counting x)) ;=> 3 317 | ~~~ 318 | 319 | #### [maximize][iterate:maximize] value \[__into__ var\] 320 | 321 | Evaluate *value* on each iteration and store the maximum in 322 | the accumulation variable. 323 | 324 | ~~~ 325 | (iter (for i in '(1 4 2 2)) 326 | (maximize i)) ;=> 4 327 | ~~~ 328 | 329 | #### [minimize][iterate:minimize] value \[__into__ var\] 330 | 331 | Evaluate *value* on each iteration and store the minimum in 332 | the accumulation variable. 333 | 334 | ~~~ 335 | (iter (for i in '(1 4 2 2)) 336 | (minimize i)) ;=> 1 337 | ~~~ 338 | 339 | #### [reducing][iterate:reducing] value __by__ fn \[__initial-value__ init-val __into__ var\] 340 | 341 | The general way to perform reductions. Function *fn* takes 342 | two arguments, the first is the value computed so far and 343 | the second is the *value*. It should return a new value. 344 | 345 | ~~~ 346 | (iter (for i in '(1 2 3 4)) 347 | (reducing i by #'(lambda (x y) (+ x y)))) ;=> 10 348 | ~~~ 349 | 350 | 351 | ## Tests 352 | 353 | #### [finding][iterate:finding...such-that] value __such-that__ test \[__into__ var __on-failure__ failure-value\] 354 | 355 | If *test* ever evaluates to non-[nil], the loop is stopped 356 | and the current *value* is returned. 357 | 358 | ~~~ 359 | (iter (for i in '(1 2 3)) 360 | (finding i such-that #'oddp)) ;=> 1 361 | 362 | (iter (for i in '(1 2 3)) 363 | (finding i such-that #'evenp)) ;=> 2 364 | ~~~ 365 | 366 | #### [finding][iterate:finding...maximizing] expr __maximizing__ m-expr \[__into__ var\] 367 | 368 | Computes the maximum value of *m-expr* over all iterations, 369 | and returns the value of the corresponding *expr*. 370 | 371 | ~~~ 372 | (iter (for lst in '((a b c) (x y) (1 2 3 4))) 373 | (finding lst maximizing (length lst))) ;=> (1 2 3 4) 374 | ~~~ 375 | 376 | #### [finding][iterate:finding...minimizing] expr __minimizing__ m-expr \[__into__ var\] 377 | 378 | Computes the minimum value of *m-expr* over all iterations, 379 | and returns the value of the corresponding *expr*. 380 | 381 | ~~~ 382 | (iter (for lst in '((a b c) (x y) (1 2 3 4))) 383 | (finding lst minimizing #'length)) ;=> (X Y) 384 | ~~~ 385 | 386 | #### [first-iteration-p][iterate:first-iteration-p] 387 | 388 | Returns [t] in the first cycle of the loop, otherwise [nil]. 389 | 390 | ~~~ 391 | (iter (repeat 3) 392 | (collect (first-iteration-p))) ;=> (T NIL NIL) 393 | ~~~ 394 | 395 | #### [first-time-p][iterate:first-time-p] 396 | 397 | Returns [t] the first time the expression is evaluated, and 398 | then [nil] forever. 399 | 400 | ~~~ 401 | (iter (for i in '(1 2 3)) 402 | (collect (list (first-time-p) i))) ;=> ((T 1) (NIL 2) (NIL 3)) 403 | ~~~ 404 | 405 | #### [always][iterate:always] expr 406 | 407 | If *expr* ever evaluates to [nil], then [nil] is immediately 408 | returned; the epilogue code is not executed. 409 | 410 | ~~~ 411 | (iter (for i in '(1 2 3 4)) 412 | (always (evenp i))) ;=> NIL 413 | ~~~ 414 | 415 | #### [never][iterate:never] expr 416 | 417 | Like `(always (not expr))`, but does not influence the last 418 | value returned by a possible other always clause. 419 | 420 | ~~~ 421 | (iter (for i in '(2 4 6 8)) 422 | (always (evenp i))) ;=> T 423 | ~~~ 424 | 425 | #### [thereis][iterate:thereis] expr 426 | 427 | If *expr* is ever non-[nil], its value is immediately returned 428 | without running epilogue code. 429 | 430 | ~~~ 431 | (iter (for i in '(1 2 3 4)) 432 | (thereis (characterp i))) ;=> NIL 433 | ~~~ 434 | 435 | 436 | ## Control Flow 437 | 438 | Alter the usual flow of control in a loop. 439 | 440 | #### [finish][iterate:finish] 441 | 442 | Stops the loop and runs the epilogue code. 443 | 444 | ~~~ 445 | (iter (for x in '(a b c 1 2 3)) 446 | (if (numberp x) 447 | (finish)) 448 | (collect x)) ;=> (A B C) 449 | ~~~ 450 | 451 | #### [leave][iterate:leave] \[value\] 452 | 453 | Immediately returns *value* (default [nil]) from the loop, 454 | skipping the epilogue code. Equivalent to using 455 | [return-from]. 456 | 457 | ~~~ 458 | (iter (for x in '(a b c 1 2 3)) 459 | (if (numberp x) 460 | (leave x))) ;=> 1 461 | ~~~ 462 | 463 | #### [next-iteration][iterate:next-iteration] 464 | 465 | Skips the remainder of the loop body and begins the next iteration. 466 | 467 | ~~~ 468 | (iter (for x in '(a b c 1 2 d e)) 469 | (if (numberp x) 470 | (next-iteration)) 471 | (collect x)) ;=> (A B C D E) 472 | ~~~ 473 | 474 | #### [while][iterate:while] expr 475 | 476 | If *expr* ever evaluates to [nil], the loop stops and the 477 | epilogue code is run. Equivalent to `(if (not expr) (finish))`. 478 | 479 | ~~~ 480 | (iter (for x in '(1 2 a b 3 4)) 481 | (while (numberp x)) 482 | (collect x)) ;=> (1 2) 483 | ~~~ 484 | 485 | #### [until][iterate:until] expr 486 | 487 | Equivalent to `(if expr (finish))`. 488 | 489 | ~~~ 490 | (iter (for x in '(a b c 1 2 d e)) 491 | (until (numberp x)) 492 | (collect x)) ;=> (A B C) 493 | ~~~ 494 | 495 | #### [if-first-time][iterate:if-first-time] then \[else\] 496 | 497 | If this clause is executed for the first time in the iterate 498 | form, the *then* code is evaluated; otherwise the *else* 499 | code is evaluated. 500 | 501 | ~~~ 502 | (iter (for i in '(1 2 3 4)) 503 | (collect (if-first-time 504 | nil 505 | i))) ;=> (NIL 2 3 4) 506 | ~~~ 507 | 508 | 509 | ## Code Placement 510 | 511 | For control over where code is placed in a loop. 512 | 513 | * [Problems with Code Movement](http://common-lisp.net/project/iterate/doc/Problems-with-Code-Movement.html) 514 | 515 | #### [initially][iterate:initially] forms\* 516 | 517 | Place *forms* in the prologue section of the loop. They are 518 | executed once, before the loop body is entered. 519 | 520 | #### [after-each][iterate:after-each] forms\* 521 | 522 | Place *forms* at the end of the loop body, where they are 523 | executed after each iteration. 524 | 525 | #### [else][iterate:else] forms\* 526 | 527 | Place *forms* in the epilogue section of the loop, where 528 | they are executed if this *else* clause is never met during 529 | execution of the loop and the loop terminates normally. 530 | 531 | #### [finally][iterate:finally] forms\* 532 | 533 | Place *forms* in the epilogue section of the loop, where 534 | they are executed after the loop has terminated normally. 535 | 536 | #### [finally-protected][iterate:finally-protected] forms\* 537 | 538 | Place *forms* in the second form of an [unwind-protect] 539 | outside the loop. They are always executed after the loop 540 | has terminated, regardless of how the termination occurred. 541 | 542 | #### [in][iterate:in] name &forms\* 543 | 544 | Evaluate *forms* as if they were part of the iterate form *name*. 545 | 546 | ~~~ 547 | (iter outer (for i in '(1 2 3)) 548 | (iter (for j in '(10 20)) 549 | (in outer (collect (* i j))))) ;=> (10 20 20 40 30 60) 550 | ~~~ 551 | 552 | 553 | ## Destructuring 554 | 555 | In many places where a variable is expected, a list can be 556 | written instead. The value to be assigned is destructured 557 | according to the pattern described by the list. 558 | 559 | ~~~ 560 | (for (x y) in '((1 2) (3 4))) 561 | (for (key . val) in alist) 562 | (for (values (a . b) c d) = (three-valued-function ...)) 563 | ~~~ 564 | 565 | #### [dsetq][iterate:dsetq] template expr 566 | 567 | Performs destructuring of *expr* using *template*. May be 568 | used outside of an `iterate` form. Yields the primary value 569 | of *expr*. 570 | 571 | ~~~ 572 | (dsetq (values a b) (floor 4.5)) ;=> 4 573 | (list a b) ;=> (4 0.5) 574 | ~~~ 575 | 576 | 577 | ## Extend 578 | 579 | Write new clauses that embody new iteration patterns. 580 | 581 | * [Generators](http://common-lisp.net/project/iterate/doc/Generators.html) 582 | * [Rolling Your Own](http://common-lisp.net/project/iterate/doc/Rolling-Your-Own.html) 583 | 584 | #### [for][iterate:for...next] var __next__ expr 585 | 586 | Set *var* to *expr* each time through the 587 | loop. Destructuring is performed. When the clause is used as 588 | a generator, *expr* is the code that is executed when (next 589 | *var*) is encountered. 590 | 591 | #### [for][iterate:for...do-next] var __do-next__ form 592 | 593 | Evaluate *form* each time through the loop. Its value is not 594 | set to *var*; that's done in *form*. *var* is only present 595 | so that `iterate` knows it is a driver variable. 596 | 597 | ## Advanced 598 | 599 | #### [defmacro-clause][iterate:defmacro-clause] arglist body-form 600 | 601 | Defines a new `iterate` clause. *arglist* is a list of 602 | symbols which are alternating keywords and arguments. 603 | 604 | ~~~ 605 | (defmacro-clause (MULTIPLY expr &optional INTO var) 606 | `(reducing ,expr by #'* into ,var initial-value 1)) 607 | ~~~ 608 | 609 | #### [defmacro-driver][iterate:defmacro-driver] arglist body-form 610 | 611 | Defines a driver clause in both the for and generate forms, 612 | and provides a parameter generate which body can examine to 613 | determine how it was invoked. 614 | 615 | #### [defsynonym][iterate:defsynonym] syn word 616 | 617 | Makes *syn* a synonym for the existing iterate keyword *word*. 618 | 619 | #### [defclause-sequence][iterate:defclause-sequence] element-name index-name &keys\* 620 | 621 | Provides a simple way to define sequence clauses. Generates 622 | two clauses, one for iterating over the sequence's elements, 623 | the other for iterating over its indices. 624 | 625 | #### [display-iterate-clauses][iterate:display-iterate-clauses] \[clause-spec\] 626 | 627 | Displays a list of [iterate][iter] clauses. If *clause-spec* 628 | is not provided, all clauses are shown. 629 | --------------------------------------------------------------------------------