doc HtDP language additions for testing

svn: r9163

collects/scribblings/htdp-langs/advanced.scrbl

@@ -17,7 +17,7 @@
     (define intm-time (scheme time))))
 @(bd intm-define intm-define-struct intm-lambda intm-local intm-letrec intm-let intm-let* intm-time)
 
-@(define-syntax-rule (bbd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-require)
+@(define-syntax-rule (bbd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-check-expect beg-require)
    (begin
     (require (for-label lang/htdp-beginner))
     (define beg-define (scheme define))
@@ -26,8 +26,9 @@
     (define beg-if (scheme if))
     (define beg-and (scheme and))
     (define beg-or (scheme or))
+    (define beg-check-expect (scheme check-expect))
     (define beg-require (scheme require))))
-@(bbd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-require)
+@(bbd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-check-expect beg-require)
 
 
 @title[#:style 'toc]{Advanced Student}
@@ -36,7 +37,8 @@
 
 @schemegrammar*+qq[
 #:literals (define define-struct lambda cond else if and or empty true false require lib planet
-            local let let* letrec time begin begin0 set! delay shared recur when case unless)
+            local let let* letrec time begin begin0 set! delay shared recur when case unless
+            check-expect check-within check-error)
 [program (code:line def-or-expr ...)]
 [def-or-expr definition
              expr
@@ -69,6 +71,7 @@
       (and expr expr expr ...)
       (or expr expr expr ...)
       (time expr)
+      test-case
       empty
       (code:line id (code:comment #, @seclink["intermediate-id"]{identifier}))
       (code:line prim-op (code:comment #, @seclink["intermediate-lambda-prim-op"]{primitive operation}))
@@ -316,6 +319,16 @@ The same as Beginning's @|beg-and| and @|beg-or|.}
 The same as Intermediate's @|intm-time|.}
 
 
+@deftogether[(
+@defform[(check-expect expr expr)]
+@defform[(check-within expr expr expr)]
+@defform[(check-error expr expr)]
+)]{
+
+The same as Beginning's @|beg-check-expect|, etc.}
+
+
+
 @deftogether[(
 @defthing[empty empty?]
 @defthing[true boolean?]

collects/scribblings/htdp-langs/beginner-abbr.scrbl

@@ -4,7 +4,7 @@
           "prim-ops.ss"
           (for-label lang/htdp-beginner-abbr))
 
-@(define-syntax-rule (bd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-require)
+@(define-syntax-rule (bd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-check-expect beg-require)
    (begin
     (require (for-label lang/htdp-beginner))
     (define beg-define (scheme define))
@@ -13,8 +13,9 @@
     (define beg-if (scheme if))
     (define beg-and (scheme and))
     (define beg-or (scheme or))
+    (define beg-check-expect (scheme check-expect))
     (define beg-require (scheme require))))
-@(bd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-require)
+@(bd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-check-expect beg-require)
 
 
 @title[#:style 'toc]{Beginning Student with List Abbreviations}
@@ -22,7 +23,8 @@
 @declare-exporting[lang/htdp-beginner-abbr]
 
 @schemegrammar*+qq[
-#:literals (define define-struct lambda cond else if and or empty true false require lib planet)
+#:literals (define define-struct lambda cond else if and or empty true false require lib planet
+            check-expect check-within check-error)
 [program (code:line def-or-expr ...)]
 [def-or-expr definition
              expr
@@ -38,6 +40,7 @@
       (if expr expr expr)
       (and expr expr expr ...)
       (or expr expr expr ...)
+      test-case
       empty
       id
       (code:line #, @elem{@schemevalfont{'}@scheme[quoted]} (code:comment #, @seclink["beginner-abbr-quote"]{quoted value}))
@@ -164,6 +167,14 @@ The same as Beginning's @|beg-if|.}
 
 The same as Beginning's @|beg-and| and @|beg-or|.}
 
+@deftogether[(
+@defform[(check-expect expr expr)]
+@defform[(check-within expr expr expr)]
+@defform[(check-error expr expr)]
+)]{
+
+The same as Beginning's @|beg-check-expect|, etc.}
+
 @deftogether[(
 @defthing[empty empty?]
 @defthing[true boolean?]

collects/scribblings/htdp-langs/beginner.scrbl

@@ -10,10 +10,12 @@
 @declare-exporting[lang/htdp-beginner]
 
 @schemegrammar*+library[
-#:literals (define define-struct lambda cond else if and or empty true false require lib planet)
+#:literals (define define-struct lambda cond else if and or empty true false require lib planet
+            check-expect check-within check-error)
 [program (code:line def-or-expr ...)]
 [def-or-expr definition
              expr
+             
              library-require]
 [definition (define (id id id ...) expr)
             (define id expr)
@@ -26,6 +28,7 @@
       (if expr expr expr)
       (and expr expr expr ...)
       (or expr expr expr ...)
+      test-case
       empty
       id
       (code:line id (code:comment #, @seclink["beginner-id"]{identifier}))
@@ -219,6 +222,29 @@ value other than @scheme[true] or @scheme[false], it is an error.}
 
 @; ----------------------------------------------------------------------
 
+@section{Test Cases}
+
+@defform[(check-expect expr expr)]{
+
+A test case to check that the first @scheme[expr] produces the same
+value as the second @scheme[expr], where the latter is normally an
+immediate value.}
+
+@defform[(check-within expr expr expr)]{
+
+Like @scheme[check-expect], but with an extra expression that produces
+a number @scheme[_delta]. The test case checks that each number in the
+result of the first @scheme[expr] is within @scheme[_delta] of each
+corresponding number from the second @scheme[expr].}
+
+@defform[(check-error expr expr)]{
+
+A test case to check that the first @scheme[expr] signals an error,
+where the error messages matches the string produced by the second
+@scheme[expr].}
+
+@; ----------------------------------------------------------------------
+
 @section{@scheme[empty]}
 
 @defthing[empty empty?]{

collects/scribblings/htdp-langs/intermediate-lambda.scrbl

@@ -16,7 +16,7 @@
     (define intm-time (scheme time))))
 @(bd intm-define intm-define-struct intm-local intm-letrec intm-let intm-let* intm-time)
 
-@(define-syntax-rule (bbd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-require)
+@(define-syntax-rule (bbd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-check-expect beg-require)
    (begin
     (require (for-label lang/htdp-beginner))
     (define beg-define (scheme define))
@@ -25,8 +25,9 @@
     (define beg-if (scheme if))
     (define beg-and (scheme and))
     (define beg-or (scheme or))
+    (define beg-check-expect (scheme check-expect))
     (define beg-require (scheme require))))
-@(bbd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-require)
+@(bbd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-check-expect beg-require)
 
 
 @title[#:style 'toc]{Intermediate Student with Lambda}
@@ -35,7 +36,7 @@
 
 @schemegrammar*+qq[
 #:literals (define define-struct lambda cond else if and or empty true false require lib planet
-            local let let* letrec time)
+            local let let* letrec time check-expect check-within check-error)
 [program (code:line def-or-expr ...)]
 [def-or-expr definition
              expr
@@ -55,6 +56,7 @@
       (and expr expr expr ...)
       (or expr expr expr ...)
       (time expr)
+      test-case
       empty
       (code:line id (code:comment #, @seclink["intermediate-id"]{identifier}))
       (code:line prim-op (code:comment #, @seclink["intermediate-lambda-prim-op"]{primitive operation}))
@@ -167,6 +169,15 @@ The same as Beginning's @|beg-and| and @|beg-or|.}
 The same as Intermediate's @|intm-time|.}
 
 
+@deftogether[(
+@defform[(check-expect expr expr)]
+@defform[(check-within expr expr expr)]
+@defform[(check-error expr expr)]
+)]{
+
+The same as Beginning's @|beg-check-expect|, etc.}
+
+
 @deftogether[(
 @defthing[empty empty?]
 @defthing[true boolean?]

collects/scribblings/htdp-langs/intermediate.scrbl

@@ -4,7 +4,7 @@
           "prim-ops.ss"
           (for-label lang/htdp-intermediate))
 
-@(define-syntax-rule (bd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-require)
+@(define-syntax-rule (bd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-check-expect beg-require)
    (begin
     (require (for-label lang/htdp-beginner))
     (define beg-define (scheme define))
@@ -13,8 +13,9 @@
     (define beg-if (scheme if))
     (define beg-and (scheme and))
     (define beg-or (scheme or))
+    (define beg-check-expect (scheme check-expect))
     (define beg-require (scheme require))))
-@(bd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-require)
+@(bd beg-define beg-define-struct beg-cond beg-if beg-and beg-or beg-check-expect beg-require)
 
 @title[#:style 'toc]{Intermediate Student}
 
@@ -22,7 +23,7 @@
 
 @schemegrammar*+qq[
 #:literals (define define-struct lambda cond else if and or empty true false require lib planet
-            local let let* letrec time)
+            local let let* letrec time check-expect check-within check-error)
 [program (code:line def-or-expr ...)]
 [def-or-expr definition
              expr
@@ -43,6 +44,7 @@
       (and expr expr expr ...)
       (or expr expr expr ...)
       (time expr)
+      test-case
       empty
       (code:line id (code:comment #, @seclink["intermediate-id"]{identifier}))
       (code:line prim-op (code:comment #, @seclink["intermediate-prim-op"]{primitive operation}))
@@ -210,6 +212,16 @@ The same as Beginning's @|beg-if|.}
 
 The same as Beginning's @|beg-and| and @|beg-or|.}
 
+
+@deftogether[(
+@defform[(check-expect expr expr)]
+@defform[(check-within expr expr expr)]
+@defform[(check-error expr expr)]
+)]{
+
+The same as Beginning's @|beg-check-expect|, etc.}
+
+
 @deftogether[(
 @defthing[empty empty?]
 @defthing[true boolean?]

collects/scribblings/htdp-langs/std-grammar.ss

@@ -13,6 +13,9 @@
 (define-syntax-rule (schemegrammar*+library form ...)
   (schemegrammar*
    form ...
+   [test-case #, @scheme[(check-expect expr expr)]
+              #, @scheme[(check-within expr expr expr)]
+              #, @scheme[(check-error expr expr)]]
    (...
     [libray-require #, @scheme[(require string)]
                     #, @scheme[(require (lib string string ...))]