... 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 /._
                  "")

        ($.definition /.functor)
        ($.definition /.apply)
        ($.definition /.monad)

        ($.definition (/.Projection state it)
          "A generic projection.")

        ($.definition /.assertion
          "Fails with the given message if the test is #0."
          ($.example (' (assertion message test))))

        ($.definition /.maybe
          "Optionality combinator."
          ($.example (' (maybe projection))))

        ($.definition /.value
          (%.message "Executes the projection on the input."
                     \n "Does not verify that all of the input has been consumed by the projection."
                     \n "Returns both the projection's output, and a value that represents the remaining input.")
          ($.example (' (value projection input))))

        ($.definition /.and
          "Sequencing combinator."
          ($.example (' (and first second))))

        ($.definition /.or
          "Heterogeneous alternative combinator."
          ($.example (' (or left right))))

        ($.definition /.either
          "Homogeneous alternative combinator."
          ($.example (' (either this that))))

        ($.definition /.some
          "0-or-more combinator."
          ($.example (' (some projection))))

        ($.definition /.many
          "1-or-more combinator."
          ($.example (' (many projection))))

        ($.definition /.exactly
          "Parse exactly N times."
          ($.example (' (exactly amount projection))))

        ($.definition /.at_least
          "Parse at least N times."
          ($.example (' (at_least amount projection))))

        ($.definition /.at_most
          "Parse at most N times."
          ($.example (' (at_most amount projection))))

        ($.definition /.between
          ""
          ($.example (' (between minimum additional projection))))

        ($.definition /.separated_by
          "Parses instances of 'projection' that are separated by instances of 'separator'."
          ($.example (' (separated_by separator projection))))

        ($.definition /.not
          "Only succeeds when the underlying projection fails."
          ($.example (' (not projection))))

        ($.definition /.failure
          "Always fail with this 'message'."
          ($.example (' (failure message))))

        ($.definition /.of_try
          "Lift a potentially failed computation into a projection."
          ($.example (' (of_try operation))))

        ($.definition /.else
          "If the given projection fails, returns the default value."
          ($.example (' (else value projection))))

        ($.definition /.remaining
          "Yield the remaining input (without consuming it).")

        ($.definition /.rec
          "Combinator for recursive projections."
          ($.example (' (rec projection))))

        ($.definition /.after
          "Run the projection after another one (whose output is ignored)."
          ($.example (' (after param subject))))

        ($.definition /.before
          "Run the projection before another one (whose output is ignored)."
          ($.example (' (before param subject))))

        ($.definition /.only
          "Only succeed when the projection's output passes a test."
          ($.example (' (only test projection))))

        ($.definition /.parses?
          "Ignore a projection's output and just verify that it succeeds."
          ($.example (' (parses? projection))))

        ($.definition /.parses
          "Ignore a projection's output and just execute it."
          ($.example (' (parses projection))))

        ($.definition /.speculative
          (%.message "Executes a projection, without actually consuming the input."
                     \n "That way, the same input can be consumed again by another projection.")
          ($.example (' (speculative projection))))

        ($.definition /.format
          "Decode the output of a projection using a format."
          ($.example (' (format format projection))))
        ))
