source: project/wiki/eggref/4/condition-utils @ 35327

Last change on this file since 35327 was 35327, checked in by kon, 13 months ago

better param names

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