-- | This module can be useful while /developing/ an application. It should not
-- be used in production.
module Debug
( -- * Debugging
toString,
log,
todo,
)
where
import Basics ((>>))
import Data.Text (pack, unpack)
import qualified Debug.Trace
import qualified GHC.Stack as Stack
import Text (Text, concat)
import qualified Text.Show.Pretty
import Prelude (Show, error)
-- | Turn any @Show@able kind of value into a string.
--
-- > toString 42 == "42"
-- > toString [1,2] == "[1,2]"
-- > toString ('a', "cat", 13) == "('a', \"cat\", 13)"
-- > toString "he said, \"hi\"" == "\"he said, \\\"hi\\\"\""
--
-- Notice that with strings, this is not the @identity@ function. Ultimately it's
-- down to the value's @Show@ instance, but for strings this typically escapes
-- characters. If you say @toString "he said, \\"hi\\""@ it will show @"he said,
-- \\"hi\\""@ rather than @he said, "hi"@.
toString :: (Show a) => a -> Text
toString =
Text.Show.Pretty.ppShow >> pack
-- | Log a tagged value on the developer console, and then return the value.
--
-- > 1 + log "number" 1 -- equals 2, logs "number: 1"
-- > length (log "start" []) -- equals 0, logs "start: []"
--
-- It is often possible to sprinkle this around to see if values are what you
-- expect. It is kind of old-school to do it this way, but it works!
log :: (Show a) => Text -> a -> a
log message value =
Debug.Trace.trace (unpack (concat [message, ": ", toString value])) value
-- | This is a placeholder for code that you will write later.
--
-- For example, if you are working with a large union type and have partially
-- completed a case expression, it may make sense to do this:
--
-- > type Entity = Ship | Fish | Captain | Seagull
-- >
-- > drawEntity entity =
-- > case entity of
-- > Ship ->
-- > ...
-- >
-- > Fish ->
-- > ...
-- >
-- > _ ->
-- > Debug.todo "handle Captain and Seagull"
--
-- When you call this it throws an exception with the message you give. That
-- exception is catchable... but don't.
todo :: (Stack.HasCallStack) => Text -> a
todo =
Stack.withFrozenCallStack (unpack >> error)