The more-conditions Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The more-conditions Reference Manual

This is the more-conditions Reference Manual, version 0.4.5, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:18:43 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

* 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 # 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= 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 
    FEZ, whiz
  #+END_EXAMPLE
  Note how references from the causing condition are collected and
  printed.

* settings                                                         :noexport:

# Local Variables:
# mode: org
# End:


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 more-conditions

Maintainer

Jan Moringen <jmoringe@techfak.uni-bielefeld.de>

Author

Jan Moringen <jmoringe@techfak.uni-bielefeld.de>

License

LLGPLv3

Description

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

Long Description

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.

Version

0.4.5

Dependencies
Source

more-conditions.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 more-conditions/src

Parent

more-conditions (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Next: , Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 more-conditions.asd

Location

more-conditions.asd

Systems

more-conditions (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 more-conditions/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

more-conditions


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 more-conditions/src/types.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/types.lisp

Exported Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.4 more-conditions/src/variables.lisp

Dependency

types.lisp (file)

Parent

src (module)

Location

src/variables.lisp

Exported Definitions

*print-references* (special variable)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.5 more-conditions/src/protocol.lisp

Dependency

variables.lisp (file)

Parent

src (module)

Location

src/protocol.lisp

Exported Definitions
Internal Definitions

default-initarg-value (function)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.6 more-conditions/src/conditions.lisp

Dependency

protocol.lisp (file)

Parent

src (module)

Location

src/conditions.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

4.1.7 more-conditions/src/macros.lisp

Dependency

conditions.lisp (file)

Parent

src (module)

Location

src/macros.lisp

Exported Definitions

Previous: , Up: Files   [Contents][Index]

4.2 Other


Previous: , Up: Other files   [Contents][Index]

4.2.1 more-conditions/README.org

Parent

more-conditions (system)

Location

README.org


Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

5.1 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’

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Special variables

Special Variable: *print-references*

When non-nil, ‘reference-condition’ instances print reference information in addition to the primary condition report.

Package

more-conditions

Source

variables.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Macros

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’).

Package

more-conditions

Source

macros.lisp (file)

Macro: error-behavior-restart-case (VAR (ERROR-CONDITION &rest INITARGS &key &allow-other-keys) &key WARNING-CONDITION ALLOW-OTHER-VALUES?) &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)

Package

more-conditions

Source

macros.lisp (file)

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.

Package

more-conditions

Source

macros.lisp (file)

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.

Package

more-conditions

Source

macros.lisp (file)

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.

Package

more-conditions

Source

macros.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Functions

Function: incompatible-arguments &rest ARGUMENTS

Signal an ‘incompatible-arguments’ error for ARGUMENTS which has to be of the form

PARAMETER1 VALUE1 PARAMETER2 VALUE2 ...

Package

more-conditions

Source

conditions.lisp (file)

Function: incompatible-initargs CLASS &rest INITARGS

Signal an ‘incompatible-initargs’ error for CLASS and INITARGS.

Package

more-conditions

Source

conditions.lisp (file)

Function: maybe-print-cause STREAM CONDITION &optional COLON? AT?

Print the condition that caused CONDITION to be signaled (if any) onto STREAM.

Package

more-conditions

Source

conditions.lisp (file)

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 ".".

Package

more-conditions

Source

conditions.lisp (file)

Function: missing-required-argument PARAMETER

Signal a ‘missing-required-argument’ error for PARAMETER.

Package

more-conditions

Source

conditions.lisp (file)

Function: missing-required-initarg CLASS INITARG

Signal a ‘missing-required-initarg’ error for CLASS and INITARG.

Package

more-conditions

Source

conditions.lisp (file)

Function: print-reference STREAM SPEC &optional AT? COLON?

Print reference SPEC onto STREAM. AT? and COLON? are ignored.

Package

more-conditions

Source

conditions.lisp (file)

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.

Package

more-conditions

Source

conditions.lisp (file)

Function: progress->real PROGRESS
Package

more-conditions

Source

types.lisp (file)

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)))

Package

more-conditions

Source

conditions.lisp (file)

Function: reference-document SPEC

Return the document of SPEC.

Package

more-conditions

Source

types.lisp (file)

Function: reference-link SPEC

Return the link of SPEC.

Package

more-conditions

Source

types.lisp (file)

Function: reference-part SPEC

Return the part of SPEC.

Package

more-conditions

Source

types.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.4 Generic functions

Generic Function: cause CONDITION

Return the condition that was signaled and caused CONDITION to be signaled.

Package

more-conditions

Source

protocol.lisp (file)

Methods
Method: cause (CONDITION chainable-condition)
Source

conditions.lisp (file)

Method: cause (CONDITION condition)
Generic Function: condition-references CONDITION

Return a list of references (of type ‘reference-spec’) which are associated to CONDITION.

Package

more-conditions

Source

protocol.lisp (file)

Methods
Method: condition-references (CONDITION reference-condition)
Source

conditions.lisp (file)

Method: condition-references (CONDITION chainable-condition) around
Source

conditions.lisp (file)

Method: condition-references CONDITION
Method: condition-references CONDITION around
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).

Package

more-conditions

Source

protocol.lisp (file)

Methods
Method: default-references (CLASS symbol)
Method: default-references (CLASS class)
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’).

Package

more-conditions

Source

protocol.lisp (file)

Methods
Method: direct-default-references (CLASS symbol)
Method: direct-default-references (CLASS class)
Generic Function: incompatible-arguments-parameters CONDITION
Package

more-conditions

Methods
Method: incompatible-arguments-parameters (CONDITION incompatible-arguments)
Source

conditions.lisp (file)

Generic Function: incompatible-arguments-values CONDITION
Package

more-conditions

Methods
Method: incompatible-arguments-values (CONDITION incompatible-arguments)
Source

conditions.lisp (file)

Generic Function: initarg-error-class CONDITION
Package

more-conditions

Methods
Method: initarg-error-class (CONDITION initarg-error)
Source

conditions.lisp (file)

Generic Function: missing-required-argument-parameter CONDITION
Package

more-conditions

Methods
Method: missing-required-argument-parameter (CONDITION missing-required-argument)
Source

conditions.lisp (file)

Generic Function: progress-condition-message CONDITION

Return a string describing CONDITION or nil.

Package

more-conditions

Source

protocol.lisp (file)

Methods
Method: progress-condition-message (CONDITION simple-progress-condition)
Source

conditions.lisp (file)

Method: progress-condition-message (CONDITION condition)
Generic Function: progress-condition-operation CONDITION
Package

more-conditions

Methods
Method: progress-condition-operation (CONDITION progress-condition)
Source

conditions.lisp (file)

Generic Function: progress-condition-progress CONDITION
Generic Function: (setf progress-condition-progress) NEW-VALUE CONDITION
Package

more-conditions

Methods
Method: progress-condition-progress (CONDITION progress-condition)
Method: (setf progress-condition-progress) NEW-VALUE (CONDITION progress-condition)
Source

conditions.lisp (file)

Generic Function: root-cause CONDITION

Return the condition that was originally signaled and eventually caused CONDITION to be signaled.

Package

more-conditions

Source

protocol.lisp (file)

Methods
Method: root-cause (CONDITION chainable-condition)
Source

conditions.lisp (file)

Method: root-cause (CONDITION condition)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.5 Conditions

Condition: chainable-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.

Package

more-conditions

Source

conditions.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses

incompatible-arguments (condition)

Direct methods
Direct slots
Slot: cause

The condition which originally caused the condition to be signaled.

Initargs

:cause

Initform

(quote nil)

Readers

cause (generic function)

Condition: incompatible-arguments ()

This error is signaled when an incompatible combination of arguments is supplied.

Package

more-conditions

Source

conditions.lisp (file)

Direct superclasses
Direct subclasses

incompatible-initargs (condition)

Direct methods
Direct slots
Slot: parameters

A list of the parameters for which incompatible values have been supplied.

Initargs

:parameters

Readers

incompatible-arguments-parameters (generic function)

Slot: values

A list of the incompatible values.

Initargs

:values

Readers

incompatible-arguments-values (generic function)

Direct Default Initargs
InitargValue
:values(more-conditions:missing-required-initarg (quote more-conditions:incompatible-arguments) :values)
:parameters(more-conditions:missing-required-initarg (quote more-conditions:incompatible-arguments) :parameters)
Condition: incompatible-initargs ()

This error is signaled when incompatible initargs are supplied.

Package

more-conditions

Source

conditions.lisp (file)

Direct superclasses
Condition: initarg-error ()

This error is signaled when invalid initargs are supplied.

Package

more-conditions

Source

conditions.lisp (file)

Direct superclasses

program-error (condition)

Direct subclasses
Direct methods

initarg-error-class (method)

Direct slots
Slot: class

The class for which the initarg error occurred.

Initargs

:class

Readers

initarg-error-class (generic function)

Direct Default Initargs
InitargValue
:class(more-conditions:missing-required-initarg (quote more-conditions:initarg-error) :class)
Condition: missing-required-argument ()

This error is signaled when no value is supplied for a required parameter.

Package

more-conditions

Source

conditions.lisp (file)

Direct superclasses

program-error (condition)

Direct subclasses

missing-required-initarg (condition)

Direct methods

missing-required-argument-parameter (method)

Direct slots
Slot: parameter

The parameter for which a value should have been supplied.

Initargs

:parameter

Readers

missing-required-argument-parameter (generic function)

Direct Default Initargs
InitargValue
:parameter(more-conditions:missing-required-initarg (quote more-conditions:missing-required-argument) :parameter)
Condition: missing-required-initarg ()

This error is signaled when an initarg that is required by a class is not supplied.

Package

more-conditions

Source

conditions.lisp (file)

Direct superclasses
Condition: progress-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.

Package

more-conditions

Source

conditions.lisp (file)

Direct superclasses

condition (condition)

Direct subclasses

simple-progress-condition (condition)

Direct methods
Direct slots
Slot: operation

Stores a symbol identifying the operation for which the condition reports progress.

Initargs

:operation

Initform

(quote nil)

Readers

progress-condition-operation (generic function)

Slot: progress

Stores the operation progress indicated by the condition. See type ‘progress-designator’.

Initargs

:progress

Initform

(quote nil)

Readers

progress-condition-progress (generic function)

Writers

(setf progress-condition-progress) (generic function)

Condition: reference-condition ()

This condition class is intended to be mixed into condition classes which can associate documentation references to their instances.

Package

more-conditions

Source

conditions.lisp (file)

Direct superclasses

condition (condition)

Direct methods
Direct slots
Slot: references

Stores a list of references of type ‘reference-spec’.

Initargs

:references

Initform

(quote :compute)

Readers

condition-%references (generic function)

Writers

(setf condition-%references) (generic function)

Condition: simple-progress-condition ()

Like ‘progress-condition’ but supports format control and format arguments to produce a report to go along with the raw progress information.

Package

more-conditions

Source

conditions.lisp (file)

Direct superclasses
Direct methods

Previous: , Up: Exported definitions   [Contents][Index]

6.1.6 Types

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).

Package

more-conditions

Source

types.lisp (file)

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.

Package

more-conditions

Source

types.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Functions

Function: %progress &optional OPERATION PROGRESS FORMAT-CONTROL-OR-CONDITION-CLASS &rest FORMAT-ARGUMENTS-OR-INITARGS
Package

more-conditions

Source

conditions.lisp (file)

Function: default-initarg-value CLASS INITARG
Package

more-conditions

Source

protocol.lisp (file)

Function: print-arguments STREAM PARAMETERS-AND-VALUES &optional AT? COLON?

Print PARAMETERS-AND-VALUES which has to be of the form

(PARAMETERS VALUES)

onto STREAM. AT? and COLON? are ignored.

Package

more-conditions

Source

conditions.lisp (file)

Function: print-progress-percentage STREAM PROGRESS &optional COLON? AT?
Package

more-conditions

Source

conditions.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Generic functions

Generic Function: condition-%references CONDITION
Generic Function: (setf condition-%references) NEW-VALUE CONDITION
Package

more-conditions

Methods
Method: condition-%references (CONDITION reference-condition)
Method: (setf condition-%references) NEW-VALUE (CONDITION reference-condition)
Source

conditions.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M   O  
Index Entry  Section

F
File, Lisp, more-conditions.asd: The more-conditions<dot>asd file
File, Lisp, more-conditions/src/conditions.lisp: The more-conditions/src/conditions<dot>lisp file
File, Lisp, more-conditions/src/macros.lisp: The more-conditions/src/macros<dot>lisp file
File, Lisp, more-conditions/src/package.lisp: The more-conditions/src/package<dot>lisp file
File, Lisp, more-conditions/src/protocol.lisp: The more-conditions/src/protocol<dot>lisp file
File, Lisp, more-conditions/src/types.lisp: The more-conditions/src/types<dot>lisp file
File, Lisp, more-conditions/src/variables.lisp: The more-conditions/src/variables<dot>lisp file
File, other, more-conditions/README.org: The more-conditions/readme<dot>org file

L
Lisp File, more-conditions.asd: The more-conditions<dot>asd file
Lisp File, more-conditions/src/conditions.lisp: The more-conditions/src/conditions<dot>lisp file
Lisp File, more-conditions/src/macros.lisp: The more-conditions/src/macros<dot>lisp file
Lisp File, more-conditions/src/package.lisp: The more-conditions/src/package<dot>lisp file
Lisp File, more-conditions/src/protocol.lisp: The more-conditions/src/protocol<dot>lisp file
Lisp File, more-conditions/src/types.lisp: The more-conditions/src/types<dot>lisp file
Lisp File, more-conditions/src/variables.lisp: The more-conditions/src/variables<dot>lisp file

M
Module, more-conditions/src: The more-conditions/src module
more-conditions.asd: The more-conditions<dot>asd file
more-conditions/README.org: The more-conditions/readme<dot>org file
more-conditions/src: The more-conditions/src module
more-conditions/src/conditions.lisp: The more-conditions/src/conditions<dot>lisp file
more-conditions/src/macros.lisp: The more-conditions/src/macros<dot>lisp file
more-conditions/src/package.lisp: The more-conditions/src/package<dot>lisp file
more-conditions/src/protocol.lisp: The more-conditions/src/protocol<dot>lisp file
more-conditions/src/types.lisp: The more-conditions/src/types<dot>lisp file
more-conditions/src/variables.lisp: The more-conditions/src/variables<dot>lisp file

O
Other File, more-conditions/README.org: The more-conditions/readme<dot>org file

Jump to:   F   L   M   O  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
C   D   E   F   G   I   M   P   R   W  
Index Entry  Section

%
%progress: Internal functions

(
(setf condition-%references): Internal generic functions
(setf condition-%references): Internal generic functions
(setf progress-condition-progress): Exported generic functions
(setf progress-condition-progress): Exported generic functions

C
cause: Exported generic functions
cause: Exported generic functions
cause: Exported generic functions
condition-%references: Internal generic functions
condition-%references: Internal generic functions
condition-references: Exported generic functions
condition-references: Exported generic functions
condition-references: Exported generic functions
condition-references: Exported generic functions
condition-references: Exported generic functions

D
default-initarg-value: Internal functions
default-references: Exported generic functions
default-references: Exported generic functions
default-references: Exported generic functions
define-condition-translating-method: Exported macros
direct-default-references: Exported generic functions
direct-default-references: Exported generic functions
direct-default-references: Exported generic functions

E
error-behavior-restart-case: Exported macros

F
Function, %progress: Internal functions
Function, default-initarg-value: Internal functions
Function, incompatible-arguments: Exported functions
Function, incompatible-initargs: Exported functions
Function, maybe-print-cause: Exported functions
Function, maybe-print-explanation: Exported functions
Function, missing-required-argument: Exported functions
Function, missing-required-initarg: Exported functions
Function, print-arguments: Internal functions
Function, print-progress-percentage: Internal functions
Function, print-reference: Exported functions
Function, progress: Exported functions
Function, progress->real: Exported functions
Function, progressing: Exported functions
Function, reference-document: Exported functions
Function, reference-link: Exported functions
Function, reference-part: Exported functions

G
Generic Function, (setf condition-%references): Internal generic functions
Generic Function, (setf progress-condition-progress): Exported generic functions
Generic Function, cause: Exported generic functions
Generic Function, condition-%references: Internal generic functions
Generic Function, condition-references: Exported generic functions
Generic Function, default-references: Exported generic functions
Generic Function, direct-default-references: Exported generic functions
Generic Function, incompatible-arguments-parameters: Exported generic functions
Generic Function, incompatible-arguments-values: Exported generic functions
Generic Function, initarg-error-class: Exported generic functions
Generic Function, missing-required-argument-parameter: Exported generic functions
Generic Function, progress-condition-message: Exported generic functions
Generic Function, progress-condition-operation: Exported generic functions
Generic Function, progress-condition-progress: Exported generic functions
Generic Function, root-cause: Exported generic functions

I
incompatible-arguments: Exported functions
incompatible-arguments-parameters: Exported generic functions
incompatible-arguments-parameters: Exported generic functions
incompatible-arguments-values: Exported generic functions
incompatible-arguments-values: Exported generic functions
incompatible-initargs: Exported functions
initarg-error-class: Exported generic functions
initarg-error-class: Exported generic functions

M
Macro, define-condition-translating-method: Exported macros
Macro, error-behavior-restart-case: Exported macros
Macro, with-condition-translation: Exported macros
Macro, with-sequence-progress: Exported macros
Macro, with-trivial-progress: Exported macros
maybe-print-cause: Exported functions
maybe-print-explanation: Exported functions
Method, (setf condition-%references): Internal generic functions
Method, (setf progress-condition-progress): Exported generic functions
Method, cause: Exported generic functions
Method, cause: Exported generic functions
Method, condition-%references: Internal generic functions
Method, condition-references: Exported generic functions
Method, condition-references: Exported generic functions
Method, condition-references: Exported generic functions
Method, condition-references: Exported generic functions
Method, default-references: Exported generic functions
Method, default-references: Exported generic functions
Method, direct-default-references: Exported generic functions
Method, direct-default-references: Exported generic functions
Method, incompatible-arguments-parameters: Exported generic functions
Method, incompatible-arguments-values: Exported generic functions
Method, initarg-error-class: Exported generic functions
Method, missing-required-argument-parameter: Exported generic functions
Method, progress-condition-message: Exported generic functions
Method, progress-condition-message: Exported generic functions
Method, progress-condition-operation: Exported generic functions
Method, progress-condition-progress: Exported generic functions
Method, root-cause: Exported generic functions
Method, root-cause: Exported generic functions
missing-required-argument: Exported functions
missing-required-argument-parameter: Exported generic functions
missing-required-argument-parameter: Exported generic functions
missing-required-initarg: Exported functions

P
print-arguments: Internal functions
print-progress-percentage: Internal functions
print-reference: Exported functions
progress: Exported functions
progress->real: Exported functions
progress-condition-message: Exported generic functions
progress-condition-message: Exported generic functions
progress-condition-message: Exported generic functions
progress-condition-operation: Exported generic functions
progress-condition-operation: Exported generic functions
progress-condition-progress: Exported generic functions
progress-condition-progress: Exported generic functions
progressing: Exported functions

R
reference-document: Exported functions
reference-link: Exported functions
reference-part: Exported functions
root-cause: Exported generic functions
root-cause: Exported generic functions
root-cause: Exported generic functions

W
with-condition-translation: Exported macros
with-sequence-progress: Exported macros
with-trivial-progress: Exported macros

Jump to:   %   (  
C   D   E   F   G   I   M   P   R   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
C   O   P   R   S   V  
Index Entry  Section

*
*print-references*: Exported special variables

C
cause: Exported conditions
class: Exported conditions

O
operation: Exported conditions

P
parameter: Exported conditions
parameters: Exported conditions
progress: Exported conditions

R
references: Exported conditions

S
Slot, cause: Exported conditions
Slot, class: Exported conditions
Slot, operation: Exported conditions
Slot, parameter: Exported conditions
Slot, parameters: Exported conditions
Slot, progress: Exported conditions
Slot, references: Exported conditions
Slot, values: Exported conditions
Special Variable, *print-references*: Exported special variables

V
values: Exported conditions

Jump to:   *  
C   O   P   R   S   V  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   I   M   P   R   S   T  
Index Entry  Section

C
chainable-condition: Exported conditions
Condition, chainable-condition: Exported conditions
Condition, incompatible-arguments: Exported conditions
Condition, incompatible-initargs: Exported conditions
Condition, initarg-error: Exported conditions
Condition, missing-required-argument: Exported conditions
Condition, missing-required-initarg: Exported conditions
Condition, progress-condition: Exported conditions
Condition, reference-condition: Exported conditions
Condition, simple-progress-condition: Exported conditions

I
incompatible-arguments: Exported conditions
incompatible-initargs: Exported conditions
initarg-error: Exported conditions

M
missing-required-argument: Exported conditions
missing-required-initarg: Exported conditions
more-conditions: The more-conditions system
more-conditions: The more-conditions package

P
Package, more-conditions: The more-conditions package
progress-condition: Exported conditions
progress-designator: Exported types

R
reference-condition: Exported conditions
reference-spec: Exported types

S
simple-progress-condition: Exported conditions
System, more-conditions: The more-conditions system

T
Type, progress-designator: Exported types
Type, reference-spec: Exported types

Jump to:   C   I   M   P   R   S   T