source: project/wiki/eggref/5/condition-utils @ 35974

Last change on this file since 35974 was 35974, checked in by kon, 12 months ago

rel 2.1.0

File size: 13.3 KB
Line 
1[[tags: egg]]
2
3== condition-utils
4
5SRFI 12 Condition Utilities
6
7[[toc:]]
8
9
10== Documentation
11
12Convenience API for constructing common Chicken exception conditions,
13predicates, and accessors.
14
15=== Argument Conventions
16
17{{LOC}} is a {{symbol}}, or {{#f}}.
18
19{{MSG}} is a {{string}}, or {{#f}}.
20
21{{ARGS}} is a {{list}}, or {{#f}}.
22
23{{CALL-CHAIN}} is the result of {{(get-call-chain)}}, or {{#f}}.
24
25{{CONDITION}} is a {{property-condition}}.
26
27{{CONDITION-SPEC}} is a:
28
29; {{CONDITION}} : a condition object
30; {{symbol}} : {{(make-property-condition <symbol>)}}
31; {{list}} : {{(apply make-property-condition <list>)}}
32
33{{KIND}} is a {{symbol}}.
34
35{{PROP}} is a {{symbol}}.
36
37=== Usage
38
39<enscript language=scheme>
40(import condition-utils)
41</enscript>
42
43=== make-condition+
44
45<procedure>(make-condition+ CONDITION-SPEC...) --> property-condition</procedure>
46
47Returns a {{composite-condition}} {{CONDITION-SPEC...}}.
48
49=== make-condition-predicate
50
51<macro>(make-condition-predicate KIND...) --> (procedure (*) boolean)</macro>
52
53Returns a {{condition-predicate}} for {{KIND...}}.
54
55=== make-condition-property-accessor
56
57<macro>(make-condition-property-accessor KIND PROP [DEFAULT]) --> (procedure (*) boolean)</macro>
58
59Returns a {{condition-property-accessor}} for {{KIND PROP}}. The default value
60of {{DEFAULT}} is {{#f}}.
61
62=== condition-irritants
63
64<procedure>(condition-irritants CONDITION) --> list</procedure>
65
66Returns a list of the condition properties for the condition {{CONDITION}}. The form
67of the list, alist vs. plist, is dependent on the result of the system
68procedure {{condition->list}}.
69
70; CHICKEN 4 : alist
71; CHICKEN 5 : plist
72
73The properties are without associated condition information.
74
75=== write-condition
76
77<procedure>(write-condition CONDITION [PORT (current-output-port) [HEADER "Error"]])</procedure>
78
79Produces on {{PORT}} the form:
80
81Error: <condition-kind>: <condition-property> ...
82    +: <condition-kind>: <condition-property> ...
83       ... for a composite condition ...
84
85=== condition-predicate*
86
87<procedure>(condition-predicate* KIND) --> (* -> boolean : condition)</procedure>
88
89Returns a "memoized" {{condition-predicate}} for {{KIND}}.
90
91=== condition-property-accessor*
92
93<procedure>(condition-property-accessor* KIND PROP [DEFAULT #f]) --> (condition --> *)</procedure>
94
95Returns a "memoized" {{condition-property-accessor}} for {{KIND}}.
96
97
98=== EXN Condition Library
99
100=== Usage
101
102<enscript language=scheme>
103(import exn-condition)
104</enscript>
105
106=== make-exn-condition
107
108<procedure>(make-exn-condition [LOC [MSG [ARGS [CALL-CHAIN]]]]) --> property-condition</procedure>
109
110Returns an {{exn}} {{property-condition}} with optional {{location}},
111{{arguments}}, and {{call-chain}} property values.
112
113Defaults:
114
115; {{LOC}} : missing
116; {{MSG}} : {{"unknown"}}
117; {{ARGS}} : missing
118; {{CALL-CHAIN}} : missing
119
120Will always include {{message}} property in the {{property-condition}}.
121
122=== make-exn-condition+
123
124<procedure>(make-exn-condition+ LOC MSG ARGS [CALL-CHAIN] [CONDITION-SPEC...]) --> property-condition</procedure>
125
126Returns a {{composite-condition}} {{exn CONDITION-SPEC...}}.
127
128When one-of {{LOC}}, {{MSG}}, or {{ARGS}} is without a useful value in the
129error context use {{#f}} as the actual argument. The optional {{CALL-CHAIN}} argument
130is detected by structure.
131
132When {{MSG}} is {{#f}} the value {{"unknown"}} is used.
133
134=== write-exn-condition
135
136<procedure>(write-exn-condition CONDITION [PORT (current-output-port) [HEADER "Error" [CHAIN-HEADER "\n\tCall history:\n"]]])</procedure>
137
138Produces on {{PORT}} the form:
139
140Error: (<location - if any>) <message - if any>: <arguments - if any>
141    +: <condition-kind>: <condition-property> ...
142       ... for a composite condition ...
143
144       Call history:
145       <call-chain>
146
147The call-chain may not be available.
148
149===== exn-condition?
150
151<procedure>(exn-condition? CONDITION) --> boolean</procedure>
152
153===== exn-location
154
155<procedure>(exn-location CONDITION) --> *</procedure>
156
157===== exn-message
158
159<procedure>(exn-message CONDITION) --> *</procedure>
160
161===== exn-arguments
162
163<procedure>(exn-arguments CONDITION) --> *</procedure>
164
165===== exn-call-chain
166
167<procedure>(exn-call-chain CONDITION) --> *</procedure>
168
169
170=== Standard Condition Library
171
172==== Usage
173
174<enscript language=scheme>
175(import standard-conditions)
176</enscript>
177
178==== Condition Predicates
179
180===== arity-condition?
181
182<procedure>(arity-condition? CONDITION) --> boolean</procedure>
183
184===== type-condition?
185
186<procedure>(type-condition? CONDITION) --> boolean</procedure>
187
188===== arithmetic-condition?
189
190<procedure>(arithmetic-condition? CONDITION) --> boolean</procedure>
191
192===== i/o-condition?
193
194<procedure>(i/o-condition? CONDITION) --> boolean</procedure>
195
196===== file-condition?
197
198<procedure>(file-condition? CONDITION) --> boolean</procedure>
199
200===== network-condition?
201
202<procedure>(network-condition? CONDITION) --> boolean</procedure>
203
204===== network-timeout-condition?
205
206<procedure>(network-timeout-condition? CONDITION) --> boolean</procedure>
207
208===== bounds-condition?
209
210<procedure>(bounds-condition? CONDITION) --> boolean</procedure>
211
212===== runtime-condition?
213
214<procedure>(runtime-condition? CONDITION) --> boolean</procedure>
215
216===== runtime-limit-condition?
217
218<procedure>(runtime-limit-condition? CONDITION) --> boolean</procedure>
219
220===== runtime-cycle-condition?
221
222<procedure>(runtime-cycle-condition? CONDITION) --> boolean</procedure>
223
224===== match-condition?
225
226<procedure>(match-condition? CONDITION) --> boolean</procedure>
227
228===== syntax-condition?
229
230<procedure>(syntax-condition? CONDITION) --> boolean</procedure>
231
232===== process-condition?
233
234<procedure>(process-condition? CONDITION) --> boolean</procedure>
235
236===== access-condition?
237
238<procedure>(access-condition? CONDITION) --> boolean</procedure>
239
240===== domain-condition?
241
242<procedure>(domain-condition? CONDITION) --> boolean</procedure>
243
244===== memory-condition?
245
246<procedure>(memory-condition? CONDITION) --> boolean</procedure>
247
248
249=== HTTP Client Condition Library
250
251==== Usage
252
253<enscript language=scheme>
254(import http-client-conditions)
255</enscript>
256
257==== Condition Predicates
258
259===== http-condition?
260
261<procedure>(http-condition? CONDITION) --> boolean</procedure>
262
263===== client-error-condition?
264
265<procedure>(client-error-condition? CONDITION) --> boolean</procedure>
266
267===== server-error-condition?
268
269<procedure>(server-error-condition? CONDITION) --> boolean</procedure>
270
271===== unexpected-server-response-condition?
272
273<procedure>(unexpected-server-response-condition? CONDITION) --> boolean</procedure>
274
275===== redirect-depth-exceeded-condition?
276
277<procedure>(redirect-depth-exceeded-condition? CONDITION) --> boolean</procedure>
278
279===== unsupported-uri-scheme-condition?
280
281<procedure>(unsupported-uri-scheme-condition? CONDITION) --> boolean</procedure>
282
283===== unknown-authtype-condition?
284
285<procedure>(unknown-authtype-condition? CONDITION) --> boolean</procedure>
286
287==== Condition Property Accessors
288
289===== client-error-response
290
291<procedure>(client-error-response CONDITION) --> *</procedure>
292
293===== client-error-body
294
295<procedure>(client-error-body CONDITION) --> *</procedure>
296
297===== server-error-response
298
299<procedure>(server-error-response CONDITION) --> *</procedure>
300
301===== server-error-body
302
303<procedure>(server-error-body CONDITION) --> *</procedure>
304
305===== unexpected-server-response-response
306
307<procedure>(unexpected-server-response-response CONDITION) --> *</procedure>
308
309===== unexpected-server-response-body
310
311<procedure>(unexpected-server-response-body CONDITION) --> *</procedure>
312
313===== redirect-depth-exceeded-uri
314
315<procedure>(redirect-depth-exceeded-uri CONDITION) --> *</procedure>
316
317===== formdata-error-condition?
318
319<procedure>(formdata-error-condition? CONDITION) --> boolean</procedure>
320
321===== unsupported-uri-scheme-uri-scheme
322
323<procedure>(unsupported-uri-scheme-uri-scheme CONDITION) --> *</procedure>
324
325===== unsupported-uri-scheme-request-uri
326
327<procedure>(unsupported-uri-scheme-request-uri CONDITION) --> *</procedure>
328
329===== unknown-authtype-authtype
330
331<procedure>(unknown-authtype-authtype CONDITION) --> *</procedure>
332
333
334=== Intarweb Condition Library
335
336==== Usage
337
338<enscript language=scheme>
339(import intarweb-conditions)
340</enscript>
341
342==== Condition Predicates
343
344===== http-condition?
345
346<procedure>(http-condition? CONDITION) --> boolean</procedure>
347
348===== urlencoded-request-data-limit-exceeded?
349
350<procedure>(urlencoded-request-data-limit-exceeded? CONDITION) --> boolean</procedure>
351
352===== line-limit-exceeded?
353
354<procedure>(line-limit-exceeded? CONDITION) --> boolean</procedure>
355
356===== header-error?
357
358<procedure>(header-error? CONDITION) --> boolean</procedure>
359
360===== header-limit-exceeded?
361
362<procedure>(header-limit-exceeded? CONDITION) --> boolean</procedure>
363
364===== unknown-protocol-line?
365
366<procedure>(unknown-protocol-line? CONDITION) --> boolean</procedure>
367
368===== unknown-protocol?
369
370<procedure>(unknown-protocol? CONDITION) --> boolean</procedure>
371
372===== unknown-code?
373
374<procedure>(unknown-code? CONDITION) --> boolean</procedure>
375
376===== unknown-status?
377
378<procedure>(unknown-status? CONDITION) --> boolean</procedure>
379
380===== rfc1123-subparser?
381
382<procedure>(rfc1123-subparser? CONDITION) --> boolean</procedure>
383
384===== rfc850-subparser?
385
386<procedure>(rfc850-subparser? CONDITION) --> boolean</procedure>
387
388===== asctime-subparser?
389
390<procedure>(asctime-subparser? CONDITION) --> boolean</procedure>
391
392===== http-date-subparser?
393
394<procedure>(http-date-subparser? CONDITION) --> boolean</procedure>
395
396===== unencoded-header?
397
398<procedure>(unencoded-header? CONDITION) --> boolean</procedure>
399
400===== username-with-colon?
401
402<procedure>(username-with-colon? CONDITION) --> boolean</procedure>
403
404==== Condition Property Accessors
405
406===== urlencoded-request-data-limit-exceeded-contents
407
408<procedure>(urlencoded-request-data-limit-exceeded-contents CONDITION) --> *</procedure>
409
410===== urlencoded-request-data-limit-exceeded-limit
411
412<procedure>(urlencoded-request-data-limit-exceeded-limit CONDITION) --> *</procedure>
413
414===== line-limit-exceeded-contents
415
416<procedure>(line-limit-exceeded-contents CONDITION) --> *</procedure>
417
418===== line-limit-exceeded-limit
419
420<procedure>(line-limit-exceeded-limit CONDITION) --> *</procedure>
421
422===== header-error-contents
423
424<procedure>(header-error-contents CONDITION) --> *</procedure>
425
426===== header-limit-exceeded-contents
427
428<procedure>(header-limit-exceeded-contents CONDITION) --> *</procedure>
429
430===== header-limit-exceeded-limit
431
432<procedure>(header-limit-exceeded-limit CONDITION) --> *</procedure>
433
434===== unknown-protocol-line-line
435
436<procedure>(unknown-protocol-line-line CONDITION) --> *</procedure>
437
438===== unknown-protocol-major
439
440<procedure>(unknown-protocol-major CONDITION) --> *</procedure>
441
442===== unknown-protocol-minor
443
444<procedure>(unknown-protocol-minor CONDITION) --> *</procedure>
445
446===== unknown-code-code
447
448<procedure>(unknown-code-code CONDITION) --> *</procedure>
449
450===== unknown-status-status
451
452<procedure>(unknown-status-status CONDITION) --> *</procedure>
453
454===== rfc1123-subparser-value?
455
456<procedure>(rfc1123-subparser-value? CONDITION) --> boolean</procedure>
457
458===== rfc850-subparser-value?
459
460<procedure>(rfc850-subparser-value? CONDITION) --> boolean</procedure>
461
462===== asctime-subparser-value?
463
464<procedure>(asctime-subparser-value? CONDITION) --> boolean</procedure>
465
466===== http-date-subparser-value?
467
468<procedure>(http-date-subparser-value? CONDITION) --> boolean</procedure>
469
470===== unencoded-header-value?
471
472<procedure>(unencoded-header-value? CONDITION) --> boolean</procedure>
473
474===== username-with-colon-value?
475
476<procedure>(username-with-colon-value? CONDITION) --> boolean</procedure>
477
478
479== Notes
480
481* {{write-exn-condition}} is from {{write-exception}} of
482[[https://github.com/dleslie/geiser/blob/master/scheme/chicken/geiser/emacs.scm]].
483
484
485== Author
486
487[[/users/kon-lovett|Kon Lovett]]
488
489
490== Version history
491
492; 2.1.0 : CHICKEN 5 release.
493; 1.5.1 : Fix for empty call-chain.
494; 1.5.0 : Add types.
495; 1.4.2 : Fix #1378
496; 1.4.1 : Fix {{write-exn-condition}} call-chain header duplication.
497; 1.4.0 : Add {{HEADER}} to {{write-exn-condition}} & {{write-condition}}. Add {{CHAIN-HEADER}} to {{write-exn-condition}}. Follow {{error}} form more closely.
498; 1.3.0 : {{write-exn-condition}} now includes all elements of a {{composite-condition}}. Added {{write-condition}}.
499; 1.2.0 : amended {{write-exn-condition}}, add doc for condition libraries.
500; 1.1.1 : added {{write-exn-condition}}
501; 1.1.0 : added {{make-exn-condition}}
502; 1.0.4 : default exn msg
503; 1.0.3 : added call-chain argument & standard conditions
504; 1.0.2 : Fix for ticket #630
505; 1.0.1 :
506; 1.0.0 : Hello (from "check-errors:1.11.0")
507
508
509== License
510
511Copyright (C) 2009-2017 Kon Lovett.  All rights reserved.
512
513Permission is hereby granted, free of charge, to any person obtaining a
514copy of this software and associated documentation files (the Software),
515to deal in the Software without restriction, including without limitation
516the rights to use, copy, modify, merge, publish, distribute, sublicense,
517and/or sell copies of the Software, and to permit persons to whom the
518Software is furnished to do so, subject to the following conditions:
519
520The above copyright notice and this permission notice shall be included
521in all copies or substantial portions of the Software.
522
523THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
524IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
525FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
526THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
527OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
528ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
529OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.