... This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
... If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.

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

(the .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 /.is?
          "Is this exception the cause of the error message?"
          ($.example (' (is? exception error))))

        ($.definition /.when
          (%.message "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.")
          ($.example (' (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."
          ($.example (' (otherwise else try))))

        ($.definition /.error
          "Constructs an error message from an exception."
          ($.example (' (error exception message))))

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

        ($.definition /.def
          (%.message "Define a new exception type."
                     \n "It mostly just serves as a way to tag error messages for later catching.")
          ($.comment "Simple case:")
          ($.example (' (/.the .public some_exception)))

          ($.comment "Complex case:")
          ($.example (' (/.the .public [arbitrary type variables] (some_exception [optional arguments])
                          (/.Exception [Text Integer])
                          optional_body))))

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

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

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