Begin reworking koan list

.koans

@@ -1,31 +1,32 @@
 (
- :asserts
- :nil-false-empty
- :evaluation
- :atoms-vs-lists
- :special-forms
- :lists
- :arrays
- :vectors
- :multiple-values
- :equality-distinctions
- :hash-tables
- :functions
- :strings
- :structures
- :iteration
- :mapcar-and-reduce
- :control-statements
- :condition-handlers
- :loops
- :triangle-project
- :scoring-project
- :format
- :type-checking
- :clos
- :std-method-comb
- :dice-project
- :macros
- :scope-and-extent
- #+quicklisp :threads
+ #:asserts
+ #:nil-false-empty
+ #:evaluation
+ #:atoms-vs-lists
+ #:let
+ #:basic-macros
+ #:lists
+ #:arrays
+ #:vectors
+ #:multiple-values
+ #:equality-distinctions
+ #:hash-tables
+ #:functions
+ #:strings
+ #:structures
+ #:iteration
+ #:mapcar-and-reduce
+ #:control-statements
+ #:condition-handlers
+ #:loops
+ #:triangle-project
+ #:scoring-project
+ #:format
+ #:type-checking
+ #:clos
+ #:std-method-comb
+ #:dice-project
+ #:macros
+ #:scope-and-extent
+ #+quicklisp #:threads
 )

koans/arrays.lisp

@@ -1,46 +1,43 @@
-;;   Copyright 2013 Google Inc.
-;;
-;;   Licensed under the Apache License, Version 2.0 (the "License");
-;;   you may not use this file except in compliance with the License.
-;;   You may obtain a copy of the License at
-;;
-;;       http://www.apache.org/licenses/LICENSE-2.0
-;;
-;;   Unless required by applicable law or agreed to in writing, software
-;;   distributed under the License is distributed on an "AS IS" BASIS,
-;;   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-;;   See the License for the specific language governing permissions and
-;;   limitations under the License.
-
-
-;; see http://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node157.html
+;;; Copyright 2013 Google Inc.
+;;;
+;;; Licensed under the Apache License, Version 2.0 (the "License");
+;;; you may not use this file except in compliance with the License.
+;;; You may obtain a copy of the License at
+;;;
+;;;     http://www.apache.org/licenses/LICENSE-2.0
+;;;
+;;; Unless required by applicable law or agreed to in writing, software
+;;; distributed under the License is distributed on an "AS IS" BASIS,
+;;; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+;;; See the License for the specific language governing permissions and
+;;; limitations under the License.
 
+;;; See http://www.gigamonkeys.com/book/collections.html
 
 (define-test test-basic-array-stuff
-    " the first block of code defines an 8x8 array, then fills
-      the elements with a checkerboard pattern"
-  (let ((chess-board))
-    (setf chess-board (make-array '(8 8)))
-    "this dotimes is an iterator which loops x over integers 0 to 7"
+  "We define an 8x8 array and then fill it with a checkerboard pattern."
+  (let ((chess-board (make-array '(8 8))))
+    "(DOTIMES (X 8) ...) will iterate with X taking values from 0 to 7."
     (dotimes (x 8)
       (dotimes (y 8)
-        (if (evenp (+ x y))
-            (setf (aref chess-board x y) :black)
-            (setf (aref chess-board x y) :white)
-            )))
+        "AREF stands for \"array reference\"."
+        (setf (aref chess-board x y) (if (evenp (+ x y)) :black :white))))
     (assert-true (typep chess-board 'array))
-    (assert-equal (aref chess-board 0 0) ___)
-    (assert-equal (aref chess-board 2 3) ___)
-    "array-rank returns the number of dimensions of the array"
-    (assert-equal ___ (array-rank chess-board))
-    "array-dimensions returns a list of the cardinality of the array dims"
-    (assert-equal ___ (array-dimensions chess-board))
-    (assert-equal ___ (array-total-size chess-board))))
+    (assert-equal (aref chess-board 0 0) ____)
+    (assert-equal (aref chess-board 2 3) ____)
+    "ARRAY-RANK returns the number of dimensions of the array."
+    (assert-equal ____ (array-rank chess-board))
+    "ARRAY-DIMENSIONS returns a list of the cardinality of the array dims"
+    (assert-equal ____ (array-dimensions chess-board))
+    "ARRAY-TOTAL-SIZE returns the total number of elements in the array."
+    (assert-equal ____ (array-total-size chess-board))))
 
 (define-test test-make-your-own-array
-    "make your own array that meets the specifications below."
-  (let ((color-cube nil))
-    "you may need to modify your array after you make it"
+  "Make your own array that meets the specifications below."
+  (let ((color-cube ____))
+    "You may need to modify your array after you create it."
+    (setf (____ color-cube ____ ____ ____) ____
+          (____ color-cube ____ ____ ____) ____)
     (if (typep color-cube '(simple-array T (3 3 3)))
         (progn
           (assert-equal 3 (array-rank color-cube))
@@ -50,28 +47,24 @@
           (assert-equal (aref color-cube 2 1 0) :white))
         (assert-true nil))))
 
-
 (define-test test-adjustable-array
-    "one may build arrays that can change size"
+  "The size of an array does not need to be constant."
   (let ((x (make-array '(2 2) :initial-element 5 :adjustable t)))
     (assert-equal (aref x 1 0) ____)
     (assert-equal (array-dimensions x) ____)
     (adjust-array x '(3 4))
     (assert-equal (array-dimensions x) ____)))
 
-
 (define-test test-make-array-from-list
-  (let ((x))
-    (setf x (make-array '(4) :initial-contents '(:one :two :three :four)))
+  "One can create arrays from list structure."
+  (let ((x (make-array '(4) :initial-contents '(:one :two :three :four))))
     (assert-equal (array-dimensions x) ____)
     (assert-equal ____ (aref x 0))))
 
-
 (define-test test-row-major-index
-    "row major indexing is a way to access elements with a single integer,
-     rather than a list of integers"
-  (let ((my-array nil))
-    (setf my-array (make-array '(2 2 2 2)))
+  "Row major indexing is a way to access elements with a single integer,
+   rather than a list of integers."
+  (let ((my-array (make-array '(2 2 2 2))))
     (dotimes (i (* 2 2 2 2))
       (setf (row-major-aref my-array i) i))
     (assert-equal (aref my-array 0 0 0 0) ____)

koans/asserts.lisp

@@ -1,47 +1,65 @@
-;;   Copyright 2013 Google Inc.
-;;
-;;   Licensed under the Apache License, Version 2.0 (the "License");
-;;   you may not use this file except in compliance with the License.
-;;   You may obtain a copy of the License at
-;;
-;;       http://www.apache.org/licenses/LICENSE-2.0
-;;
-;;   Unless required by applicable law or agreed to in writing, software
-;;   distributed under the License is distributed on an "AS IS" BASIS,
-;;   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-;;   See the License for the specific language governing permissions and
-;;   limitations under the License.
+;;; Copyright 2013 Google Inc.
+;;;
+;;; Licensed under the Apache License, Version 2.0 (the "License");
+;;; you may not use this file except in compliance with the License.
+;;; You may obtain a copy of the License at
+;;;
+;;;     http://www.apache.org/licenses/LICENSE-2.0
+;;;
+;;; Unless required by applicable law or agreed to in writing, software
+;;; distributed under the License is distributed on an "AS IS" BASIS,
+;;; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+;;; See the License for the specific language governing permissions and
+;;; limitations under the License.
 
+;;;                       ╭╮         ╭╮ ///////
+;;;                       ┃┃         ┃┃///////
+;;;                       ┃┃╭┳━━┳━━╮ ┃┃╭┳━━┳━━┳━╮╭━━╮
+;;;                       ┃┃┣┫━━┫╭╮┃ ┃╰╯┫╭╮┃╭╮┃╭╮┫━━┫
+;;;                       ┃╰┫┣━━┃╰╯┃ ┃╭╮┫╰╯┃╭╮┃┃┃┣━━┃
+;;;                       ╰━┻┻━━┫╭━╯/╰╯╰┻━━┻╯╰┻╯╰┻━━╯
+;;;                             ┃┃ //////
+;;;                             ╰╯//////
 
-; Concept: What do you do to go through the lisp koans?  You fill in
-; the blanks, or otherwise fix the lisp code so that the
-; code within the 'define-test' blocks passes.
+;;; Welcome to the Lisp Koans.
+;;; May the code stored here influence your enlightenment as a programmer.
 
+;;; In order to progress, fill in the blanks, denoted via ____ in source code.
+;;; Sometimes, you will be asked to provide values that are equal to something.
 
-; In common lisp, "True" and "False" are represented by "t" and "nil".
-; More in a future lesson, but for now, consider t to be true,
-; and nil to be false.
+(define-test fill-in-the-blanks
+  (assert-equal ____ 2)
+  (assert-equal ____ 3.14)
+  (assert-equal ____ "Hello World"))
 
+;;; Sometimes, you will be asked to say whether something is true or false,
+;;; In Common Lisp, the canonical values for truth and falsehood are T and NIL.
 
 (define-test assert-true
-    "t is true.  Replace the blank with a t"
-    (assert-true ___))
+  (assert-true ____))
 
 (define-test assert-false
-    "nil is false"
-    (assert-false ___))
+  (assert-false ____))
 
-(define-test fill-in-the-blank
-    "sometimes you will need to fill the blank to complete"
-    (assert-equal 2 ___))
+(define-test true-or-false
+  (true-or-false? ____ (= 34 34))
+  (true-or-false? ____ (= 19 78)))
 
-(define-test fill-in-the-blank-string
-    (assert-equal ___ "hello world"))
+;;; Since T and NIL are symbols, you can type them in lowercase or uppercase;
+;;; by default, Common Lisp will automatically upcase them upon reading.
 
-(define-test test-true-or-false
-    "sometimes you will be asked to evaluate whether statements
-     are true (t) or false (nil)"
-    (true-or-false? ___ (equal 34 34))
-    (true-or-false? ___ (equal 19 78)))
+(define-test upcase-downcase
+  ;; Try inserting a lowercase t here.
+  (assert-equal ____ T)
+  ;; Try inserting an uppercase NIL here.
+  (assert-equal ____ nil))
 
+;;; Sometimes, you will be asked to provide a part of an expression that must be
+;;; either true or false.
+
+(define-test a-true-assertion
+  (assert-true (= ____ (+ 2 2))))
+
+(define-test a-false-assertion
+  (assert-false (= ____ (+ 2 2))))
 

koans/atoms-vs-lists.lisp

@@ -1,48 +1,43 @@
-;;   Copyright 2013 Google Inc.
-;;
-;;   Licensed under the Apache License, Version 2.0 (the "License");
-;;   you may not use this file except in compliance with the License.
-;;   You may obtain a copy of the License at
-;;
-;;       http://www.apache.org/licenses/LICENSE-2.0
-;;
-;;   Unless required by applicable law or agreed to in writing, software
-;;   distributed under the License is distributed on an "AS IS" BASIS,
-;;   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-;;   See the License for the specific language governing permissions and
-;;   limitations under the License.
-
-
-(define-test test-list-or-atom
-    "Lists in lisp are forms beginning and ending with rounded parentheses.
-     Atoms are symbols, numbers, or other forms usually separated by
-     white-space or parentheses.  The function 'listp' will return true if
-     the input is a list.  The function 'atom' will return true if the
-     input is an atom."
-  (true-or-false? ___ (listp '(1 2 3)))
-  (true-or-false? ___ (atom '(1 2 3)))
-
-  (true-or-false? ___ (listp '("heres" "some" "strings")))
-  (true-or-false? ___ (atom '("heres" "some" "strings")))
-
-  (true-or-false? ___ (listp "a string"))
-  (true-or-false? ___ (atom "a string"))
-
-  (true-or-false? ___ (listp 2))
-  (true-or-false? ___ (atom 2))
-
-  (true-or-false? ___ (listp '(("first" "list") ("second" "list"))))
-  (true-or-false? ___ (atom '(("first" "list") ("second" "list")))))
-
-
-(define-test test-empty-list-is-both-list-and-atom
-    "the empty list, nil, is unique in that it is both a list and an atom"
-  (true-or-false? ___ (listp nil))
-  (true-or-false? ___ (atom nil)))
-
-
-(define-test test-keywords
-    "symbols like :hello or :like-this are treated differently in lisp.
-     Called keywords, they are symbols that evaluate to themselves."
-  (true-or-false? ___ (equal :this-is-a-keyword :this-is-a-keyword))
-  (true-or-false? ___ (equal :this-is-a-keyword ':this-is-a-keyword)))
+;;; Copyright 2013 Google Inc.
+;;;
+;;; Licensed under the Apache License, Version 2.0 (the "License");
+;;; you may not use this file except in compliance with the License.
+;;; You may obtain a copy of the License at
+;;;
+;;;     http://www.apache.org/licenses/LICENSE-2.0
+;;;
+;;; Unless required by applicable law or agreed to in writing, software
+;;; distributed under the License is distributed on an "AS IS" BASIS,
+;;; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+;;; See the License for the specific language governing permissions and
+;;; limitations under the License.
+
+;;; Lists in lisp are forms beginning and ending with rounded parentheses.
+;;; Atoms are symbols, numbers, or other forms usually separated by whitespace
+;;; or parentheses.
+
+(define-test list-or-atom
+  ;; The function LISTP will return true if the input is a list.
+  ;; The function ATOM will return true if the input is an atom.
+  (true-or-false? ____ (listp '(1 2 3)))
+  (true-or-false? ____ (atom '(1 2 3)))
+  (true-or-false? ____ (listp '("heres" "some" "strings")))
+  (true-or-false? ____ (atom '("heres" "some" "strings")))
+  (true-or-false? ____ (listp "a string"))
+  (true-or-false? ____ (atom "a string"))
+  (true-or-false? ____ (listp 2))
+  (true-or-false? ____ (atom 2))
+  (true-or-false? ____ (listp '(("first" "list") ("second" "list"))))
+  (true-or-false? ____ (atom '(("first" "list") ("second" "list")))))
+
+(define-test the-duality-of-nil
+  ;; The empty list, NIL, is unique in that it is both a list and an atom.
+  (true-or-false? ____ (listp nil))
+  (true-or-false? ____ (atom nil)))
+
+(define-test keywords
+  ;; Symbols like :HELLO or :LIKE-THIS are keywords. They are treated
+  ;; differently in Lisp: they are constants that always evaluate to themselves.
+  (true-or-false? ____ (equal :this-is-a-keyword :this-is-a-keyword))
+  (true-or-false? ____ (equal :this-is-a-keyword ':this-is-a-keyword))
+  (true-or-false? ____ (equal :this-is-a-keyword :this-is-also-a-keyword)))