Hoed-0.3.0: Lighweight algorithmic debugging.

Copyright(c) 2000 Andy Gill, (c) 2010 University of Kansas, (c) 2013-2015 Maarten Faddegon
LicenseBSD3
Maintainerhoed@maartenfaddegon.nl
Stabilityexperimental
PortabilityPOSIX
Safe HaskellNone
LanguageHaskell2010

Debug.Hoed.Pure

Contents

Description

Hoed is a tracer and debugger for the programming language Haskell. You can trace a program by annotating functions in suspected modules and linking your program against standard profiling libraries.

To locate a defect with Hoed you annotate suspected functions and compile as usual. Then you run your program, information about the annotated functions is collected. Finally you connect to a debugging session using a webbrowser.

Let us consider the following program, a defective implementation of a parity function with a test property.

import Test.QuickCheck

isOdd :: Int -> Bool
isOdd n = isEven (plusOne n)

isEven :: Int -> Bool
isEven n = mod2 n == 0

plusOne :: Int -> Int
plusOne n = n + 1

mod2 :: Int -> Int
mod2 n = div n 2

prop_isOdd :: Int -> Bool
prop_isOdd x = isOdd (2*x+1)

main :: IO ()
main = printO (prop_isOdd 1)

main :: IO ()
main = quickcheck prop_isOdd

Using the property-based test tool QuickCheck we find the counter example `1` for our property.

./MyProgram
*** Failed! Falsifiable (after 1 test): 1

Hoed can help us determine which function is defective. We annotate the functions isOdd, isEven, plusOne and mod2 as follows:

import Debug.Hoed.Pure

isOdd :: Int -> Bool
isOdd = observe "isOdd" isOdd'
isOdd' n = isEven (plusOne n)

isEven :: Int -> Bool
isEven = observe "isEven" isEven'
isEven' n = mod2 n == 0

plusOne :: Int -> Int
plusOne = observe "plusOne" plusOne'
plusOne' n = n + 1

mod2 :: Int -> Int
mod2 = observe "mod2" mod2'
mod2' n = div n 2

prop_isOdd :: Int -> Bool
prop_isOdd x = isOdd (2*x+1)

main :: IO ()
main = printO (prop_isOdd 1)

After running the program a computation tree is constructed and displayed in a web browser.

./MyProgram
False
Listening on http://127.0.0.1:10000/

After running the program a computation tree is constructed and displayed in a web browser. You can freely browse this tree to get a better understanding of your program. If your program misbehaves, you can judge the computation statements in the tree as right or wrong according to your intention. When enough statements are judged the debugger tells you the location of the fault in your code.

I work on this debugger in the context of my Ph.D. research. Read more about the theory behind Hoed at http://maartenfaddegon.nl/#pub.

Hoed.Pure is recommended over Hoed.Stk because to debug your program with Hoed.Pure you can optimize your program and do not need to enable profiling.

I am keen to hear about your experience with Hoed: where did you find it useful and where would you like to see improvement? You can send me an e-mail at hoed@maartenfaddegon.nl, or use the github issue tracker https://github.com/MaartenFaddegon/hoed/issues.

Synopsis

Basic annotations

observe :: Observable a => String -> a -> a Source

Functions which you suspect of misbehaving are annotated with observe and should have a cost centre set. The name of the function, the label of the cost centre and the label given to observe need to be the same.

Consider the following function:

triple x = x + x

This function is annotated as follows:

triple y = (observe "triple" (\x -> {# SCC "triple" #}  x + x)) y

To produce computation statements like:

triple 3 = 6

To observe a value its type needs to be of class Observable. We provided instances for many types already. If you have defined your own type, and want to observe a function that takes a value of this type as argument or returns a value of this type, an Observable instance can be derived as follows:

  data MyType = MyNumber Int | MyName String deriving Generic

  instance Observable MyType

runO :: IO a -> IO () Source

The main entry point; run some IO code, and debug inside it. After the IO action is completed, an algorithmic debugging session is started at http://localhost:10000/ to which you can connect with your webbrowser.

For example:

  main = runO $ do print (triple 3)
                   print (triple 2)

printO :: Show a => a -> IO () Source

Short for runO . print.

Experimental annotations

traceOnly :: IO a -> IO () Source

Only produces a trace. Useful for performance measurements.

doit :: IO a -> IO () Source

observeTempl :: String -> Q Exp Source

observedTypes :: String -> [Q Type] -> Q [Dec] Source

observeCC :: Observable a => String -> a -> a Source

logO :: FilePath -> IO a -> IO () Source

The Observable class

newtype Observer Source

Constructors

O (forall a. Observable a => String -> a -> a) 

class Observable a where Source

Minimal complete definition

Nothing

Methods

observer :: a -> Parent -> a Source

Instances

(<<) :: Observable a => ObserverM (a -> b) -> a -> ObserverM b infixl 9 Source

thunk :: (a -> Parent -> a) -> a -> ObserverM a Source

nothunk :: a -> ObserverM a Source

send :: String -> ObserverM a -> Parent -> a Source

observeBase :: Show a => a -> Parent -> a Source

observeOpaque :: String -> a -> Parent -> a Source

debugO :: IO a -> IO Trace Source

run some code and return the Trace

data CDS Source

Instances

class Generic a

Representable types of kind *. This class is derivable in GHC with the DeriveGeneric flag on.

Minimal complete definition

from, to

Instances