Changeset 39593 in project

Timestamp:

02/13/21 17:32:07 (3 weeks ago)

Author:

juergen

Message:

checks 1.4 docu

File:

• wiki/eggref/5/checks (modified) (4 diffs)

wiki/eggref/5/checks

@@ -2 +2 @@
 [[toc:]]
 
-== Pre- and postconditions made easy
-
+== Rationale
+
+Pre- and postconditions made easy
+---------------------------------
 This egg implements some routines, which are outsourced from
 simple-exceptions. In particular macros << and >>, which accept an
@@ -16 +18 @@
 careful, if you used the equally named routines from simple-expressions.
 
-=== Interface
-
 The precondition and postcondition checks are denoted with some
 consecutive symbols < and > respectively. There are macro and procedure
@@ -27 +27 @@
 location of the checks.
 
+=== API
+
+==== checker
+ 
+<procedure>(checker sym .. ok? ....)</procedure>
+
+creates a checker routine, i.e. a unuary procedure, which returns its
+argument unchanged, provided it passes all ok? tests. If not, an error
+is generated with location sym, whose default is 'checker.
+
+==== checker?
+ 
+<procedure>(checker? xpr)</procedure>
+
+type predicate.
+
 ==== assert*
-
-<macro>(assert* loc xpr ....)</macro>
-
-checks the expressions xpr .... in sequence and raises an exception
-for the first failing expression with location property loc and
-arguments property the failing expression quoted.
+ 
+<macro>(assert* loc xpr . xprs)</macro>
+
+checks, if its arguments xpr . xprs are not #f.
 
 ==== named-lambda
-
+ 
 <macro>(named-lambda (name . args) xpr . xprs)</macro>
 
-a named version of lambda, which makes recursion possible and helps in
-error messages.
+can be used in place of lambda,
+possibly improving error messages
 
 ==== <<<
-
+ 
 <macro>(<<< loc arg arg? ...)</macro>
 
-precondition test:
-returns arg unchanged only if all predicates arg? return #t on it,
-otherwise an error message with the offending predicate and the
-location loc is printed.
+Precondition test.
+Check a procedure argument, arg, against each predicate arg? ...
+in sequence and pass it to the procedure in case of success.
+loc names the location in the error message.
 
 ==== <<
-
+ 
 <macro>(<< arg arg? ...)</macro>
 
-precondition test:
-returns arg unchanged only if all predicates arg? return #t on it,
-otherwise an error message with the offending predicate is printed.
+Precondition test.
+Check a procedure argument, arg, against each predicate arg? ...
+in sequence and pass it to the procedure in case of success.
 
 ==== >>>
-
+ 
 <macro>(>>> loc result result? ...)</macro>
 
-postcondition test:
-returns result unchanged only if all predicates result? return #t on it,
-otherwise an error message with the offending predicate and the
-location loc is printed.
+Postcondition test.
+Check a return value of a function, result, against each predicate
+result? ...in sequence and return it in case of success.
+loc names the location in case of error.
 
 ==== >>
-
+ 
 <macro>(>> result result? ...)</macro>
 
-postcondition test:
-passes result unchanged only if all predicates result? return #t on it
-otherwise an error message with the offending predicate is printed.
+Postcondition test.
+Check a return value of a function, result, against each predicate
+result? ...in sequence and return it in case of success.
 
 ==== <<<%
-
-<procedure>(<<<% loc name arg arg? ...)</procedure>
-
-precondition test:
-returns arg unchanged only if all predicates arg? return #t on it,
-otherwise an error message with the offending predicate and the
-location loc as well as arg's name is printed.
+ 
+<procedure>(<<<% loc arg-name arg . tests)</procedure>
+
+Precondition test.
+Procedure version of <<<, arg needs to be named.
 
 ==== <<%
-
-<procedure>(<<% name arg arg? ...)</procedure>
-
-precondition test:
-returns arg unchanged only if all predicates arg? return #t on it,
-otherwise an error message with the offending predicate as well as
-arg's name is printed.
+ 
+<procedure>(<<% arg-name arg . tests)</procedure>
+
+Precondition test.
+Procedure version of <<, arg needs to be named.
 
 ==== >>>%
-
-<procedure>(>>>% loc name result result? ...)</procedure>
-
-postcondition test:
-returns result unchanged only if all predicates result? return #t on it,
-otherwise an error message with the offending predicate and the
-location loc as well as result's name is printed.
+ 
+<procedure>(>>>% loc result-name result . tests)</procedure>
+
+Postcondition test.
+Procedure version of >>>, result needs to be named.
 
 ==== >>%
-
-<procedure>(>>% name result result? ...)</procedure>
-
-postcondition test:
-passes result unchanged only if all predicates result? return #t on it
-otherwise an error message with the offending predicate as well as
-result's name is printed.
+ 
+<procedure>(>>% result-name result . tests)</procedure>
+
+Postcondition test.
+Procedure version of <<, result needs to be named.
 
 ==== true?
-
+ 
 <procedure>(true? xpr)</procedure>
 
-returns always #t
+always true
 
 ==== false?
-
+ 
 <procedure>(false? xpr)</procedure>
 
-returns always #f
+always false
+
+==== checks
+ 
+<procedure>(checks)</procedure>
+
+<procedure>(checks sym)</procedure>
+
+with sym: documentation of exported symbol
+without sym: list of exported symbols
 
 === Examples
 
-(define x 5)
-
 <enscript highlight=scheme>
 
 (import checks)
 
-(condition-case
-  (assert* 'x (integer? x) (even? x))
-  ((exn assert) #f)) ;-> #f
-
-(<< x positive? odd?)
-; -> 5
-
-(<< x zero? odd?)
-; -> error
-
-(<< x positive? even?)
-; -> error
-
-(<<< 'loc x positive? even?)
-; -> argument-exception
-
-(<<<% 'loc 'x x positive? even?)
-; -> result-exception
-
-(condition-case
-  (<<% 'x x integer? even?)
-  ((exn argument) #f)) ;-> #f 
+(checker? checkit)
+;-> #t
+
+(checker? checkme)
+;-> #t
+
+(checker? string?)
+;-> #f
+
+(checkit 5)
+;-> 5
+
+(checkme 5)
+;-> 5
+
+(condition-case (checkme -1) ((exn) #f))
+;-> #f
+
+(condition-case ((checker 'bar string?) 5) ((exn) #f))
+;-> #f
+
+(assert* 'x (integer? x))
+;-> #t
+
+(assert* 'x (integer? x) (odd? x))
+;-> #t
+
+(condition-case (assert* 'x (integer? x) (even? x)) ((exn assert) #f))
+;-> #f
+
+x
+;-> 5
+
+(>> x)
+;-> 5
+
+(<< x)
+;-> 5
+
+(>> x integer? odd?)
+;-> 5
+
+(>>% 'x x integer? odd?)
+;-> 5
+
+(<< x integer? odd?)
+;-> 5
+
+(<<% 'x x integer? odd?)
+;-> 5
+
+(<<< 'loc x integer? odd?)
+;-> 5
+
+(>>> 'loc x integer? odd?)
+;-> 5
+
+(<<<% 'loc 'x x integer? odd?)
+;-> 5
+
+(>>>% 'loc 'x x integer? odd?)
+;-> 5
+
+(condition-case (<<% 'x x integer? even?) ((exn argument) #f))
+;-> #f
+
+(condition-case (<<<% 'loc 'x x integer? even?) ((exn argument) #f))
+;-> #f
+
+(condition-case (>> x integer? even?) ((exn result) #f))
+;-> #f
+
+(<< ((lambda () #f)) boolean?)
+;-> #f
+
+((named-lambda (! n) (if (zero? n) 1 (* n (! (- n 1))))) 5)
+;-> 120
 
 </enscript>
 
+
+== Requirements
+
+simple-exceptions
+
 == Last update
 
-Mar 29, 2019
+Feb 13, 2021
 
 == Author
 
-[[/users/juergen-lorenz|Juergen Lorenz]]
+Juergen Lorenz
 
 == License
 
- Copyright (c) 2014-2019, Juergen Lorenz
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions are
- met:
- 
- Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- 
- Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in the
- documentation and/or other materials provided with the distribution.
- Neither the name of the author nor the names of its contributors may be
- used to endorse or promote products derived from this software without
- specific prior written permission. 
-   
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
- IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
- TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
- PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
- TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-== Version History
-
+Copyright (c) 2014-2021, Juergen Lorenz
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+Neither the name of the author nor the names of its contributors may be
+used to endorse or promote products derived from this software without
+specific prior written permission. 
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+== Version history
+; 1.4 : checkers added
 ; 1.3 : dependency on simple-exceptions added
 ; 1.2 : code cleaned
@@ -204 +279 @@
 ; 1.0 : extracted and modified from simple-exceptions
 
-