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

Last change on this file since 37192 was 37192, checked in by juergen, 8 months ago

checks 1.1 docu

File size: 5.4 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. They 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==== <<<
38
39<macro>(<<< loc arg arg? ...)</macro>
40
41precondition test:
42returns arg unchanged only if all predicates arg? return #t on it,
43otherwise an error message with the offending predicate and the
44location loc is printed.
45
46==== <<
47
48<macro>(<< arg arg? ...)</macro>
49
50precondition test:
51returns arg unchanged only if all predicates arg? return #t on it,
52otherwise an error message with the offending predicate is printed.
53
54==== >>>
55
56<macro>(>>> loc result result? ...)</macro>
57
58postcondition test:
59returns result unchanged only if all predicates result? return #t on it,
60otherwise an error message with the offending predicate and the
61location loc is printed.
62
63==== >>
64
65<macro>(>> result result? ...)</macro>
66
67postcondition test:
68passes result unchanged only if all predicates result? return #t on it
69otherwise an error message with the offending predicate is printed.
70
71==== <<<%
72
73<procedure>(<<<% loc name arg arg? ...)</procedure>
74
75precondition test:
76returns arg unchanged only if all predicates arg? return #t on it,
77otherwise an error message with the offending predicate and the
78location loc as well as arg's name is printed.
79
80==== <<%
81
82<procedure>(<<% name arg arg? ...)</procedure>
83
84precondition test:
85returns arg unchanged only if all predicates arg? return #t on it,
86otherwise an error message with the offending predicate as well as
87arg's name is printed.
88
89==== >>>%
90
91<procedure>(>>>% loc name result result? ...)</procedure>
92
93postcondition test:
94returns result unchanged only if all predicates result? return #t on it,
95otherwise an error message with the offending predicate and the
96location loc as well as result's name is printed.
97
98==== >>%
99
100<procedure>(>>% name result result? ...)</procedure>
101
102postcondition test:
103passes result unchanged only if all predicates result? return #t on it
104otherwise an error message with the offending predicate as well as
105result's name is printed.
106
107==== true?
108
109<procedure>(true? xpr)</procedure>
110
111returns always #t
112
113==== false?
114
115<procedure>(false? xpr)</procedure>
116
117returns always #f
118
119=== Examples
120
121(define x 5)
122
123(<< x positive? odd?)
124; -> 5
125
126(<< x zero? odd?)
127; -> error
128
129(<< x positive? even?)
130; -> error
131
132(<<< 'loc x positive? even?)
133; -> error message with predicate even?, location 'loc and name 'x
134
135(<<<% 'loc 'x x positive? even?)
136; -> error message with predicate even?, location 'loc and name 'x
137
138== Last update
139
140Feb 02, 2019
141
142== Author
143
144[[/users/juergen-lorenz|Juergen Lorenz]]
145
146== License
147
148 Copyright (c) 2014-2019, Juergen Lorenz
149 All rights reserved.
150
151 Redistribution and use in source and binary forms, with or without
152 modification, are permitted provided that the following conditions are
153 met:
154 
155 Redistributions of source code must retain the above copyright
156 notice, this list of conditions and the following disclaimer.
157 
158 Redistributions in binary form must reproduce the above copyright
159 notice, this list of conditions and the following disclaimer in the
160 documentation and/or other materials provided with the distribution.
161 Neither the name of the author nor the names of its contributors may be
162 used to endorse or promote products derived from this software without
163 specific prior written permission.
164   
165 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
166 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
167 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
168 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
169 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
170 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
171 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
172 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
173 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
174 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
175 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
176
177== Version History
178
179; 1.1 : procedure versions added
180; 1.0 : extracted and modified from simple-exceptions
181
182
Note: See TracBrowser for help on using the repository browser.