module Debugging.CustomTypeErrors.OverviewAPI where

# Prim Special Submodules

Every Purescript project imports the Prim module by default:

This module defines `kind Type` and the types
for `Int`, `Array`, and `Function`.

In addition, the Prim module has sub module called "TypeError"
that is not imported by default. Within it, Prim defines a few
things for writing your own custom type warnings/errors.

Similar to what we did in the Syntax folder, we'll show the
value-level definitions of these type-level types, instances, and functions

The following is commented out to prevent a compiler warning:
  "import is redundant"

-- new imports
import Prim.TypeError (
  -- type-level type
    kind Doc

  -- type-level instances
  , Text
  , Quote
  , Above
  , Beside

  -- type-level functions
  , class Warn
  , class Fail


data Doc_
  = Text_ String      -- wraps a Symbol
  | Quote_ String     -- the Type's name as a Symbol
  | QuoteLabel_ String -- Similar to Text but handles things differently
                       -- Used particularly for 'labels', the 'keys'
                       -- in rows/records (see functions file)
  | Beside_ Doc_ Doc_ -- Similar to "left <> right" ("leftright") in that
                      -- it places documents side-by-side. However, it's
                      -- different in that these documents are aligned at
                      -- the top.
  | Above_ Doc_ Doc_  -- same as "top" <> "\n" <> "bottom" ("top\nbottom")

type Explanation = String

warn :: Explanation
warn = """
              - Constrain a type with Warn in a value/function declaration
              - Constrain a type in a type class instance with Warn
              If value/function is used, outputs a warning during compile-time
         Compilation succeeds?:
         Use Cases:
              - "Soft" Deprecation - Indicate to users of library that this
                  function/value will be removed/changed in future
              - Warning indicating developer/debug code should be removed
                  before production code is released
         Does the REPL display it?:
              No (as of this writing)

fail :: Explanation
fail = """
              - Constrain a type with Fail in a value/function declaration
              - Constrain a type in a type class instance with Fail
              If instance is used, outputs an error during compile-time
         Compilation succeeds?:
         Use Cases:
              - "Hard" Deprecation - Remove support for a value/function and
                  force users of library to migrate to new approach or
                  use a different value/function that does the same thing.
              - Provide better error messages for specific type class instances
                  that cannot exist.
         Does the REPL display it?: