diff --git a/Debug/Hoed/Pure.hs b/Debug/Hoed/Pure.hs --- a/Debug/Hoed/Pure.hs +++ b/Debug/Hoed/Pure.hs @@ -1,18 +1,18 @@ {-| Module : Debug.Hoed.Pure -Description : Lighweight algorithmic debugging based on observing intermediate values and the cost centre stack. +Description : Lighweight algorithmic debugging based on observing intermediate values. Copyright : (c) 2000 Andy Gill, (c) 2010 University of Kansas, (c) 2013-2015 Maarten Faddegon License : BSD3 Maintainer : hoed@maartenfaddegon.nl Stability : experimental Portability : POSIX -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. +Hoed is a tracer and debugger for the programming language Haskell. -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. +Hoed.Pure is recommended over Hoed.Stk: in contrast to Hoed.Stk you can optimize your program and do not need to enable profiling when using Hoed.Pure. +To locate a defect with Hoed.Pure 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 @@ -82,12 +82,11 @@ 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 . +Read more about Hoed on its project homepage . -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. +Papers on the theory behind Hoed can be obtained via . 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 . -} diff --git a/Debug/Hoed/Pure/Observe.lhs b/Debug/Hoed/Pure/Observe.lhs --- a/Debug/Hoed/Pure/Observe.lhs +++ b/Debug/Hoed/Pure/Observe.lhs @@ -22,7 +22,7 @@ Copyright (c) Andy Gill, 1992-2000 Copyright (c) The University of Kansas 2010 -Copyright (c) Maarten Faddegon, 2013-2014 +Copyright (c) Maarten Faddegon, 2013-2015 All rights reserved. HOOD is distributed as free software under the license in the file "License", which available from the HOOD @@ -174,8 +174,8 @@ gdmobserver m@(M1 x) cxt = M1 (gdmobserver x cxt) -- Uncomment next two lines to record selector names - -- | selName m == "" = M1 (gdmobserver x cxt) - -- | otherwise = M1 (send (selName m ++ " =") (gdmObserveChildren x) cxt) + -- selName m == "" = M1 (gdmobserver x cxt) + -- otherwise = M1 (send (selName m ++ " =") (gdmObserveChildren x) cxt) gdmObserveChildren = gthunk gdmShallowShow = error "gdmShallowShow not defined on <>" diff --git a/Hoed.cabal b/Hoed.cabal --- a/Hoed.cabal +++ b/Hoed.cabal @@ -1,12 +1,13 @@ name: Hoed -version: 0.3.2 +version: 0.3.3 synopsis: Lightweight algorithmic debugging. 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. + Hoed is a tracer and debugger for the programming language Haskell. . 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. . - Hoed comes in two flavours: Hoed.Pure and Hoed.Stk. Hoed.Pure is recommended over Hoed.Stk: to debug your program with Hoed.Pure you can optimize your program and do not need to enable profiling. Hoed.Stk is Hoed as presented on PLDI 2015 and possibly has benefits over Hoed.Pure for debugging concurrent/parallel programs. + Hoed comes in two flavours: Hoed.Pure and Hoed.Stk. Hoed.Stk uses the cost-centre stacks of the GHC profiling environment to construct the information needed for debugging. Hoed.Pure is recommended over Hoed.Stk: to debug your program with Hoed.Pure you can optimize your program and do not need to enable profiling. + . homepage: http://maartenfaddegon.nl license: BSD3 license-file: LICENSE @@ -130,6 +131,39 @@ -- main-is: Main.hs -- hs-source-dirs: examples/FPretty__with_properties -- default-language: Haskell2010 + +Executable hoed-examples-Rot13 + if flag(buildExamples) + build-depends: base >= 4 && < 5 + , Hoed + , threepenny-gui + , filepath + else + buildable: False + main-is: Rot13.hs + hs-source-dirs: examples + default-language: Haskell2010 + +Executable hoed-examples-Salary + if flag(buildExamples) + build-depends: base >= 4 && < 5 + , Hoed + , threepenny-gui + , filepath + else + buildable: False + main-is: Salary.hs + hs-source-dirs: examples + default-language: Haskell2010 + +Executable hoed-examples-Nub-defective-sort__with_properties + if flag(buildExamples) + build-depends: base >= 4 && < 5, Hoed, threepenny-gui, filepath, QuickCheck + else + buildable: False + main-is: Main.hs + hs-source-dirs: examples/Nubsort + default-language: Haskell2010 Executable hoed-examples-Insertion_Sort_elements_disappear if flag(buildExamples) diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,85 +1,7 @@ # Hoed - A Lightweight Haskell Tracer and Debugger [![Build Status](https://travis-ci.org/MaartenFaddegon/Hoed.svg?branch=master)](https://travis-ci.org/MaartenFaddegon/Hoed) -Hoed is a tracer and debugger for the programming language Haskell. - -## Using Hoed - -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. - - 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/ - -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. - -![Screenshot of Hoed][1] - -## Installation - -Hoed is available from Hackage and can be installed with Cabal. - - cabal install Hoed - -## Other Tracers - -Many of the ideas for Hoed come from the Hat project. Hoed is the Dutch word for a hat. Compared to Hoed, Hat can give more detailed traces. However, Hat requires all modules to be transformed and is therefore not practical for many real-world Haskell programs. +Hoed is a tracer and debugger for the programming language Haskell. 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. See the -The idea to observe values with local annotations comes from the HOOD project. Unlike Hoed, HOOD does not give relations between observed values. HOOD also requires the programmer to write a class-instance for the type of the value they want to observe. With Hoed these instates can be derived automatically. + [**Project homepage**](http://wiki.haskell.org/Hoed) - [1]: http://www.cs.kent.ac.uk/people/rpg/mf357/hoedv2.0.0.png +for more information on what it does and how you can use it to find bugs in your code. diff --git a/changelog b/changelog --- a/changelog +++ b/changelog @@ -1,3 +1,7 @@ +0.3.3 Maarten Faddegon 6 Dec 2015 + + * Documentation and additional examples. + 0.3.2 Maarten Faddegon 6 Dec 2015 * Add experimental combinators for property-assisted algorithmic debugging. diff --git a/examples/Nubsort/Main.hs b/examples/Nubsort/Main.hs new file mode 100644 --- /dev/null +++ b/examples/Nubsort/Main.hs @@ -0,0 +1,19 @@ +import Debug.Hoed.Pure +import Nubsort + +main = testOwp ps prop_nub_idempotent [2,1,1] + where + ps = [ Propositions [ (BoolProposition,nubsortModule,"prop_nub_idempotent",[0]) + , (BoolProposition,nubsortModule,"prop_nub_unique",[0]) + , (BoolProposition,nubsortModule,"prop_nub_complete",[0]) + ] PropertiesOf "nub" [] + , Propositions [ (QuickCheckProposition,nubsortModule,"prop_nubord_idempotent",[0]) + , (QuickCheckProposition,nubsortModule,"prop_nubord_unique",[0]) + , (QuickCheckProposition,nubsortModule,"prop_nubord_complete",[0]) + ] PropertiesOf "nubord" [modQuickCheck] + , Propositions [ (QuickCheckProposition,nubsortModule,"prop_insert_ordered",[0]) + , (QuickCheckProposition,nubsortModule,"prop_insert_complete",[0]) + ] PropertiesOf "insert" [modQuickCheck] + ] + nubsortModule = Module "Nubsort" "../examples/Nubsort/" + modQuickCheck = Module "Test.QuickCheck" "" diff --git a/examples/Rot13.hs b/examples/Rot13.hs new file mode 100644 --- /dev/null +++ b/examples/Rot13.hs @@ -0,0 +1,21 @@ +-- A defective ROT13 implemenation. +import Data.Maybe +import Data.Char +import Debug.Hoed.Pure + +main = printO (prop_rot13length "Abc") + +----------------------------------------------------------------------------- + +rot13 = observe "rot13" rot13' +normalize = observe "normalize" normalize' +rot13char = observe "rot13char" rot13char' + +rot13' = mapMaybe (\c -> rot13char (normalize c)) +normalize' c = lookup c (zip ['a'..'z'] ['A' .. 'Z']) +rot13char' Nothing = Nothing +rot13char' (Just c) = lookup c table + where table = zip ['A'..'Z'] (['N'..'Z'] ++ ['A'..'M']) + +prop_rot13length s = length t == length (rot13 t) + where t = filter isAlpha s diff --git a/examples/Salary.hs b/examples/Salary.hs new file mode 100644 --- /dev/null +++ b/examples/Salary.hs @@ -0,0 +1,39 @@ +{-# LANGUAGE DeriveGeneric #-} +import Debug.Hoed.Pure + +avgSalary :: [Employee] -> Float +f :: [Employee] -> Float +avg :: Float -> Float -> Employee -> Float + +------------------------------------------------------------ +-- defective computation of avarage salary (always 0.0) + +data Employee = Employee {getName :: String, getSalary :: Float} deriving Generic + +avgSalary es = foldl (avg 1.0) 0.0 es +-- avgSalary es = foldl (avg (f es)) 0.0 es +f es = toFloat (1 `div` (length es)) +avg' x acc (Employee _ s) = acc + (x * s) + +instance Observable Employee +-- avgSalary = observe "avgSalary" avgSalary' +-- f = observe "f" f' +avg = observe "avg" avg' + +------------------------------------------------------------ +-- properties + +newtype Positive a = Positive {getPositive :: a} deriving Show + +prop_avgSalaryPositive :: [Positive Float] -> Bool +prop_avgSalaryPositive ss = avgSalary (map mkEmployee ss) > 0.0 + where mkEmployee (Positive s) = Employee "X" s + +------------------------------------------------------------ + +main = testO prop_avgSalaryPositive ss + where ss = [Positive 3000.0, Positive 1800.0] + employees = [Employee "Aafje" 3000, Employee "Ben" 2000] + +toFloat :: Int -> Float +toFloat = fromInteger . toInteger