... 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/.

(.using
 [library
  [lux
   [program (.only program)]
   ["$" documentation]
   ["[0]" debug]
   [control
    ["[0]" io]]
   [data
    ["[0]" text (.only \n)
     ["%" \\injection]]
    [collection
     ["[0]" list (.use "[1]:[0]" monoid)]
     ["[0]" set]]]
   [meta
    [macro
     ["[0]" template]]]]]
 [\\library
  ["[0]" / (.except)]]
 ["[0]" /
  ["[1][0]" abstract]
  ["[1][0]" control]
  ["[1][0]" data]
  ["[1][0]" debug]
  ["[1][0]" documentation]
  ["[1][0]" ffi]
  ["[1][0]" math]
  ["[1][0]" meta]
  ["[1][0]" program]
  ["[1][0]" test]
  ["[1][0]" world]])

(the all_1/4
  (List $.Documentation)
  (list ($.definition /.prelude
          (text "The name of the prelude module."
                \n "Value: " (%.text /.prelude)))

        ($.definition /.Any
          (text "The type of things whose type is irrelevant."
                \n "It can be used to write functions or data-structures that can take, or return, anything."))

        ($.definition /.Nothing
          (text "The type of things whose type is undefined."
                \n "Useful for expressions that cause errors or other 'extraordinary' conditions."))

        ($.definition (/.List item)
          "A potentially empty list of values.")

        ($.definition /.Bit
          "Your standard, run-of-the-mill boolean values (as 0b or 1b bits).")

        ($.definition (/.I64 kind)
          "64-bit integers without any semantics.")

        ($.definition /.Natural
          (text "Natural numbers (unsigned integers)."
                \n "They start at zero (0) and extend in the positive direction."))

        ($.definition /.Integer
          "Your standard, run-of-the-mill integer numbers.")

        ($.definition /.Revolution
          (text "Fractional numbers that live in the interval [0,1)."
                \n "Useful for probability, and other domains that work within that interval."))

        ($.definition /.Decimal
          "Your standard, run-of-the-mill floating-point (decimal) numbers.")

        ($.definition /.Text
          "Your standard, run-of-the-mill string values.")

        ($.definition /.Name
          (text "A name for a Lux definition."
                \n "It includes the module of provenance."))

        ($.definition (/.Maybe value)
          "A potentially missing value.")

        ($.definition /.Type
          "This type represents the data-structures that are used to specify types themselves.")

        ($.definition /.Provenance
          "Provenances are for specifying the provenance of Code nodes in Lux files during compilation.")

        ($.definition (/.Annotated meta_data datum)
          "The type of things that can be annotated with meta-data of arbitrary types.")

        ($.definition /.Code
          "The type of Code nodes for Lux syntax.")

        ($.definition /.private
          "The export policy for private/local definitions.")

        ($.definition /.local
          "The export policy for private/local definitions.")

        ($.definition /.public
          "The export policy for public/global definitions.")

        ($.definition /.global
          "The export policy for public/global definitions.")

        ($.definition /.Definition
          "Represents all the data associated with a definition: its type, its annotations, and its value.")

        ($.definition /.Global
          "Represents all the data associated with a global constant.")

        ($.definition (/.Either left right)
          "A choice between two values of different types.")

        ($.definition /.Module
          "All the information contained within a Lux module.")

        ($.definition /.Mode
          "A sign that shows the conditions under which the compiler is running.")

        ($.definition /.Info
          "Information about the current version and type of compiler that is running.")

        ($.definition /.Lux
          (text "Represents the state of the Lux compiler during a run."
                \n "It is provided to macros during their invocation, so they can access compiler data."
                \n "Caveat emptor: Avoid fiddling with it, unless you know what you're doing."))

        ($.definition (/.Meta it)
          (text "Computations that can have access to the state of the compiler."
                \n "These computations may fail, or modify the state of the compiler."))

        ($.definition /.Macro
          "Functions that run at compile-time and allow you to transform and extend the language in powerful ways.")

        ($.definition /.comment
          (text "Throws away any code given to it."
                \n "Great for commenting-out code, while retaining syntax high-lighting and formatting in your text editor.")
          ($.example (' (comment
                          (the (this will not)
                            (Be Defined)
                            (because it will be (commented out)))))))

        ($.definition /.for_any
          "Universal quantification."

          ($.example (' (for_any (_ a)
                          (-> a a))))

          ($.comment "A name can be provided, to specify a recursive type.")
          ($.example (' (for_any (List a)
                          (Or Any
                              [a (List a)])))))

        ($.definition /.for_some
          "Existential quantification."

          ($.example (' (for_some (_ a)
                          [(Format Text a) a])))
          
          ($.comment "A name can be provided, to specify a recursive type.")
          ($.example (' (for_some (Self a)
                          [(Format Text a)
                           a
                           (List (Self a))]))))
        ))

(the all_2/4
  (List $.Documentation)
  (list ($.definition /.->
          "Function types."
          ($.comment "This is the type of a function that takes 2 Integers and returns an Integer.")
          ($.example (' (-> Integer Integer Integer))))

        ($.definition /.list
          "List literals."
          ($.example (' (is (List Natural)
                            (list 0 1 2 3)))))

        ($.definition /.Union
          "Union types."
          ($.example (' (Union Bit Natural Text)))
          ($.example (' (= Nothing
                           (Union)))))

        ($.definition /.Tuple
          "Tuple types."
          ($.example (' (Tuple Bit Natural Text)))
          ($.example (' (= Any
                           (Tuple)))))

        ($.definition /.Or
          "An alias for the Union type constructor."
          ($.example (' (= (Union Bit Natural Text)
                           (Or Bit Natural Text))))
          ($.example (' (= (Union)
                           (Or)))))

        ($.definition /.And
          "An alias for the Tuple type constructor."
          ($.example (' (= (Tuple Bit Natural Text)
                           (And Bit Natural Text))))
          ($.example (' (= (Tuple)
                           (And)))))

        ($.definition /.left
          "Left-association for the application of binary functions over variadic arguments."

          ($.example (' (left text:composite "Hello, " name ". How are you?")))
          ($.comment "=>")
          ($.example (' (text:composite (text:composite "Hello, " name) ". How are you?"))))

        ($.definition /.all
          "Right-association for the application of binary functions over variadic arguments."
          ($.example (' (all text:composite "Hello, " name ". How are you?")))
          ($.comment "=>")
          ($.example (' (text:composite "Hello, " (text:composite name ". How are you?")))))

        ($.definition /.if
          "Picks which expression to evaluate based on a bit test value."
          ($.example (' (if 1b
                            "Oh, yeah!"
                            "Aw hell naw!")))
          ($.comment "=>")
          ($.example (' "Oh, yeah!"))

          ($.example (' (if 0b
                            "Oh, yeah!"
                            "Aw hell naw!")))
          ($.comment "=>")
          ($.example (' "Aw hell naw!")))

        ($.definition /.Nominal
          "Macro to treat define new nominal types."
          ($.example (' (Nominal "java.lang.Object")))
          ($.example (' (Nominal "java.util.List" [(Nominal "java.lang.Long")]))))

        ($.definition /.`
          (text "Hygienic quasi-quotation as a macro."
                \n "Unquote (,) and unquote-splice (,*) must also be used as forms."
                \n "All unprefixed macros will receive their parent module's prefix if imported; otherwise will receive the prefix of the module on which the quasi-quote is being used.")
          ($.example (' (` (the (, name)
                             (function ((,' _) (,* args))
                               (, body)))))))

        ($.definition /.`'
          (text "Unhygienic quasi-quotation as a macro."
                \n "Unquote (,) and unquote-splice (,*) must also be used as forms.")
          ($.example (' (`' (the (, name)
                              (function (_ (,* args))
                                (, body)))))))

        ($.definition /.'
          "Quotation as a macro."
          ($.example (' (' YOLO))))

        ($.definition /.|>
          "Piping macro."
          ($.example (' (|> elems
                            (list:each integer:as)
                            (interposed " ")
                            (mix text:composite ""))))
          ($.comment "=>")
          ($.example (' (mix text:composite ""
                             (interposed " "
                                         (list:each integer:as
                                                    elems))))))

        ($.definition /.<|
          "Reverse piping macro."
          ($.example (' (<| (mix text:composite "")
                            (interposed " ")
                            (list:each integer:as)
                            elems)))
          ($.comment "=>")
          ($.example (' (mix text:composite ""
                             (interposed " "
                                         (list:each integer:as
                                                    elems))))))

        ($.definition /.template
          ""
          ($.comment "By specifying a pattern (with holes), and the input data to fill those holes, repeats the pattern as many times as necessary.")
          ($.example (' (template.with [<name> <diff>]
                          [(the .public <name>
                             (-> Integer Integer)
                             (+ <diff>))]
                          
                          [[++ +1]
                           [-- -1]]
                          ))))
        ))

(`` (the all_3/4
      (List $.Documentation)
      (list ($.definition /.not
              "Bit negation."
              ($.example (' (not 1b)))
              ($.comment "=>")
              ($.example (' 0b))
              
              ($.example (' (not 0b)))
              ($.comment "=>")
              ($.example (' 1b)))

            ($.definition /.is
              "The type-annotation macro."
              ($.example (' (is (List Integer)
                                (list +1 +2 +3)))))

            ($.definition /.as
              "The type-coercion macro."
              ($.example (' (as Dinosaur
                                (list +1 +2 +3)))))

            ($.definition /.Rec
              "Parameter-less recursive types."
              ($.comment "A name has to be given to the whole type, to use it within its body.")
              ($.example (' (Rec Integer_List
                              (Or Any
                                  [Integer Integer_List]))))

              ($.comment "Can also be used with type and labelled-type definitions.")
              ($.example (' (every Type
                              (Rec @
                                (Variant
                                 {:Nominal Text (List @)}
                                 {:Sum @ @}
                                 {:Product @ @}
                                 {:Function @ @}
                                 {:Parameter Natural}
                                 {:Variable Natural}
                                 {:Opaque Natural}
                                 {:Universal (List @) @}
                                 {:Existential (List @) @}
                                 {:Reification @ @}
                                 {:Named Name @}))))))

            ($.definition /.exec
              "Sequential execution of expressions (great for side-effects)."
              ($.example (' (exec
                              (log! "1b")
                              (log! "#2")
                              (log! "#3")
                              "YOLO"))))

            ($.definition /.when
              (text "The pattern-matching macro."
                    \n "Allows the usage of macros within the patterns to provide custom syntax.")
              ($.example (' (when (is (List Integer)
                                      (list +1 +2 +3))
                              {:Top a {:Top b {:Top c {:Empty}}}}
                              {:Some (all x a b c)}

                              _
                              {:None}))))

            ($.definition /.pattern
              (text "Macro-expanding patterns."
                    \n "It's a special macro meant to be used with 'when'.")
              ($.example (' (when (is (List Integer)
                                      (list +1 +2 +3))
                              (list a b c)
                              {:Some (all * a b c)}

                              _
                              {:None}))))

            ... ($.definition /.^or
            ...   (text "Or-patterns."
            ...           \n "It's a special macro meant to be used with 'when'.")
            ...   ($.example (' (every Weekday
            ...                   (Variant
            ...                    {:Monday}
            ...                    {:Tuesday}
            ...                    {:Wednesday}
            ...                    {:Thursday}
            ...                    {:Friday}
            ...                    {:Saturday}
            ...                    {:Sunday}))))
            ...   ($.example (' (the (weekend? day)
            ...                   (-> Weekday Bit)
            ...                   (when day
            ...                     (^or {:Saturday} {:Sunday})
            ...                     true

            ...                     _
            ...                     false)))))

            ($.definition /.let
              (text "Creates local bindings."
                    \n "Can (optionally) use pattern-matching macros when binding.")
              ($.example (' (let [x (foo bar)
                                  y (baz quux)]
                              (op x y)))))

            ($.definition /.function
              "Syntax for creating functions."
              ($.example (' (is (for_any (_ a b)
                                  (-> a b a))
                                (function (_ x y)
                                  x))))

              ($.comment "Allows for giving the function itself a name, for the sake of recursion.")
              ($.example (' (is (-> Natural Natural)
                                (function (factorial n)
                                  (when n
                                    0 1
                                    _ (x n  (factorial (-- n)))))))))

            ($.definition /.def
              "Defines global constants/functions."
              ($.example (' (the branching_exponent
                              Integer
                              +5)))

              ($.comment "The type is optional.")
              ($.example (' (the branching_exponent
                              +5)))

              ($.example (' (the (pair_list pair)
                              (-> [Code Code] (List Code))
                              (let [[left right] pair]
                                (list left right)))))

              ($.comment "Can pattern-match on the inputs to functions.")
              ($.example (' (the (pair_list [left right])
                              (-> [Code Code] (List Code))
                              (list left right)))))

            ($.definition /.macro
              "Macro-definition macro."
              ($.example (' (the .public name
                              (macro (_ tokens)
                                (when tokens
                                  (^template.with [<tag>]
                                    [(list {<tag> _ [module name]})
                                     (pure (list (` [(, (as_text module))
                                                     (, (as_text name))])))])
                                  ([:Name])
                                  
                                  _
                                  (failure "")))))))

            ($.definition /.and
              "Short-circuiting 'and'."
              ($.example (' (and 1b 0b)))
              ($.comment "=>")
              ($.example (' 0b))
              
              ($.example (' (and 1b 1b)))
              ($.comment "=>")
              ($.example (' 1b)))

            ($.definition /.or
              "Short-circuiting 'or'."
              ($.example (' (or 1b 0b)))
              ($.comment "=>")
              ($.example (' 1b))

              ($.example (' (or 0b 0b)))
              ($.comment "=>")
              ($.example (' 0b)))

            ($.definition /.halt!
              "Causes an error, with the given error message."
              ($.example (' (halt! "OH NO!"))))

            ($.definition /.implementation
              "Express a value that implements an interface."
              ($.example (' (is (Order Integer)
                                (implementation
                                 (the equality
                                   equality)
                                 (the (< reference subject)
                                   (< reference subject))
                                 )))))

            ($.definition /.Variant
              (text "Syntax for defining labelled/tagged sum/union types."
                    \n "WARNING: Only use it within the type macro.")
              ($.example (' (every Referrals
                              (Variant
                               {:All}
                               {:Only (List Text)}
                               {:Exclude (List Text)}
                               {:Ignore}
                               {:Nothing})))))

            ($.definition /.Record
              (text "Syntax for defining labelled/slotted product/tuple types."
                    \n "WARNING: Only use it within the type macro.")
              ($.example (' (every Refer
                              (Record
                               [:refer_defs Referrals
                                :refer_open (List Openings)])))))

            ($.definition /.every
              "The definition macro for types."
              ($.example (' (every (List a)
                              {:Empty}
                              {:Top a (List a)}))))

            ($.definition /.Interface
              "Interface definition."
              ($.example (' (every .public (Order a)
                              (Interface
                               (is (Equality a)
                                   equality)
                               (is (-> a a Bit)
                                   <))))))

            (,, (template.with [<name>]
                  [($.definition <name>
                     "Safe type-casting for I64 values.")]

                  [[/.i64]
                   [/.natural]
                   [/.integer]
                   [/.revolution]]
                  ))

            ($.definition /.open
              (text "Same as the 'open' macro, but meant to be used as a pattern-matching macro for generating local bindings."
                    \n "Takes an 'alias' text for the generated local bindings.")
              ($.example (' (the .public (range enum from to)
                              (for_any (_ a) (-> (Enum a) a a (List a)))
                              (let [(open "[0]") enum]
                                (loop (of [end to
                                           output {.:Empty}])
                                  (if (< end from)
                                      (of (pred end) {.:Top end output})

                                      (< from end)
                                      (of (succ end) {.:Top end output})

                                      ... (= end from)
                                      {.:Top end output})))))))

            ($.definition /.its
              "Accesses the value of a record at a given tag."
              ($.example (' (its :field my_record)))

              ($.comment "Can also work with multiple levels of nesting.")
              ($.example (' (its [:foo :bar :baz] my_record)))

              ($.comment "And, if only the slot/path is given, generates an accessor function.")
              ($.example (' (let [getter (its [:foo :bar :baz])]
                              (getter my_record)))))

            ($.definition /.use
              "Opens a implementation and generates a definition for each of its members (including nested members)."
              ($.example (' (use "i:[0]" order)))
              ($.comment "=>")
              ($.example (' (the i:= (by order =))))
              ($.example (' (the i:< (by order <)))))

            ($.definition /.|>>
              "Similar to the piping macro, but rather than taking an initial object to work on, creates a function for taking it."
              ($.example (' (|>> (list:each integer:as)
                                 (interposed " ")
                                 (mix text:composite ""))))
              ($.comment "=>")
              ($.example (' (function (_ <it>)
                              (mix text:composite ""
                                   (interposed " "
                                               (list:each integer:as <it>)))))))

            ($.definition /.<<|
              "Similar to the reverse piping macro, but rather than taking an initial object to work on, creates a function for taking it."
              ($.example (' (<<| (mix text:composite "")
                                 (interposed " ")
                                 (list:each integer:as))))
              ($.comment "=>")
              ($.example (' (function (_ <it>)
                              (mix text:composite ""
                                   (interposed " "
                                               (list:each integer:as
                                                          <it>)))))))

            ($.definition /.using
              "Module-definition macro."
              ($.example (' (.using
                             [lux (.except)
                              [control
                               ["M" monad (.except)]]
                              [data
                               maybe
                               ["[0]" name (.use "[1]:[0]" format)]]
                              [macro
                               code]]
                             [//
                              [type (.use "[0]" equality)]]))))

            ($.definition /.by
              "Allows accessing the value of a implementation's member."
              ($.example (' (by format as)))

              ($.comment "Also allows using that value as a function.")
              ($.example (' (by format as +123))))

            ($.definition /.has
              "Sets the value of a record at a given tag."
              ($.example (' (has :name "Lux" lang)))

              ($.comment "Can also work with multiple levels of nesting.")
              ($.example (' (has [:foo :bar :baz] value my_record)))

              ($.comment "And, if only the slot/path and (optionally) the value are given, generates a mutator function.")
              ($.example (' (let [setter (has [:foo :bar :baz] value)]
                              (setter my_record))))
              ($.example (' (let [setter (has [:foo :bar :baz])]
                              (setter value my_record)))))
            )))

(`` (the all_4/4
      (List $.Documentation)
      (list ($.definition /.revised
              "Modifies the value of a record at a given tag, based on some function."
              ($.example (' (revised :age ++ person)))

              ($.comment "Can also work with multiple levels of nesting.")
              ($.example (' (revised [:foo :bar :baz] func my_record)))

              ($.comment "And, if only the slot/path and (optionally) the value are given, generates a mutator function.")
              ($.example (' (let [updater (revised [:foo :bar :baz] func)]
                              (updater my_record))))
              ($.example (' (let [updater (revised [:foo :bar :baz])]
                              (updater func my_record)))))

            ... ($.definition /.^template
            ...   "It's similar to template, but meant to be used during pattern-matching."
            ...   ($.example (' (the (reduced env type)
            ...                   (-> (List Type) Type Type)
            ...                   (when type
            ...                     {.:Nominal name params}
            ...                     {.:Nominal name (list:each (reduced env) params)}

            ...                     (^template.with [<tag>]
            ...                                     [{<tag> left right}
            ...                                      {<tag> (reduced env left) (reduced env right)}])
            ...                     ([.:Sum] [.:Product])

            ...                     (^template.with [<tag>]
            ...                                     [{<tag> left right}
            ...                                      {<tag> (reduced env left) (reduced env right)}])
            ...                     ([.:Function] [.:Reification])

            ...                     (^template.with [<tag>]
            ...                                     [{<tag> old_env def}
            ...                                      (when old_env
            ...                                        {.:Empty}
            ...                                        {<tag> env def}

            ...                                        _
            ...                                        type)])
            ...                     ([.:Universal] [.:Existential])

            ...                     {.:Parameter idx}
            ...                     (else type (list.item idx env))

            ...                     _
            ...                     type
            ...                     )))))

            (,, (template.with [<name> <doc>]
                  [($.definition <name>
                     <doc>)]

                  [[/.++ "Increment function."]
                   [/.-- "Decrement function."]]
                  ))

            ($.definition /.loop
              (text "Allows arbitrary looping, using the 'of' form to re-start the loop."
                    \n "Can be used in monadic code to create monadic loops.")
              ($.example (' (loop (of [count +0
                                       x init])
                              (if (< +10 count)
                                  (of (++ count) (f x))
                                  x))))

              ($.comment "Loops can also be given custom names.")
              ($.example (' (loop (my_loop [count +0
                                            x init])
                              (if (< +10 count)
                                  (my_loop (++ count) (f x))
                                  x)))))

            ($.definition /.with_expansions
              (text "Controlled macro-expansion."
                    \n "Bind an arbitraty number of Code nodes resulting from macro-expansion to local bindings."
                    \n "Wherever a binding appears, the bound Code nodes will be spliced in there.")
              ($.example (' (the test
                              Test
                              (with_expansions
                                [<tests> (template.with [<function> <parameter> <expected>]
                                           [(cover [<function>]
                                                   (compare <text>
                                                            (by format as <function> <parameter>)))]

                                           [[bit 1b "1b"]
                                            [integer +123 "+123"]
                                            [decimal +123.0 "+123.0"]
                                            [text "123" "'123'"]
                                            [name ["yolo" "lol"] "yolo.lol"]
                                            [form (list (bit 1b)) "(1b)"]
                                            [tuple (list (bit 1b)) "[1b]"]]
                                           )]
                                (all and
                                     <tests>
                                     ))))))

            ($.definition /.static
              (text "Resolves the names of definitions to their values at compile-time, assuming their values are either:"
                    \n "* Bit"
                    \n "* Natural"
                    \n "* Integer"
                    \n "* Revolution"
                    \n "* Decimal"
                    \n "* Text")
              ($.example (' (the my_natural 123)))
              ($.example (' (the my_text "456")))
              ($.example (' (and (when [my_natural my_text]
                                   (static [..my_natural ..my_text])
                                   true

                                   _
                                   false)
                                 (when [my_natural my_text]
                                   [(static ..my_natural) (static ..my_text)]
                                   true

                                   _
                                   false)))))

            ... ($.definition /.^multi
            ...   (text "Multi-level pattern matching."
            ...           \n "Useful in situations where the result of a branch depends on further refinements on the values being matched.")
            ...   ($.example (' (when (split (size static) uri)
            ...                   (^multi {:Some [chunk uri']}
            ...                           [(text.= static chunk) .true])
            ...                   (match_uri endpoint? parts' uri')

            ...                   _
            ...                   {:Left (text "Static part " (%t static) " does not match URI: " uri)})))

            ...   ($.comment "Short-cuts can be taken when using bit tests.")
            ...   ($.comment "The example above can be rewritten as...")
            ...   ($.example (' (when (split (size static) uri)
            ...                   (^multi {:Some [chunk uri']}
            ...                           (text.= static chunk))
            ...                   (match_uri endpoint? parts' uri')

            ...                   _
            ...                   {:Left (text "Static part " (%t static) " does not match URI: " uri)}))))

            ($.definition /.name
              "Gives back a 2 tuple with the module and name parts, both as Text."
              ($.example (' (name ..:doc)))
              ($.comment "=>")
              ($.example (' ["documentation/lux" "#doc"])))

            ($.definition /.parameter
              (text "WARNING: Please stay away from this macro; it's very likely to be removed in a future version of Lux."
                    "Allows you to refer to the type-variables in a polymorphic function's type, by their index.")
              ($.comment "In the example below, 0 corresponds to the 'a' variable.")
              ($.example (' (the .public (of_list list)
                              (for_any (_ a) (-> (List a) (Sequence a)))
                              (list:mix add
                                        (is (Sequence (parameter 0))
                                            empty)
                                        list)))))

            ($.definition /.identical?
              "Tests whether the 2 values are identical (not just 'equal')."
              ($.comment "This one should succeed:")
              ($.example (' (let [value +5]
                              (identical? value
                                          value))))
              
              ($.comment "This one should fail:")
              ($.example (' (identical? +5
                                        (+ +2 +3)))))

            ... ($.definition /.^let
            ...   "Allows you to simultaneously bind and de-structure a value."
            ...   ($.example (' (the (hash (^let set [member_hash _]))
            ...                   (list:mix (function (_ elem acc)
            ...                               (+ acc
            ...                                  (by member_hash hash elem)))
            ...                             0
            ...                             (set.list set))))))

            ... ($.definition /.^|>
            ...   "Pipes the value being pattern-matched against prior to binding it to a variable."
            ...   ($.example (' (when input
            ...                   (^|> value [++ (% 10) (major 1)])
            ...                   (foo value)))))

            ($.definition /.as_expected
              "Coerces the given expression to the type of whatever is expected."
              ($.example (' (is Dinosaur
                                (as_expected (is (List Natural)
                                                 (list 1 2 3)))))))

            ($.definition /.undefined
              (text "Meant to be used as a stand-in for functions with undefined implementations."
                    \n "Undefined expressions will type-check against everything, so they make good dummy implementations."
                    \n "However, if an undefined expression is ever evaluated, it will raise a runtime error.")
              ($.example (' (the (square x)
                              (-> Integer Integer)
                              (undefined)))))

            ($.definition /.type_of
              "Generates the type corresponding to a given expression."
              ($.example (' (let [my_num +123]
                              (type_of my_num))))
              ($.comment "==")
              ($.example (' Integer))
              
              ($.example (' (type_of +123)))
              ($.comment "==")
              ($.example (' Integer)))

            ($.definition /.template
              (text "Define macros in the style of template.with."
                    \n "For simple macros that do not need any fancy features.")
              ($.example (' (the square
                              (template.macro (square it)
                                (x it it))))))

            ($.definition /.these
              (text "Given a (potentially empty) list of codes, just returns them immediately, without any work done."
                    \n "This may seen useless, but it has its utility when dealing with controlled-macro-expansion macros.")
              ($.example (' (expansion.let [<operands> (these 1
                                                              2
                                                              3
                                                              4)]
                              (all + <operands>)))))

            ($.definition /.character
              "If given a 1-character text literal, yields the char-code of the sole character."
              ($.example (' (is Natural
                                (character "A"))))
              ($.comment "=>")
              ($.example (' 65)))

            ($.definition /.for
              (text "Selects the appropriate code for a given target-platform when compiling Lux to it."
                    \n "Look-up the available targets in library/lux/target.")
              ($.example (' (the js
                              "JavaScript")))
              ($.example (' (for "JVM" (do jvm stuff)
                                 js (do js stuff)
                                 (do default stuff)))))

            ($.definition /.``
              (text "Delimits a controlled (spliced) macro-expansion."
                    \n "Uses a (,,) special form to specify where to expand.")
              ($.example (' (`` (some expression
                                      (,, (some macro which may yield 0 or more results)))))))

            ... ($.definition /.^code
            ...   "Generates pattern-matching code for Code values in a way that looks like code-templating."
            ...   ($.example (' (is (Maybe Natural)
            ...                     (when (` (0b 123 +456.789))
            ...                       (^code (0b (, {.:Natural _ number}) +456.789))
            ...                       {.:Some number}

            ...                       _
            ...                       {.:None})))))

            ($.definition /.false
              "The boolean FALSE value.")

            ($.definition /.true
              "The boolean TRUE value.")

            ($.definition /.try
              ""
              ($.example (' (is Foo
                                (when (is (Either Text Bar)
                                          (try (is Bar
                                                   (risky computation which may panic))))
                                  {.:Right success}
                                  (is Foo
                                      (do something after success))

                                  {.:Left error}
                                  (is Foo
                                      (recover from error)))))))
            
            ($.definition (/.Code' w))
            ($.definition /.Alias)
            ($.definition (/.Bindings key value))
            ($.definition /.Ref)
            ($.definition /.Scope)
            ($.definition /.Source)
            ($.definition /.Module_State)
            ($.definition /.Type_Context)
            ($.definition /.Macro')
            ($.definition /.Label)
            ($.definition /.macro)
            )))

(the .public documentation
  (List $.Documentation)
  (all list:composite
       (list ($.module /._
                       "The prelude for Lux's standard library."))
       all_1/4
       all_2/4
       all_3/4
       all_4/4

       /abstract.documentation
       /control.documentation
       /data.documentation
       /debug.documentation
       /documentation.documentation
       /ffi.documentation
       /math.documentation
       /meta.documentation
       /program.documentation
       /test.documentation
       /world.documentation
       ))

(the _
  (program inputs
    (io.io (debug.log! ($.markdown ..documentation)))))
