... 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 (.except)
   ["$" documentation]
   [data
    ["[0]" text (.only \n)
     ["%" \\injection]]]]]
 [\\library
  ["[0]" /]])

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

        ($.definition /.any
          (text "Automatic implementation selection (for type-class style polymorphism)."
                \n "This feature layers type-class style polymorphism on top of Lux's signatures and implementations."
                \n "When calling a polymorphic function, or using a polymorphic constant,"
                \n "this macro will check the types of the arguments, and the expected type for the whole expression"
                \n "and it will search in the local scope, the module's scope and the imports' scope"
                \n "in order to find suitable implementations to satisfy those requirements."
                \n "If a single alternative is found, that one will be used automatically."
                \n "If no alternative is found, or if more than one alternative is found (ambiguity)"
                \n "a compile-time error will be raised, to alert the user."
                \n \n "Caveat emptor: You need to make sure to import the module of any implementation you want to use."
                \n "Otherwise, this macro will not find it.")
          ($.example (' ($.comment "Natural equality")))
          ($.example (' (by number.equality = x y)))
          ($.example (' (any = x y)))

          ($.comment "Can optionally add the prefix of the module where the signature was defined.")
          ($.example (' (any equality.= x y)))

          ($.comment "(List Natural) equality")
          ($.example (' (any =
                             (list.domain 10)
                             (list.domain 10))))

          ($.comment "(Functor List) each")
          ($.example (' (any each ++ (list.domain 10)))))

        ($.definition /.with
          "Establish lexical bindings for implementations that will be prioritized over non-lexically-bound implementations."
          ($.example (' (with [n.addition]
                          (n.= (by n.addition composite left right)
                               (any composite left right))))))

        ($.definition /.implicitly
          "Establish local definitions for implementations that will be prioritized over foreign definitions."
          ($.example (' (implicitly n.multiplication)))
          ($.example (' (n.= (by n.multiplication composite left right)
                             (any composite left right)))))
        ))
