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

more-conditions

* Introduction
  The =more-conditions= system contains some condition classes,
  functions and macros which may be useful when building slightly
  complex systems.

  One aspect handled by these classes is "chaining" of
  conditions. Chaining is one way to implement signaling and handling
  of conditions in a layered architecture: layers handle (not
  necessarily in the sense of unwinding the stack and transferring
  control) conditions signaled from lower layers by wrapping them in
  an appropriate condition instances and re-signaling. Support for
  this pattern is provided by the following classes, functions and
  macros:
  + =chainable-condition=
  + =cause= and =root-cause=
  + =maybe-print-cause=
  + =with-condition-translation=
  + =define-condition-translating-method=
  See [[*Condition Translation at Layer Boundaries]] below.

  Another aspect are custom simple conditions. The function
  =maybe-print-explanation= is intended to make writing report
  functions for custom simple conditions easier. See [[*Custom Simple
  Conditions]] below. =more-conditions= also provides a couple of
  specific =program-error= s:
  + =program-error=
    + =missing-required-argument=
      + =missing-required-initarg=
    + =incompatible-arguments=
      + =incompatible-initargs=
    + =initarg-error=
      + =missing-required-initarg=
      + =incompatible-initargs=

  Furthermore, =more-conditions= contains conditions for reporting
  progress of operations up the callstack in a minimally invasive
  way. See [[*Tracking and Reporting Progress of Operations]].

  Finally, =more-conditions= supports embedding documentation
  references in conditions via =condition-references= and the
  =reference-condition= mixin. See [[*Embedding Documentation References
  in Conditions]] below.


  #+ATTR_HTML: :alt "build status image" :title Build Status :align right
  [[https://travis-ci.org/scymtym/more-conditions][https://travis-ci.org/scymtym/more-conditions.svg]]

* Error Behaviors for Layered Systems
** Condition Translation at Layer Boundaries
   Assume some complex backend whose primary entry point is a =emit
   (NODE OPERATION TARGET)= function. Part of the backend interface is
   an =emit-error= condition. In such a situation, it is desirable to
   translate arbitrary conditions that may arise anywhere in the
   backend into the =emit-error= condition without loosing information
   regarding the root cause of the problem.

   Using =more-conditions=, the problem can be solved as follows:
   #+BEGIN_SRC lisp
   (defgeneric emit (node operation target))

   (define-condition emit-error (cl:error
                                 more-conditions:chainable-condition)
     ((node      :initarg :node
                 :reader  node)
      (operation :initarg :operation
                 :reader  operation)
      (target    :initarg :target
                 :reader  target))
     (:report (lambda (condition stream)
                (format stream "Could not ~S node ~A to target ~A~/more-conditions:maybe-print-cause/"
                        (operation condition)
                        (node condition)
                        (target condition)
                        condition))))

   (more-conditions:define-condition-translating-method emit (node operation target)
     ((error emit-error)
      :node node
      :operation operation
      :target target))

   (defmethod emit ((node real) (operation (eql :foo)) (target stream))
     (when (minusp node)
       (error "Cannot ~S for negative real node ~A."
              operation node)))
   #+END_SRC
   This does the following:
   + Translate any =error= condition into an =emit-error= condition
   + Store the node, operation, target and causing condition in the
     =emit-error= condition (can be retrieved via
     =more-conditions:cause= or =more-conditions:root-cause=)
   + Do not unwind the stack since translation is done in
     =handler-bind= rather than =handler-case=. This way the client can
     still determine the location of the causing condition.
   + Avoid wrapping multiple =emit-error= s around each other in case
     of recursive =emit= calls.

   Now =(emit -1 :foo *standard-output*)= signals an =emit-error= which
   describes the failed operation and contains a detailed description
   of the actual problem as its =more-conditions:cause=:
   #+BEGIN_EXAMPLE
   Could not :FOO node -1 to target #<SLIME-OUTPUT-STREAM {1005DAF453}> Caused by:
   > Cannot :FOO for negative real node -1.
   #+END_EXAMPLE
** Error Policies at Layer Boundaries
   When working with protocol functions, say =find-thing= for example,
   different behaviors in case of errors may be desirable under
   different circumstances such as
   + Return =nil= or some other value in case of errors in order to
     being able to write =(or (find-thing ARGS) SOMETHING-ELSE)=
     + For efficiency reasons, it made be desirable to avoid
       establishing handlers and/or restarts in this case
   + Return =nil= or some other value and signal a =style-warning=
     when a compile-time check fails or an optimization opportunity
     is missed
   + Signal an error when the computation cannot continue without the
     result
     + Establish restarts for higher layers to decide about error
       recovery

   =more-conditions= provides the =error-behavior-restart-case= macro
   for such situations. It can be used as demonstrated in the
   following example:
   #+BEGIN_SRC lisp
   (define-condition not-found-condition ()
     ((name :initarg :name)))

   (define-condition not-found-warning (warning not-found-condition)
     ())

   (define-condition not-found-error (error not-found-condition)
     ())

   (defmethod find-thing ((name t) &key)
     nil)

   (defmethod find-thing :around ((name t)
                                  &key (if-does-not-exist #'error))
     (or (call-next-method)
         (more-conditions:error-behavior-restart-case
          (if-does-not-exist (not-found-error :name name)
                             :warning-condition   not-found-warning
                             :allow-other-values? t)
          (retry ()
            (find-thing name))
          (use-value (value)
            value))))
   #+END_SRC
   Now, calling =find-thing= with different error policies results in
   different behaviors:
   #+BEGIN_SRC lisp
   (find-thing :foo)
   |- ERROR: Condition NOT-FOUND-ERROR was signalled

   (find-thing :foo :if-does-not-exist #'warn)
   | WARNING: Condition NOT-FOUND-WARNING was signalled
   => nil

   (find-thing :foo :if-does-not-exist nil)
   => nil

   (handler-bind ((error (lambda (c)
                           (declare (ignore c))
                           (invoke-restart 'use-value :value))))
     (find-thing :foo))
   => :value
   #+END_SRC
* Custom Simple Conditions
  A custom simple conditions can be defined as follows:
  #+BEGIN_SRC lisp
    (define-condition simple-frob-error (cl:error
                                         cl:simple-condition)
      ((foo :initarg :foo
            :reader  foo))
      (:report (lambda (condition stream)
                 (format stream "Could not frob ~S~/more-conditions:maybe-print-explanation/"
                         (foo condition)
                         condition))))

    (defun simple-frob-error (foo &optional format &rest args)
      (error 'simple-frob-error
             :foo              foo
             :format-control   format
             :format-arguments args))
  #+END_SRC
  Now =(simple-frob-error :bar)= and =(simple-frob-error :bar "Fez
  ~S." :whoop)= both produce nice reports.
* Tracking and Reporting Progress of Operations
  Despite the most frequently used condition superclasses, =cl:error=
  and =cl:warning=, the Common Lisp condition system allows arbitrary
  other subclasses of =cl:condition= which are not a-priori associated
  with certain control transfer behavior. The =more-conditions= system
  exploits this for providing a family of conditions which indicate
  progress of operations without necessarily affecting flow of control
  or program execution in general.

  The =more-conditions= system does not address the question of
  /handling/ progress conditions (But see
  [[http://github.com/scymtym/user-interface.progress][=user-interface.progress=]]). This is intended to allow "speculative"
  signaling of progress conditions from as many operations as possible
  without introducing dependencies beyond =more-conditions= into the
  signaling system. Further, signaling code does not have to care or
  even know whether the signaled progress conditions are actually
  handled or not in a particular situation since program execution
  remains unaffected. Despite the hopefully low impact on program
  design and code organization, there is some overhead involved in
  signaling, and potentially handling, progress conditions. Therefore,
  some amount of care is required when signaling progress conditions
  form inner loops.

  In the =more-conditions= system, there are two builtin progress
  condition classes: =more-conditions:progress-condition= and
  =more-conditions:simple-progress-condition=. Support for signaling
  these conditions is provided in form of the function
  =more-conditions:progress= and the macros
  =more-conditions:with-trivial-progress= and
  =more-conditions:with-sequence-progress=.

  These can be used as follows (the outer =cl:handler-bind= is
  required for the signaled progress conditions to produce an
  observable effect):
  #+BEGIN_SRC lisp
  (handler-bind ((more-conditions:progress-condition #'princ))
    (more-conditions:progress :my-operation 0 "Preparing")
    (sleep 1)
    (more-conditions:progress :my-operation 1/3 "Processing ~A" :data)
    (sleep 1)
    (more-conditions:progress :my-operation 2/3 "Cleaning up")
    (sleep 1)
    (more-conditions:progress :my-operation t))
  #+END_SRC

  The =more-conditions:with-trivial-progress= macro can be used to
  indicate execution of long running operations without reporting
  detailed progress during execution:
  #+BEGIN_SRC lisp
  (handler-bind ((more-conditions:progress-condition #'princ))
    (more-conditions:with-trivial-progress (:factorial "Computing factorial of ~D" 1000)
      (alexandria:factorial 1000)))
  #+END_SRC

  For the common case of processing data sequentially, the
  =more-conditions:with-sequence-progress= macro can be used to
  easily signal progress conditions:
  #+BEGIN_SRC lisp
  (handler-bind ((more-conditions:progress-condition #'princ))
    (let ((items (alexandria:iota 5)))
      (more-conditions:with-sequence-progress (:frob items)
        (dolist (item items)
          (more-conditions:progress "Processing element ~A" item)
          (sleep 1)))))
  #+END_SRC
  When using higher-order functions to process sequences the
  =more-conditions:progressing= function can be used:
  #+BEGIN_SRC lisp
  (handler-bind ((more-conditions:progress-condition #'princ))
    (let ((items (alexandria:iota 5)))
      (more-conditions:with-sequence-progress (:frob items)
        (mapcar (more-conditions:progressing #'1+ :frob) items))))
  #+END_SRC
* Embedding Documentation References in Conditions
  It is sometimes useful to include pointers to documentation in
  signaled conditions. =more-conditions= supports this via the generic
  function =condition-references= and the mixin class
  =reference-condition=. =condition-references= returns a list of
  references of the form =(DOCUMENT PART [LINK])=. The type
  =reference-spec= and the readers =reference-document=,
  =reference-part=, =reference-link= deal with these
  references. =reference-condition= stores a list of such references
  and =condition-references= collects all references traversing
  =cause= relations.

  For example, the following condition
  #+BEGIN_SRC lisp
  (define-condition foo-error (error
                               more-conditions:reference-condition
                               more-conditions:chainable-condition)
    ()
    (:report (lambda (condition stream)
               ;; Prevent reference printing in causing condition(s)
               (let ((more-conditions:*print-references* nil))
                 (format stream "Foo Error.~/more-conditions:maybe-print-cause/"
                         condition)))))

  (error 'foo-error
         :cause      (make-condition 'foo-error
                                     :references '((:foo "bar")
                                                   (:foo "baz")
                                                   (:bar "fez" "http://whoop.org")))
         :references '((:foo "bar")
                       (:fez "whiz")))
  #+END_SRC
  would print the following report:
  #+BEGIN_EXAMPLE
  Foo Error. Caused by:
  > Foo Error.
  See also:
    FOO, bar
    FOO, baz
    BAR, fez <http://whoop.org>
    FEZ, whiz
  #+END_EXAMPLE
  Note how references from the causing condition are collected and
  printed.

* settings                                                         :noexport:

# Local Variables:
# mode: org
# End:


alexandria

closer-mop

The idea is similar to
                     `alexandria:required-argument' but more
                     fine-grained.

                     In addition, there is support for translating
                     conditions at layer boundaries in larger systems.

fiveam

let-plus

Unit tests for the more-conditions system.

more-conditions

Upstream URL

Author

Maintainer

License

more-conditions

Version:

License:

Authors:

Maintainers:

Dependencies:

more-conditions/test

Version:

License:

Authors:

Maintainers:

Dependencies:

Dependencies (4)

Dependents (6)