(index ("condition-case" 0) ("get-condition-property" 1144) ("condition->list" 1407) ("current-exception-handler" 1848) ("with-exception-handler" 2049) ("handle-exceptions" 2760) ("abort" 3878) ("signal" 4449) ("condition?" 4917) ("make-property-condition" 5357) ("make-composite-condition" 5929) ("condition-predicate" 6300) ("condition-property-accessor" 6851))
(def (sig (syntax "(condition-case EXPRESSION CLAUSE ...)" (id condition-case))) (p "Evaluates " (tt "EXPRESSION") " and handles any exceptions that are covered by " (tt "CLAUSE ...") ", where " (tt "CLAUSE") " should be of the following form:") (pre " CLAUSE = ([VARIABLE] (KIND ...) BODY ...)") (p "If provided, " (tt "VARIABLE") " will be bound to the signaled exception object. " (tt "BODY ...") " is executed when the exception is a property- or composite condition with the kinds given " (tt "KIND ...") " (unevaluated). If no clause applies, the exception is re-signaled in the same dynamic context as the " (tt "condition-case") " form.") (highlight scheme "(define (check thunk)\n  (condition-case (thunk)\n    [(exn file) (print \"file error\")]\n    [(exn) (print \"other error\")]\n    [var () (print \"something else\")] ) )\n\n(check (lambda () (open-input-file \"\")))   ; -> \"file error\"\n(check (lambda () some-unbound-variable))  ; -> \"othererror\"\n(check (lambda () (signal 99)))            ; -> \"something else\"\n\n(condition-case some-unbound-variable\n  ((exn file) (print \"ignored\")) )      ; -> signals error"))
(def (sig (procedure "(get-condition-property CONDITION KIND PROPERTY [DEFAULT])" (id get-condition-property))) (p "A slightly more convenient condition property accessor, equivalent to") (pre "((condition-property-accessor KIND PROPERTY [DEFAULT]) CONDITION)"))
(def (sig (procedure "(condition->list CONDITION)" (id condition->list))) (p "This procedure converts a condition object into a list holding all the conditions that are represented by the " (i "CONDITION") " object.  It is formatted as follows:") (pre "((KIND1 (PROPERTY1 VALUE1) (PROPERTY2 VALUE2) ...) (KIND2 ... ) ... )") (p "There is no guaranteed order within the list.") (p (tt "condition->list") " was introduced in CHICKEN 4.7.0."))
(def (sig (parameter "(current-exception-handler [PROCEDURE])" (id current-exception-handler))) (p "Sets or returns the current exception handler, a procedure of one argument, the exception object."))
(def (sig (procedure "(with-exception-handler handler thunk)" (id with-exception-handler))) (p "Returns the result(s) of invoking " (i "thunk") ". The " (i "handler") " procedure is installed as the current exception handler in the dynamic context of invoking " (i "thunk") ".") (p "Example:") (highlight scheme "(call-with-current-continuation\n (lambda (k)\n  (with-exception-handler (lambda (x) (k '()))\n                          (lambda () (car '())))))\n;=> '()") (p "Note that the handler procedure must somehow return non-locally out of the dynamic extent of the " (tt "with-exception-handler") " form, because returning normally will signal yet another exception and thus result in non-termination."))
(def (sig (syntax "(handle-exceptions var handle-expr expr1 expr2 ...)" (id handle-exceptions))) (p "Evaluates the body expressions " (i "expr1") ", " (i "expr2") ", ... in sequence with an exception handler constructed from " (i "var") " and " (i "handle-expr") ". Assuming no exception is raised, the result(s) of the last body expression is(are) the result(s) of the " (tt "handle-exceptions") " expression.") (p "The exception handler created by " (tt "handle-exceptions") " restores the dynamic context (continuation, exception handler, etc.) of the " (tt "handle-exceptions") " expression, and then evaluates " (i "handle-expr") " with " (i "var") " bound to the value provided to the handler.") (p "Examples:") (highlight scheme "(handle-exceptions exn\n\t\t   (begin\n\t\t     (display \"Went wrong\")\n\t\t     (newline))\n (car '()))\n; displays \"Went wrong\"\n \n(handle-exceptions exn \n\t\t   (cond\n\t\t    ((eq? exn 'one) 1)\n\t\t     (else (abort exn)))\n  (case (random 3)\n   [(0) 'zero]\n   [(1) (abort 'one)]\n   [else (abort \"Something else\")]))\n;=> 'zero, 1, or (abort \"Something else\")"))
(def (sig (procedure "(abort obj)" (id abort))) (p "Raises a non-continuable exception represented by " (i "obj") ". The " (tt "abort") " procedure can be implemented as follows:") (highlight scheme "(define (abort obj)\n  ((current-exception-handler) obj)\n  (abort (make-property-condition\n\t   'exn\n\t   'message\n\t   \"Exception handler returned\")))") (p "The " (tt "abort") " procedure does not ensure that its argument is a condition. If its argument is a condition, " (tt "abort") " does not ensure that the condition indicates a non-continuable exception."))
(def (sig (procedure "(signal obj)" (id signal))) (p "Raises a continuable exception represented by " (i "obj") ". The " (tt "signal") " procedure can be implemented as follows:") (highlight scheme "(define (signal exn)\n ((current-exception-handler) exn))") (p "The " (tt "signal") " procedure does not ensure that its argument is a condition. If its argument is a condition, " (tt "signal") " does not ensure that the condition indicates a continuable exception."))
(def (sig (procedure "(condition? obj)" (id condition?))) (p "Returns #t if " (i "obj") " is a condition, otherwise returns #f. If any of the predicates listed in Section 3.2 of the R5RS is true of " (i "obj") ", then " (tt "condition?") " is false of " (i "obj") ".") (p "Rationale: Any Scheme object may be passed to an exception handler. This would cause ambiguity if conditions were not disjoint from all of Scheme's standard types."))
(def (sig (procedure "(make-property-condition kind-key prop-key value ...)" (id make-property-condition))) (p "This procedure accepts any even number of arguments after " (i "kind-key") ", which are regarded as a sequence of alternating " (i "prop-key") " and " (i "value") " objects. Each " (i "prop-key") " is regarded as the name of a property, and each " (i "value") " is regarded as the value associated with the " (i "key") " that precedes it. Returns a " (i "kind-key") " condition that associates the given " (i "prop-key") "s with the given " (i "value") "s."))
(def (sig (procedure "(make-composite-condition condition ...)" (id make-composite-condition))) (p "Returns a newly-allocated condition whose components correspond to the the given " (i "condition") "s. A predicate created by " (tt "condition-predicate") " returns true for the new condition if and only if it returns true for one or more of its component conditions."))
(def (sig (procedure "(condition-predicate kind-key)" (id condition-predicate))) (p "Returns a predicate that can be called with any object as its argument. Given a condition that was created by " (tt "make-property-condition") ", the predicate returns #t if and only if " (i "kind-key") " is EQV? to the kind key that was passed to " (tt "make-property-condition") ". Given a composite condition created with " (tt "make-composite-condition") ", the predicate returns #t if and only if the predicate returns #t for at least one of its components."))
(def (sig (procedure "(condition-property-accessor kind-key prop-key [default])" (id condition-property-accessor))) (p "Returns a procedure that can be called with any condition that satisfies " (tt "(condition-predicate ''kind-key'')") ". Given a condition that was created by " (tt "make-property-condition") " and " (i "kind-key") ", the procedure returns the value that is associated with " (i "prop-key") ". Given a composite condition created with " (tt "make-composite-condition") ", the procedure returns the value that is associated with " (i "prop-key") " in one of the components that satisfies " (tt "(condition-predicate ''kind-key'')") ".") (p "On CHICKEN, this procedure accepts an optional third argument DEFAULT. If the condition does not have a value for the desired property and if the optional argument is given, no error is signaled and the accessor returns the third argument.") (p "When the system raises an exception, the condition it passes to the exception handler includes the " (tt "'exn") " kind with the following properties:") (dl (dt "message") (dd "the error message") (dt "arguments") (dd "the arguments passed to the exception handler") (dt "location") (dd "the name of the procedure where the error occurred (if available)")) (p "Thus, if " (i "exn") " is a condition representing a system exception, then") (highlight scheme " ((condition-property-accessor 'exn 'message) exn)") (p "extracts the error message from " (i "exn") ". Example:") (highlight scheme "(handle-exceptions exn \n\t\t   (begin\n\t\t     (display \"Went wrong: \")\n\t\t     (display\n\t\t      ((condition-property-accessor 'exn 'message) exn))\n\t\t     (newline))\n (car '()))\n; displays something like \"Went wrong: can't take car of nil\""))
