... 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)
     ["%" \\format (.only format)]]]]]
 [\\library
  ["[0]" /]])

(.def .public documentation
  (.List $.Documentation)
  (list ($.module /._
                  "")

        ($.definition /.monoid)
        ($.definition /.functor)
        ($.definition /.apply)
        ($.definition /.monad)
        ($.definition /.equivalence)
        ($.definition /.hash)
        ($.definition /.with)
        ($.definition /.list)

        ($.definition /.lifted
          "Wraps a monadic value with Maybe machinery."
          ($.example (lifted monad)))

        ($.definition /.else
          (format "Allows you to provide a default value that will be used"
                  \n "if a (Maybe x) value turns out to be .#None."
                  \n "Note: the expression for the default value will not be computed if the base computation succeeds.")
          ($.example (else +20 {.#Some +10}))
          ($.comment "=>")
          ($.example +10)
          
          ($.example (else +20 {.#None}))
          ($.comment "=>")
          ($.example +20))

        ($.definition /.trusted
          (format "Assumes that a Maybe value is a .#Some and yields its value."
                  \n "Raises/throws a runtime error otherwise."
                  \n "WARNING: Use with caution.")
          ($.example (trusted trusted_computation)))

        ($.definition /.when
          "Can be used as a guard in (co)monadic be/do expressions."
          ($.example (do monad
                       [value (do_something 1 2 3)
                        .when (passes_test? value)]
                       (do_something_else 4 5 6))))
        ))