git.iko.soy/elk
on ce614bb help sign in
elk/libraries/Debug.elm
88 lines 3.0 kB history raw
1module Debug where
2{-| This library is for investigating bugs or performance problems. It should
3*not* be used in production code.
5# Console Debugging
6@docs log, crash
8# Time-Travel Debugging
9@docs watch, watchSummary, trace
10-}
12import Graphics.Collage (Form)
13import Native.Debug
14import Native.Error
16{-| Log a tagged value on the developer console, and then return the value.
18 1 + log "number" 1 -- equals 2, logs "number: 1"
19 length (log "start" []) -- equals 0, logs "start: []"
21Notice that `log` is not a pure function! It should *only* be used for
22investigating bugs or performance problems.
23-}
24log : String -> a -> a
25log = Native.Debug.log
27{-| Crash the program with an error message. This is an uncatchable error,
28intended for code that is soon-to-be-implemented. For example, if you are
29working with a large ADT and have partially completed a case expression, it may
30make sense to do this:
32 data Entity = Ship | Fish | Captain | Seagull
34 drawEntity entity =
35 case entity of
36 Ship -> ...
37 Fish -> ...
38 _ -> Debug.crash ("drawEntity not implemented for " ++ show entity ++ " yet!")
40Note that incomplete pattern matches are *very* bad practice! They are one of
41the very few ways to crash an Elm program, and they are completely avoidable.
42Production code should not have incomplete pattern matches!
44**Use this if** you want to do some testing while you are partway through
45writing a function.
47**Do not use this if** you want to do some typical try-catch exception handling.
48Use the `Maybe` or `Either` libraries instead.
49-}
50crash : String -> a
51crash = Native.Error.raise
53{-| Watch a particular value in the debugger. Say we want to know the value of
54a variable called `velocity` because it may not be updated correctly. Adding
55`Debug.watch` allows us to name the value and show it with the debugger.
57 Debug.watch "velocity" velocity == velocity
59Notice that the result of evaluating this expression is exactly the same as
60not having the expression at all. That means it's easy to add to any value.
61-}
62watch : String -> a -> a
63watch = Native.Debug.watch
65{-| Watch a summary of a particular value in the debugger. This function is
66pretty much the same as `watch` but it lets you specify a way to summarize
67the value you are interested in. For example, maybe you only want to see part
68of a record:
70 Debug.watchSummary "velocity" .velocity object
72This is the same as just writing `object`, but it creates a watch that *only*
73looks at the value of `object.velocity`. You can also show summary statistics
74like length of a list:
76 Debug.watchSummary "Number of clicks" length clicks
78Again, this evaluates to `clicks` but we get to see how long that list is in
79the debugger.
80-}
81watchSummary : String -> (a -> b) -> a -> a
82watchSummary = Native.Debug.watchSummary
84{-| Trace all past positions of a `Form` in the debugger. Add this to a `Form`
85and you will see a line tracing its entire history.
86-}
87trace : String -> Form -> Form
88trace = Native.Debug.tracePath