(.require
 [library
  [lux (.except)
   ["$" documentation]
   [data
    [text (.only \n)
     ["%" \\format (.only format)]]]]]
 [\\library
  ["[0]" /]])

(.def .public documentation
  (.List $.Documentation)
  (list ($.module /._
                  "Pure-Lux exception-handling functionality.")

        ($.definition /.assertion)

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

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

        ($.definition /.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)])

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

        ($.definition /.error
          "Constructs an error message from an exception."
          [(error exception message)])

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

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

        ($.definition /.report
          "An error report."
          [(is Text
               (report (list ["Row 0" value/0]
                             ["Row 1" value/1]
                             ,,,
                             ["Row N" value/N])))])

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

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