source: project/wiki/eggref/5/checks @ 37474

Last change on this file since 37474 was 37474, checked in by juergen, 11 months ago

checks docu updated

File size: 5.7 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== Pre- and postconditions made easy
5
6This egg implements some routines, which are outsourced from
7simple-exceptions. In particular macros << and >>, which accept an
8argument or result, checks it against zero or more predicates and
9returns it in case of success unchanged. Otherwise it prints a
10meaningful error message, showing i.a. the offending predicate and the
11argument's or result's name. Some are implemented as macros instead of
12procedures, because I didn't want an extra parameter with the argument's
13or result's name.
14Procedure versions of those macros are given as well.
15In reimplementing those routines, I changed the syntax a bit, so be
16careful, if you used the equally named routines from simple-expressions.
17
18=== Interface
19
20The precondition and postcondition checks are denoted with some
21consecutive symbols < and > respectively. There are macro and procedure
22versions, the latter denoted with a trailing % and needing an additional
23parameter, the name of the value to be checked. All those routines work
24the same, they differ only in the error message, they produce in case
25some predicate returns #f. The routines named with three symbols < or >
26differ from those with two only by an additional parameter naming the
27location of the checks.
28
29==== assert*
30
31<macro>(assert* loc xpr ....)</macro>
32
33checks the expressions xpr .... in sequence and raises an exception
34for the first failing expression with location property loc and
35arguments property the failing expression quoted.
36
37==== named-lambda
38
39<macro>(named-lambda (name . args) xpr . xprs)</macro>
40
41a named version of lambda, which makes recursion possible and helps in
42error messages.
43
44==== <<<
45
46<macro>(<<< loc arg arg? ...)</macro>
47
48precondition test:
49returns arg unchanged only if all predicates arg? return #t on it,
50otherwise an error message with the offending predicate and the
51location loc is printed.
52
53==== <<
54
55<macro>(<< arg arg? ...)</macro>
56
57precondition test:
58returns arg unchanged only if all predicates arg? return #t on it,
59otherwise an error message with the offending predicate is printed.
60
61==== >>>
62
63<macro>(>>> loc result result? ...)</macro>
64
65postcondition test:
66returns result unchanged only if all predicates result? return #t on it,
67otherwise an error message with the offending predicate and the
68location loc is printed.
69
70==== >>
71
72<macro>(>> result result? ...)</macro>
73
74postcondition test:
75passes result unchanged only if all predicates result? return #t on it
76otherwise an error message with the offending predicate is printed.
77
78==== <<<%
79
80<procedure>(<<<% loc name arg arg? ...)</procedure>
81
82precondition test:
83returns arg unchanged only if all predicates arg? return #t on it,
84otherwise an error message with the offending predicate and the
85location loc as well as arg's name is printed.
86
87==== <<%
88
89<procedure>(<<% name arg arg? ...)</procedure>
90
91precondition test:
92returns arg unchanged only if all predicates arg? return #t on it,
93otherwise an error message with the offending predicate as well as
94arg's name is printed.
95
96==== >>>%
97
98<procedure>(>>>% loc name result result? ...)</procedure>
99
100postcondition test:
101returns result unchanged only if all predicates result? return #t on it,
102otherwise an error message with the offending predicate and the
103location loc as well as result's name is printed.
104
105==== >>%
106
107<procedure>(>>% name result result? ...)</procedure>
108
109postcondition test:
110passes result unchanged only if all predicates result? return #t on it
111otherwise an error message with the offending predicate as well as
112result's name is printed.
113
114==== true?
115
116<procedure>(true? xpr)</procedure>
117
118returns always #t
119
120==== false?
121
122<procedure>(false? xpr)</procedure>
123
124returns always #f
125
126=== Examples
127
128(define x 5)
129
130(<< x positive? odd?)
131; -> 5
132
133(<< x zero? odd?)
134; -> error
135
136(<< x positive? even?)
137; -> error
138
139(<<< 'loc x positive? even?)
140; -> error message with predicate even?, location 'loc and name 'x
141
142(<<<% 'loc 'x x positive? even?)
143; -> error message with predicate even?, location 'loc and name 'x
144
145== Last update
146
147Mar 27, 2019
148
149== Author
150
151[[/users/juergen-lorenz|Juergen Lorenz]]
152
153== License
154
155 Copyright (c) 2014-2019, Juergen Lorenz
156 All rights reserved.
157
158 Redistribution and use in source and binary forms, with or without
159 modification, are permitted provided that the following conditions are
160 met:
161 
162 Redistributions of source code must retain the above copyright
163 notice, this list of conditions and the following disclaimer.
164 
165 Redistributions in binary form must reproduce the above copyright
166 notice, this list of conditions and the following disclaimer in the
167 documentation and/or other materials provided with the distribution.
168 Neither the name of the author nor the names of its contributors may be
169 used to endorse or promote products derived from this software without
170 specific prior written permission.
171   
172 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
173 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
174 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
175 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
176 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
177 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
178 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
179 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
180 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
181 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
182 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
183
184== Version History
185
186; 1.2 : code cleaned
187; 1.1.0 : documentation of named-lambda fixed
188; 1.1 : procedure versions added
189; 1.0 : extracted and modified from simple-exceptions
190
191
Note: See TracBrowser for help on using the repository browser.