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

(.def .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."
          [(n.= 1
                (|> 20
                    (n.* 3)
                    (n.+ 4)
                    (new 0 [++])))])

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

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

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

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

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

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

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

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