more-conditions

API Reference

more-conditions

This system provides some generic condition classes in conjunction with support functions and macros.

MORE-CONDITIONS

This package provides generic conditions and condition-related
    utilities.

    Conditions
    * `chainable-condition'
    * `missing-required-argument'
      * `missing-required-initarg'
    * `incompatible-arguments'
      * `incompatible-initargs'
    * `reference-condition'
    * `progress-condition'
      * `simple-progress-condition'

    Condition helper functions
    * `maybe-print-cause'
    * `maybe-print-explanation'
    * `print-reference'

    Macros
    * `with-condition-translation'
    * `define-condition-translating-method'

    * `error-behavior-restart-cases'

    * `with-trivial-progress'
    * `with-sequence-progress'
  • Type REFERENCE-SPEC
    A documentation reference of the form (DOCUMENT PART [LINK]) where DOCUMENT is a keyword, PART is a string or list of strings and LINK, if present, is a string.
  • Function REFERENCE-DOCUMENT (spec)
    Return the document of SPEC.
  • Function REFERENCE-PART (spec)
    Return the part of SPEC.
  • Function REFERENCE-LINK (spec)
    Return the link of SPEC.
  • Type PROGRESS-DESIGNATOR
    Values describe progress of an operation. nil Progress is not known t Task has been completed. real Completion percentage as a real number between 0 (no progress) and 1 (completed; note that t should be used in this case, at least in a subsequently signaled condition).
  • Function PROGRESS->REAL (progress)
  • Variable *PRINT-REFERENCES*
    t
    When non-nil, `reference-condition' instances print reference information in addition to the primary condition report.
  • Generic-Function CAUSE (condition)
    Return the condition that was signaled and caused CONDITION to be signaled.
  • Method CAUSE ((condition condition))
  • Method CAUSE ((condition condition))
  • Method CAUSE ((condition condition))
  • Generic-Function ROOT-CAUSE (condition)
    Return the condition that was originally signaled and eventually caused CONDITION to be signaled.
  • Generic-Function CONDITION-REFERENCES (condition)
    Return a list of references (of type `reference-spec') which are associated to CONDITION.
  • Method CONDITION-REFERENCES ((condition t))
  • Method CONDITION-REFERENCES ((condition t))
  • Method CONDITION-REFERENCES ((condition t))
  • Method CONDITION-REFERENCES ((condition t))
  • Method CONDITION-REFERENCES ((condition t))
  • Method CONDITION-REFERENCES ((condition t))
  • Generic-Function DIRECT-DEFAULT-REFERENCES (class)
    Return a list of references (of type `reference-spec') which are the default references for CLASS (but not CLASSes superclasses; see `default-references').
  • Method DIRECT-DEFAULT-REFERENCES ((class class))
  • Method DIRECT-DEFAULT-REFERENCES ((class class))
  • Method DIRECT-DEFAULT-REFERENCES ((class class))
  • Method DIRECT-DEFAULT-REFERENCES ((class symbol))
  • Method DIRECT-DEFAULT-REFERENCES ((class symbol))
  • Method DIRECT-DEFAULT-REFERENCES ((class symbol))
  • Generic-Function DEFAULT-REFERENCES (class)
    Return a list of references (of type `reference-spec') which are the default references for CLASS (and all of CLASSes superclasses; i.e. transitive `direct-default-references'-closure).
  • Method DEFAULT-REFERENCES ((class class))
  • Method DEFAULT-REFERENCES ((class class))
  • Method DEFAULT-REFERENCES ((class class))
  • Method DEFAULT-REFERENCES ((class symbol))
  • Method DEFAULT-REFERENCES ((class symbol))
  • Method DEFAULT-REFERENCES ((class symbol))
  • Generic-Function PROGRESS-CONDITION-MESSAGE (condition)
    Return a string describing CONDITION or nil.
  • Method PROGRESS-CONDITION-MESSAGE ((condition condition))
  • Method PROGRESS-CONDITION-MESSAGE ((condition condition))
  • Method PROGRESS-CONDITION-MESSAGE ((condition condition))
  • Condition CHAINABLE-CONDITION  (CONDITION)
    Instances of this class can contain another condition instance which originally caused the condition to be signaled. This structure can continue recursively thus forming a chain of causing conditions.
  • Method ROOT-CAUSE ((condition chainable-condition))
  • Method CONDITION-REFERENCES ((condition chainable-condition))
  • Function MAYBE-PRINT-CAUSE (stream condition &optional colon? at?)
    Print the condition that caused CONDITION to be signaled (if any) onto STREAM.
  • Function MAYBE-PRINT-EXPLANATION (stream condition &optional colon? at?)
    Format the message contained in the `simple-condition' CONDITION on STREAM. If CONDITION does not have a message, print ".". This is intended for messages which can be either "MESSAGE." or "MESSAGE: EXPLANATION". When COLON? is non-nil, the explanation is printed in an indented logical block. When AT? is non-nil and CONDITION does not have an explanation, suppress printing ".".
  • Condition MISSING-REQUIRED-ARGUMENT  (PROGRAM-ERROR)
    This error is signaled when no value is supplied for a required parameter.
  • Function MISSING-REQUIRED-ARGUMENT (parameter)
    Signal a `missing-required-argument' error for PARAMETER.
  • Condition INCOMPATIBLE-ARGUMENTS  (PROGRAM-ERROR, CHAINABLE-CONDITION)
    This error is signaled when an incompatible combination of arguments is supplied.
  • Function INCOMPATIBLE-ARGUMENTS (&rest arguments)
    Signal an `incompatible-arguments' error for ARGUMENTS which has to be of the form PARAMETER1 VALUE1 PARAMETER2 VALUE2 ...
  • Condition INITARG-ERROR  (PROGRAM-ERROR)
    This error is signaled when invalid initargs are supplied.
  • Condition MISSING-REQUIRED-INITARG  (MISSING-REQUIRED-ARGUMENT, INITARG-ERROR)
    This error is signaled when an initarg that is required by a class is not supplied.
  • Function MISSING-REQUIRED-INITARG (class initarg)
    Signal a `missing-required-initarg' error for CLASS and INITARG.
  • Condition INCOMPATIBLE-INITARGS  (INCOMPATIBLE-ARGUMENTS, INITARG-ERROR)
    This error is signaled when incompatible initargs are supplied.
  • Function INCOMPATIBLE-INITARGS (class &rest initargs)
    Signal an `incompatible-initargs' error for CLASS and INITARGS.
  • Condition REFERENCE-CONDITION  (CONDITION)
    This condition class is intended to be mixed into condition classes which can associate documentation references to their instances.
  • Method CONDITION-REFERENCES ((condition reference-condition))
  • Condition PROGRESS-CONDITION  (CONDITION)
    This condition is signaled to indicate the progress of execution of an operation during the execution of that operation Note that this condition does not have to be handled and its signaling usually does not lead to a transfer of control.
  • Condition SIMPLE-PROGRESS-CONDITION  (PROGRESS-CONDITION, SIMPLE-CONDITION)
    Like `progress-condition' but supports format control and format arguments to produce a report to go along with the raw progress information.
  • Method PROGRESS-CONDITION-MESSAGE ((condition simple-progress-condition))
  • Function PROGRESS (&optional operation progress format-control-or-condition-class &rest format-arguments-or-initargs)
    Signal a progress condition indicating completion status PROGRESS for OPERATION. As with `cl:signal', `cl:error' and `cl:warn', FORMAT-CONTROL-OR-CONDITION-CLASS and FORMAT-ARGUMENTS-OR-INITARGS either specify a condition class and initargs or a report format control string or function with format arguments.
  • Function PROGRESSING (function operation &optional format-control-or-condition-class &rest format-arguments-or-initargs)
    Return a function which signals a progress condition for OPERATION and calls FUNCTION. As with `cl:signal', `cl:error' and `cl:warn', FORMAT-CONTROL-OR-CONDITION-CLASS and FORMAT-ARGUMENTS-OR-INITARGS either specify a condition class and initargs or a report format control string or function with format arguments. However, if FORMAT-CONTROL-OR-CONDITION-CLASS is nil, a format string which prints all arguments passed to FUNCTION is used. Example: (let ((items '(1 2 3 4 5))) (with-sequence-progress (:foo items) (mapcar (progressing #'1+ :foo "Frobbing") items)))
  • Function PRINT-REFERENCE (stream spec &optional at? colon?)
    Print reference SPEC onto STREAM. AT? and COLON? are ignored.
  • Macro WITH-CONDITION-TRANSLATION (clauses &body body)
    Execute BODY translating conditions as specified by CLAUSES when they are signaled. CLAUSES is a list of clauses of the form ((FROM-CONDITION TO-CONDITION &key var cause-initarg signal-via muffle?) INITARG1 VALUE1 INITARG2 VALUE2 ...) FROM-CONDITION specifies a condition type (as e.g. in `cl:handler-bind') instances of which should be translated to instances of the condition class designated by TO-CONDITION. The instance of TO-CONDITIONS is signaled via the value of :SIGNAL-VIA (default is `cl:error') and receives the initargs INITARG1 VALUE1, INITARG2 VALUE2, ... and the value of :CAUSE-INITARG (default is :CAUSE) with the original condition instance as its value. When the value of :CAUSE-INITARG is nil, the original condition is not passed to the constructed condition instance. If supplied, the value of :VAR names a variable in which the original condition instance should be received. MUFFLE? controls whether the original condition should be muffled after the translation has been performed. (This is useful for `cl:warning's and generic `cl:condition's which would not get handled by resignaling via e.g. `cl:warn'). CHAIN-SAME-CLASS? controls whether conditions which already are instances of TO-CONDITION should still be wrapped in a TO-CONDITION instance. The default is false.
  • Macro DEFINE-CONDITION-TRANSLATING-METHOD (name (&rest args) &body clauses)
    Define a method on the generic function designated by NAME which translates conditions according to CLAUSES (For a description of CLAUSES, see `with-condition-translation').
  • Macro ERROR-BEHAVIOR-RESTART-CASE ((var (error-condition &rest initargs &key &allow-other-keys) &key warning-condition (allow-other-values? t)) &body clauses)
    Select error/warning signaling of ERROR-CONDITION or WARNING-CONDITION according to VAR and establish restarts as specified in CLAUSES. CLAUSES use the same syntax as the restart clauses in `cl:restart-case'. INITARGS are passed to the constructed conditions. ALLOW-OTHER-VALUES? controls whether the form should evaluate to the value of VAR if it is not a function. Example: (flet ((try-policy (policy) (error-behavior-restart-case (policy (simple-error :format-control "Example error: ~A" :format-arguments (list :foo)) :warning-condition simple-warning :allow-other-values? t) (continue (&optional condition) :continue)))) ;; (try-policy #'error) => Error: Example error: FOO ;; (try-policy 'error) => Error: Example error: FOO (mapcar #'try-policy (list warn #'warn continue #'continue 1 :foo nil))) | WARNING: Example error: FOO | WARNING: Example error: FOO => (nil nil :continue :continue 1 :foo nil)
  • Macro WITH-TRIVIAL-PROGRESS ((operation &optional format-control-or-condition-class &rest format-arguments-or-initargs) &body body)
    Signal one progress condition for OPERATION for the start and end of the execution of BODY respectively. As with `cl:signal', `cl:error' and `cl:warn', FORMAT-CONTROL-OR-CONDITION-CLASS and FORMAT-ARGUMENTS-OR-INITARGS either specify a condition class and initargs or a report format control string and format arguments.
  • Macro WITH-SEQUENCE-PROGRESS ((operation sequence) &body body)
    Signal progress conditions for OPERATION on SEQUENCE during the execution of BODY. The function `progress' is shadowed in the lexical scope of BODY with the following syntax: progress [ format-control-or-condition-class format-arguments-or-initargs* ] Calling this function indicates that the processing of SEQUENCE advanced by one element. As with `cl:signal', `cl:error' and `cl:warn', FORMAT-CONTROL-OR-CONDITION-CLASS and FORMAT-ARGUMENTS-OR-INITARGS either specify a condition class and initargs or a report format control string and format arguments. After the completion of or non-local exit from BODY, a condition indicating the completion of OPERATION is signaled automatically.