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

Last change on this file since 36709 was 36709, checked in by kon, 6 months ago

fix tree

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