rework the exception hierarchy; refs #8363

changelog.md

@@ -177,6 +177,10 @@
   anywhere. Note that this has **nothing** to do with the ``--gc:regions`` switch
   of managing memory.
 
+- The exception hierarchy was slightly reworked, ``SystemError`` was renamed to
+  ``Error`` and is the new base class for any exception that is guaranteed to
+  be catchable. This change should have minimal impact on most existing Nim code.
+
 
 ### Tool changes
 

doc/exception_hierarchy_fragment.txt

@@ -1,28 +0,0 @@
-* `Exception <system.html#Exception>`_
-  * `AccessViolationError <system.html#AccessViolationError>`_
-  * `ArithmeticError <system.html#ArithmeticError>`_
-    * `DivByZeroError <system.html#DivByZeroError>`_
-    * `OverflowError <system.html#OverflowError>`_
-  * `AssertionError <system.html#AssertionError>`_
-  * `DeadThreadError <system.html#DeadThreadError>`_
-  * `FloatingPointError <system.html#FloatingPointError>`_
-    * `FloatDivByZeroError <system.html#FloatDivByZeroError>`_
-    * `FloatInexactError <system.html#FloatInexactError>`_
-    * `FloatInvalidOpError <system.html#FloatInvalidOpError>`_
-    * `FloatOverflowError <system.html#FloatOverflowError>`_
-    * `FloatUnderflowError <system.html#FloatUnderflowError>`_
-  * `FieldError <system.html#FieldError>`_
-  * `IndexError <system.html#IndexError>`_
-  * `ObjectAssignmentError <system.html#ObjectAssignmentError>`_
-  * `ObjectConversionError <system.html#ObjectConversionError>`_
-  * `ValueError <system.html#ValueError>`_
-    * `KeyError <system.html#KeyError>`_
-  * `ReraiseError <system.html#ReraiseError>`_
-  * `RangeError <system.html#RangeError>`_
-  * `OutOfMemoryError <system.html#OutOfMemoryError>`_
-  * `ResourceExhaustedError <system.html#ResourceExhaustedError>`_
-  * `StackOverflowError <system.html#StackOverflowError>`_
-  * `SystemError <system.html#SystemError>`_
-    * `IOError <system.html#IOError>`_
-    * `OSError <system.html#OSError>`_
-      * `LibraryError <system.html#LibraryError>`_

doc/manual.rst

@@ -3968,9 +3968,12 @@ exception.
 Exception hierarchy
 -------------------
 
-The exception tree is defined in the `system <system.html>`_ module:
+The exception tree is defined in the `system <system.html>`_ module.
-
+Every exception inherits from ``system.Exception``. Exceptions that indicate
-.. include:: exception_hierarchy_fragment.txt
+programming bugs inherit from ``system.Defect`` (which is a subtype of ``Exception``)
+and are stricly speaking not catchable as they can also be mapped to an operation
+that terminates the whole process. Exceptions that indicate any other runtime error
+that can be caught inherit from ``system.Error`` (which is a subtype of ``Exception``).
 
 
 Imported exceptions

lib/pure/smtp.nim

@@ -119,8 +119,7 @@ proc newSmtp*(useSsl = false, debug=false,
     when compiledWithSsl:
       sslContext.wrapSocket(result.sock)
     else:
-      raise newException(SystemError,
+      {.error: "SMTP module compiled without SSL support".}
-                         "SMTP module compiled without SSL support")
 
 proc newAsyncSmtp*(useSsl = false, debug=false,
                    sslContext = defaultSslContext): AsyncSmtp =
@@ -133,8 +132,7 @@ proc newAsyncSmtp*(useSsl = false, debug=false,
     when compiledWithSsl:
       sslContext.wrapSocket(result.sock)
     else:
-      raise newException(SystemError,
+      {.error: "SMTP module compiled without SSL support".}
-                         "SMTP module compiled without SSL support")
 
 proc quitExcpt(smtp: AsyncSmtp, msg: string): Future[void] =
   var retFuture = newFuture[void]()

lib/system.nim

@@ -484,141 +484,103 @@ type
     raise_id: uint # set when exception is raised
     up: ref Exception # used for stacking exceptions. Not exported!
 
-  SystemError* = object of Exception ## \
+  Defect* = object of Exception ## \
-    ## Abstract class for exceptions that the runtime system raises.
+    ## Abstract base class for all exceptions that Nim's runtime raises
-    ##
+    ## but that are strictly uncatchable as they can also be mapped to
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
+    ## a ``quit`` / ``trap`` / ``exit`` operation.
-  IOError* = object of SystemError ## \
+
+  Error* = object of Exception ## \
+    ## Abstract class for all exceptions that are catchable.
+  IOError* = object of Error ## \
     ## Raised if an IO error occurred.
-    ##
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
   EOFError* = object of IOError ## \
     ## Raised if an IO "end of file" error occurred.
-    ##
+  OSError* = object of Error ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  OSError* = object of SystemError ## \
     ## Raised if an operating system service failed.
-    ##
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
     errorCode*: int32 ## OS-defined error code describing this error.
   LibraryError* = object of OSError ## \
     ## Raised if a dynamic library could not be loaded.
-    ##
+  ResourceExhaustedError* = object of Error ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  ResourceExhaustedError* = object of SystemError ## \
     ## Raised if a resource request could not be fulfilled.
-    ##
+  ArithmeticError* = object of Defect ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  ArithmeticError* = object of Exception ## \
     ## Raised if any kind of arithmetic error occurred.
-    ##
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
   DivByZeroError* = object of ArithmeticError ## \
     ## Raised for runtime integer divide-by-zero errors.
-    ##
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
 
   OverflowError* = object of ArithmeticError ## \
     ## Raised for runtime integer overflows.
     ##
     ## This happens for calculations whose results are too large to fit in the
-    ## provided bits.  See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
+    ## provided bits.
-  AccessViolationError* = object of Exception ## \
+  AccessViolationError* = object of Defect ## \
     ## Raised for invalid memory access errors
-    ##
+  AssertionError* = object of Defect ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  AssertionError* = object of Exception ## \
     ## Raised when assertion is proved wrong.
     ##
-    ## Usually the result of using the `assert() template <#assert>`_.  See the
+    ## Usually the result of using the `assert() template <#assert>`_.
-    ## full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
+  ValueError* = object of Defect ## \
-  ValueError* = object of Exception ## \
     ## Raised for string and object conversion errors.
   KeyError* = object of ValueError ## \
     ## Raised if a key cannot be found in a table.
     ##
     ## Mostly used by the `tables <tables.html>`_ module, it can also be raised
     ## by other collection modules like `sets <sets.html>`_ or `strtabs
-    ## <strtabs.html>`_. See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
+    ## <strtabs.html>`_.
-  OutOfMemError* = object of SystemError ## \
+  OutOfMemError* = object of Defect ## \
     ## Raised for unsuccessful attempts to allocate memory.
-    ##
+  IndexError* = object of Defect ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  IndexError* = object of Exception ## \
     ## Raised if an array index is out of bounds.
-    ##
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
 
-  FieldError* = object of Exception ## \
+  FieldError* = object of Defect ## \
     ## Raised if a record field is not accessible because its dicriminant's
     ## value does not fit.
-    ##
+  RangeError* = object of Defect ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  RangeError* = object of Exception ## \
     ## Raised if a range check error occurred.
-    ##
+  StackOverflowError* = object of Defect ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  StackOverflowError* = object of SystemError ## \
     ## Raised if the hardware stack used for subroutine calls overflowed.
-    ##
+  ReraiseError* = object of Defect ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  ReraiseError* = object of Exception ## \
     ## Raised if there is no exception to reraise.
-    ##
+  ObjectAssignmentError* = object of Defect ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  ObjectAssignmentError* = object of Exception ## \
     ## Raised if an object gets assigned to its parent's object.
-    ##
+  ObjectConversionError* = object of Defect ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  ObjectConversionError* = object of Exception ## \
     ## Raised if an object is converted to an incompatible object type.
     ## You can use ``of`` operator to check if conversion will succeed.
-    ##
+  FloatingPointError* = object of Defect ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  FloatingPointError* = object of Exception ## \
     ## Base class for floating point exceptions.
-    ##
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
   FloatInvalidOpError* = object of FloatingPointError ## \
     ## Raised by invalid operations according to IEEE.
     ##
-    ## Raised by ``0.0/0.0``, for example.  See the full `exception
+    ## Raised by ``0.0/0.0``, for example.
-    ## hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
   FloatDivByZeroError* = object of FloatingPointError ## \
     ## Raised by division by zero.
     ##
-    ## Divisor is zero and dividend is a finite nonzero number.  See the full
+    ## Divisor is zero and dividend is a finite nonzero number.
-    ## `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
   FloatOverflowError* = object of FloatingPointError ## \
     ## Raised for overflows.
     ##
     ## The operation produced a result that exceeds the range of the exponent.
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
   FloatUnderflowError* = object of FloatingPointError ## \
     ## Raised for underflows.
     ##
     ## The operation produced a result that is too small to be represented as a
-    ## normal number. See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
+    ## normal number.
   FloatInexactError* = object of FloatingPointError ## \
     ## Raised for inexact results.
     ##
     ## The operation produced a result that cannot be represented with infinite
     ## precision -- for example: ``2.0 / 3.0, log(1.1)``
     ##
-    ## **NOTE**: Nim currently does not detect these!  See the full
+    ## **NOTE**: Nim currently does not detect these!
-    ## `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
+  DeadThreadError* = object of Defect ## \
-  DeadThreadError* = object of Exception ## \
     ## Raised if it is attempted to send a message to a dead thread.
-    ##
+  NilAccessError* = object of Defect ## \
-    ## See the full `exception hierarchy <manual.html#exception-handling-exception-hierarchy>`_.
-  NilAccessError* = object of SystemError ## \
     ## Raised on dereferences of ``nil`` pointers.
     ##
     ## This is only raised if the ``segfaults.nim`` module was imported!
 
 when defined(nimNewRuntime):
   type
-    MoveError* = object of SystemError ## \
+    MoveError* = object of Defect ## \
       ## Raised on attempts to re-sink an already consumed ``sink`` parameter.
 
 when defined(js) or defined(nimdoc):