Changeset 39593 in project


Ignore:
Timestamp:
02/13/21 17:32:07 (3 weeks ago)
Author:
juergen
Message:

checks 1.4 docu

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/checks

    r37485 r39593  
    22[[toc:]]
    33
    4 == Pre- and postconditions made easy
    5 
     4== Rationale
     5
     6Pre- and postconditions made easy
     7---------------------------------
    68This egg implements some routines, which are outsourced from
    79simple-exceptions. In particular macros << and >>, which accept an
     
    1618careful, if you used the equally named routines from simple-expressions.
    1719
    18 === Interface
    19 
    2020The precondition and postcondition checks are denoted with some
    2121consecutive symbols < and > respectively. There are macro and procedure
     
    2727location of the checks.
    2828
     29=== API
     30
     31==== checker
     32 
     33<procedure>(checker sym .. ok? ....)</procedure>
     34
     35creates a checker routine, i.e. a unuary procedure, which returns its
     36argument unchanged, provided it passes all ok? tests. If not, an error
     37is generated with location sym, whose default is 'checker.
     38
     39==== checker?
     40 
     41<procedure>(checker? xpr)</procedure>
     42
     43type predicate.
     44
    2945==== assert*
    30 
    31 <macro>(assert* loc xpr ....)</macro>
    32 
    33 checks the expressions xpr .... in sequence and raises an exception
    34 for the first failing expression with location property loc and
    35 arguments property the failing expression quoted.
     46 
     47<macro>(assert* loc xpr . xprs)</macro>
     48
     49checks, if its arguments xpr . xprs are not #f.
    3650
    3751==== named-lambda
    38 
     52 
    3953<macro>(named-lambda (name . args) xpr . xprs)</macro>
    4054
    41 a named version of lambda, which makes recursion possible and helps in
    42 error messages.
     55can be used in place of lambda,
     56possibly improving error messages
    4357
    4458==== <<<
    45 
     59 
    4660<macro>(<<< loc arg arg? ...)</macro>
    4761
    48 precondition test:
    49 returns arg unchanged only if all predicates arg? return #t on it,
    50 otherwise an error message with the offending predicate and the
    51 location loc is printed.
     62Precondition test.
     63Check a procedure argument, arg, against each predicate arg? ...
     64in sequence and pass it to the procedure in case of success.
     65loc names the location in the error message.
    5266
    5367==== <<
    54 
     68 
    5569<macro>(<< arg arg? ...)</macro>
    5670
    57 precondition test:
    58 returns arg unchanged only if all predicates arg? return #t on it,
    59 otherwise an error message with the offending predicate is printed.
     71Precondition test.
     72Check a procedure argument, arg, against each predicate arg? ...
     73in sequence and pass it to the procedure in case of success.
    6074
    6175==== >>>
    62 
     76 
    6377<macro>(>>> loc result result? ...)</macro>
    6478
    65 postcondition test:
    66 returns result unchanged only if all predicates result? return #t on it,
    67 otherwise an error message with the offending predicate and the
    68 location loc is printed.
     79Postcondition test.
     80Check a return value of a function, result, against each predicate
     81result? ...in sequence and return it in case of success.
     82loc names the location in case of error.
    6983
    7084==== >>
    71 
     85 
    7286<macro>(>> result result? ...)</macro>
    7387
    74 postcondition test:
    75 passes result unchanged only if all predicates result? return #t on it
    76 otherwise an error message with the offending predicate is printed.
     88Postcondition test.
     89Check a return value of a function, result, against each predicate
     90result? ...in sequence and return it in case of success.
    7791
    7892==== <<<%
    79 
    80 <procedure>(<<<% loc name arg arg? ...)</procedure>
    81 
    82 precondition test:
    83 returns arg unchanged only if all predicates arg? return #t on it,
    84 otherwise an error message with the offending predicate and the
    85 location loc as well as arg's name is printed.
     93 
     94<procedure>(<<<% loc arg-name arg . tests)</procedure>
     95
     96Precondition test.
     97Procedure version of <<<, arg needs to be named.
    8698
    8799==== <<%
    88 
    89 <procedure>(<<% name arg arg? ...)</procedure>
    90 
    91 precondition test:
    92 returns arg unchanged only if all predicates arg? return #t on it,
    93 otherwise an error message with the offending predicate as well as
    94 arg's name is printed.
     100 
     101<procedure>(<<% arg-name arg . tests)</procedure>
     102
     103Precondition test.
     104Procedure version of <<, arg needs to be named.
    95105
    96106==== >>>%
    97 
    98 <procedure>(>>>% loc name result result? ...)</procedure>
    99 
    100 postcondition test:
    101 returns result unchanged only if all predicates result? return #t on it,
    102 otherwise an error message with the offending predicate and the
    103 location loc as well as result's name is printed.
     107 
     108<procedure>(>>>% loc result-name result . tests)</procedure>
     109
     110Postcondition test.
     111Procedure version of >>>, result needs to be named.
    104112
    105113==== >>%
    106 
    107 <procedure>(>>% name result result? ...)</procedure>
    108 
    109 postcondition test:
    110 passes result unchanged only if all predicates result? return #t on it
    111 otherwise an error message with the offending predicate as well as
    112 result's name is printed.
     114 
     115<procedure>(>>% result-name result . tests)</procedure>
     116
     117Postcondition test.
     118Procedure version of <<, result needs to be named.
    113119
    114120==== true?
    115 
     121 
    116122<procedure>(true? xpr)</procedure>
    117123
    118 returns always #t
     124always true
    119125
    120126==== false?
    121 
     127 
    122128<procedure>(false? xpr)</procedure>
    123129
    124 returns always #f
     130always false
     131
     132==== checks
     133 
     134<procedure>(checks)</procedure>
     135
     136<procedure>(checks sym)</procedure>
     137
     138with sym: documentation of exported symbol
     139without sym: list of exported symbols
    125140
    126141=== Examples
    127142
    128 (define x 5)
    129 
    130143<enscript highlight=scheme>
    131144
    132145(import checks)
    133146
    134 (condition-case
    135   (assert* 'x (integer? x) (even? x))
    136   ((exn assert) #f)) ;-> #f
    137 
    138 (<< x positive? odd?)
    139 ; -> 5
    140 
    141 (<< x zero? odd?)
    142 ; -> error
    143 
    144 (<< x positive? even?)
    145 ; -> error
    146 
    147 (<<< 'loc x positive? even?)
    148 ; -> argument-exception
    149 
    150 (<<<% 'loc 'x x positive? even?)
    151 ; -> result-exception
    152 
    153 (condition-case
    154   (<<% 'x x integer? even?)
    155   ((exn argument) #f)) ;-> #f
     147(checker? checkit)
     148;-> #t
     149
     150(checker? checkme)
     151;-> #t
     152
     153(checker? string?)
     154;-> #f
     155
     156(checkit 5)
     157;-> 5
     158
     159(checkme 5)
     160;-> 5
     161
     162(condition-case (checkme -1) ((exn) #f))
     163;-> #f
     164
     165(condition-case ((checker 'bar string?) 5) ((exn) #f))
     166;-> #f
     167
     168(assert* 'x (integer? x))
     169;-> #t
     170
     171(assert* 'x (integer? x) (odd? x))
     172;-> #t
     173
     174(condition-case (assert* 'x (integer? x) (even? x)) ((exn assert) #f))
     175;-> #f
     176
     177x
     178;-> 5
     179
     180(>> x)
     181;-> 5
     182
     183(<< x)
     184;-> 5
     185
     186(>> x integer? odd?)
     187;-> 5
     188
     189(>>% 'x x integer? odd?)
     190;-> 5
     191
     192(<< x integer? odd?)
     193;-> 5
     194
     195(<<% 'x x integer? odd?)
     196;-> 5
     197
     198(<<< 'loc x integer? odd?)
     199;-> 5
     200
     201(>>> 'loc x integer? odd?)
     202;-> 5
     203
     204(<<<% 'loc 'x x integer? odd?)
     205;-> 5
     206
     207(>>>% 'loc 'x x integer? odd?)
     208;-> 5
     209
     210(condition-case (<<% 'x x integer? even?) ((exn argument) #f))
     211;-> #f
     212
     213(condition-case (<<<% 'loc 'x x integer? even?) ((exn argument) #f))
     214;-> #f
     215
     216(condition-case (>> x integer? even?) ((exn result) #f))
     217;-> #f
     218
     219(<< ((lambda () #f)) boolean?)
     220;-> #f
     221
     222((named-lambda (! n) (if (zero? n) 1 (* n (! (- n 1))))) 5)
     223;-> 120
    156224
    157225</enscript>
    158226
     227
     228== Requirements
     229
     230simple-exceptions
     231
    159232== Last update
    160233
    161 Mar 29, 2019
     234Feb 13, 2021
    162235
    163236== Author
    164237
    165 [[/users/juergen-lorenz|Juergen Lorenz]]
     238Juergen Lorenz
    166239
    167240== License
    168241
    169  Copyright (c) 2014-2019, Juergen Lorenz
    170  All rights reserved.
    171 
    172  Redistribution and use in source and binary forms, with or without
    173  modification, are permitted provided that the following conditions are
    174  met:
    175  
    176  Redistributions of source code must retain the above copyright
    177  notice, this list of conditions and the following disclaimer.
    178  
    179  Redistributions in binary form must reproduce the above copyright
    180  notice, this list of conditions and the following disclaimer in the
    181  documentation and/or other materials provided with the distribution.
    182  Neither the name of the author nor the names of its contributors may be
    183  used to endorse or promote products derived from this software without
    184  specific prior written permission.
    185    
    186  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
    187  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
    188  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
    189  PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    190  HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    191  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
    192  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    193  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    194  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    195  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    196  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    197 
    198 == Version History
    199 
     242Copyright (c) 2014-2021, Juergen Lorenz
     243All rights reserved.
     244
     245Redistribution and use in source and binary forms, with or without
     246modification, are permitted provided that the following conditions are
     247met:
     248
     249Redistributions of source code must retain the above copyright
     250notice, this list of conditions and the following disclaimer.
     251
     252Redistributions in binary form must reproduce the above copyright
     253notice, this list of conditions and the following disclaimer in the
     254documentation and/or other materials provided with the distribution.
     255
     256Neither the name of the author nor the names of its contributors may be
     257used to endorse or promote products derived from this software without
     258specific prior written permission.
     259
     260THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
     261IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
     262TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
     263PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
     264HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     265SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
     266TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
     267PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
     268LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
     269NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
     270SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     271
     272
     273== Version history
     274; 1.4 : checkers added
    200275; 1.3 : dependency on simple-exceptions added
    201276; 1.2 : code cleaned
     
    204279; 1.0 : extracted and modified from simple-exceptions
    205280
    206 
Note: See TracChangeset for help on using the changeset viewer.