Debug.Variables

Module for debugging Haskell programs. To use, take the functions that you are interested in debugging, e.g.:

module QuickSort(quicksort) where
import Data.List

quicksort :: Ord a => [a] -> [a]
quicksort [] = []
quicksort (x:xs) = quicksort lt ++ [x] ++ quicksort gt
    where (lt, gt) = partition (<= x) xs

Turn on the TemplateHaskell and ViewPatterns extensions, import Debug, indent your code and place it under a call to debug, e.g.:

{-# LANGUAGE TemplateHaskell, ViewPatterns, PartialTypeSignatures #-}
{-# OPTIONS_GHC -Wno-partial-type-signatures #-}
module QuickSort(quicksort) where
import Data.List
import Debug

debug [d|
   quicksort :: Ord a => [a] -> [a]
   quicksort [] = []
   quicksort (x:xs) = quicksort lt ++ [x] ++ quicksort gt
       where (lt, gt) = partition (<= x) xs
   |]

We can now run our debugger with:

$ ghci QuickSort.hs
GHCi, version 8.2.1: http://www.haskell.org/ghc/  :? for help
[1 of 1] Compiling QuickSort        ( QuickSort.hs, interpreted )
Ok, 1 module loaded.
*QuickSort> quicksort "haskell"
"aehklls"
*QuickSort> debugView

The final call to debugView starts a web browser to view the recorded information. Alternatively call debugSave to write the web page to a known location.

For more ways to view the result (e.g. producing JSON) or record traces (without using TemplateHaskell) see Debug.DebugTrace.

Documentation

debug :: Q [Dec] -> Q [Dec]

A TemplateHaskell wrapper to convert a normal function into a traced function. For an example see Debug. Inserts funInfo and var calls.

debugClear :: IO ()

Clear all debug information. Useful when working in ghci to reset any previous debugging work and reduce the amount of output.

debugRun :: IO a -> IO a

Run a computation and open a browser window showing observed function calls.

 main = debugRun $ do
       ...

debugPrint :: IO ()

Print information about the observed function calls to stdout, in a human-readable format.

debugJSON :: IO String

Obtain information about observed functions in JSON format. The JSON format is not considered a stable part of the interface, more presented as a back door to allow exploration of alternative views.

debugView :: IO ()

Open a web browser showing information about observed functions.

debugSave :: FilePath -> IO ()

Save information about observed functions to the specified file, in HTML format.

data DebugTrace

A flat encoding of debugging observations.

Constructors

DebugTrace

Fields

• functions :: [Function]

  Flat list of all the functions traced

• variables :: [Text]

  Flat list of all the variable values observed

• calls :: [CallData]

  Flat list of all the function calls traced

Instances

Eq DebugTrace

Methods

(==) :: DebugTrace -> DebugTrace -> Bool

(/=) :: DebugTrace -> DebugTrace -> Bool

Show DebugTrace

Methods

showsPrec :: Int -> DebugTrace -> ShowS

show :: DebugTrace -> String

showList :: [DebugTrace] -> ShowS

Generic DebugTrace

Associated Types

type Rep DebugTrace :: * -> *

Methods

from :: DebugTrace -> Rep DebugTrace x

to :: Rep DebugTrace x -> DebugTrace

ToJSON DebugTrace

Methods

toJSON :: DebugTrace -> Value

toEncoding :: DebugTrace -> Encoding

toJSONList :: [DebugTrace] -> Value

toEncodingList :: [DebugTrace] -> Encoding

FromJSON DebugTrace

Methods

parseJSON :: Value -> Parser DebugTrace

parseJSONList :: Value -> Parser [DebugTrace]

NFData DebugTrace

Methods

rnf :: DebugTrace -> ()

type Rep DebugTrace

type Rep DebugTrace = D1 * (MetaData "DebugTrace" "Debug.DebugTrace" "debug-0.1.1-2DyeDCIqDFN7qdOxN33d3b" False) (C1 * (MetaCons "DebugTrace" PrefixI True) ((:*:) * (S1 * (MetaSel (Just Symbol "functions") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * [Function])) ((:*:) * (S1 * (MetaSel (Just Symbol "variables") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * [Text])) (S1 * (MetaSel (Just Symbol "calls") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * [CallData])))))

getDebugTrace :: IO DebugTrace

Returns all the information about the observed function accumulated so far in the variables.

Recording

funInfo :: Show a => Function -> (Call -> a) -> a

A version of fun allowing you to pass further information about the Function which is used when showing debug views.

fun :: Show a => String -> (Call -> a) -> a

Called under a lambda with a function name to provide a unique context for a particular call, e.g.:

tracedAdd x y = fun "add" $ \t -> var t "x" x + var t "y" y

This function involves giving identity to function calls, so is unsafe, and will only work under a lambda.

var :: Show a => Call -> String -> a -> a

Used in conjunction with fun to annotate variables. See fun for an example.