(.using
  [library
   [lux {"-" if loop}
    ["$" documentation {"+" documentation:}]
    [data
     [text {"+" \n}
      ["%" format {"+" format}]]]
    [macro
     ["[0]" template]]]]
  [\\library
   ["[0]" /]])

(documentation: (/.Exception it)
  "An exception provides a way to decorate error messages.")

(documentation: /.match?
  "Is this exception the cause of the error message?"
  [(match? exception error)])

(documentation: /.when
  (format "If a particular exception is detected on a possibly-erroneous value, handle it."
          \n "If no exception was detected, or a different one from the one being checked, then pass along the original value.")
  [(when exception then try)])

(documentation: /.otherwise
  "If no handler could be found to catch the exception, then run a function as a last-resort measure."
  [(otherwise else try)])

(documentation: /.error
  "Constructs an error message from an exception."
  [(error exception message)])

(documentation: /.except
  "Decorate an error message with an Exception and lift it into the error-handling context."
  [(except exception message)])

(documentation: /.exception:
  (format "Define a new exception type."
          \n "It mostly just serves as a way to tag error messages for later catching.")
  ["Simple case:"
   (exception: .public some_exception)]
  ["Complex case:"
   (exception: .public [arbitrary type variables] (some_exception [optional Text
                                                                   arguments Int])
     optional_body)])

(documentation: /.report
  "An error report."
  [(: Text
      (report ["Row 0" value/0]
              ["Row 1" value/1]
              ,,,
              ["Row N" value/N]))])

(documentation: /.listing
  (format "A numbered report of the entries on a list."
          \n "NOTE: 0-based numbering.")
  [(listing format entries)])

(documentation: /.with
  "If a computation fails, prepends the exception to the error."
  [(with exception message computation)])

(.def: .public documentation
  (.List $.Module)
  ($.module /._
            "Pure-Lux exception-handling functionality."
            [..Exception
             ..match?
             ..when
             ..otherwise
             ..error
             ..except
             ..exception:
             ..report
             ..listing
             ..with
             ($.default /.assertion)]
            []))
