... 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 /._
                  "Composable extensions to the piping macros (|> and <|) that enhance them with various abilities.")

        ($.definition /.new
          "Ignores the piped argument, and begins a new pipe."
          ($.example (' (n.= 1
                             (|> 20
                                 (n.* 3)
                                 (n.+ 4)
                                 (new 0 [++]))))))

        ($.definition /.let
          "Gives a name to the piped-argument, within the given expression."
          ($.example (' (n.= 10
                             (|> 5
                                 (let x (n.+ x x)))))))

        ($.definition /.cond
          (%.message "Branching for pipes."
                     \n "Both the tests and the bodies are piped-code, and must be given inside a tuple.")
          ($.example (' (|> +5
                            (cond [i.even?] [(i.* +2)]
                                  [i.odd?] [(i.* +3)]
                                  [(new -1 [])])))))

        ($.definition /.if
          "If-branching."
          ($.example (' (same? (if (n.even? sample)
                                 "even"
                                 "odd")
                               (|> sample
                                   (if [n.even?]
                                     [(new "even" [])]
                                     [(new "odd" [])]))))))

        ($.definition /.while
          (%.message "While loops for pipes."
                     \n "Both the testing and calculating steps are pipes and must be given inside tuples.")
          ($.example (' (|> +1
                            (while [(i.< +10)]
                                   [++])))))

        ($.definition /.do
          (%.message "Monadic pipes."
                     \n "Each steps in the monadic computation is a pipe and must be given inside a tuple.")
          ($.example (' (|> +5
                            (do identity.monad
                              [(i.* +3)]
                              [(i.+ +4)]
                              [++])))))

        ($.definition /.exec
          (%.message "Non-updating pipes."
                     \n "Will generate piped computations, but their results will not be used in the larger scope.")
          ($.example (' (|> +5
                            (exec [.natural %n log!])
                            (i.* +10)))))

        ($.definition /.tuple
          (%.message "Parallel branching for pipes."
                     \n "Allows to run multiple pipelines for a value and gives you a tuple of the outputs.")
          ($.example (' (|> +5
                            (tuple [(i.* +10)]
                                   [-- (i./ +2)]
                                   [i#injection]))))
          ($.comment "=>")
          ($.example (' [+50 +2 "+5"])))

        ($.definition /.when
          (%.message "Pattern-matching for pipes."
                     \n "The bodies of each branch are NOT pipes; just regular values.")
          ($.example (' (|> +5
                            (when
                              +0 "zero"
                              +1 "one"
                              +2 "two"
                              +3 "three"
                              +4 "four"
                              +5 "five"
                              +6 "six"
                              +7 "seven"
                              +8 "eight"
                              +9 "nine"
                              _ "???")))))
        ))
