-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Lightweight algorithmic debugging.
--   
--   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.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.
@package Hoed
@version 0.3.3


-- | Hoed is a tracer and debugger for the programming language Haskell.
--   
--   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.
--   
--   <pre>
--   import Test.QuickCheck
--   
--   isOdd :: Int -&gt; Bool
--   isOdd n = isEven (plusOne n)
--   
--   isEven :: Int -&gt; Bool
--   isEven n = mod2 n == 0
--   
--   plusOne :: Int -&gt; Int
--   plusOne n = n + 1
--   
--   mod2 :: Int -&gt; Int
--   mod2 n = div n 2
--   
--   prop_isOdd :: Int -&gt; Bool
--   prop_isOdd x = isOdd (2*x+1)
--   
--   main :: IO ()
--   main = printO (prop_isOdd 1)
--   
--   main :: IO ()
--   main = quickcheck prop_isOdd
--   </pre>
--   
--   Using the property-based test tool QuickCheck we find the counter
--   example `1` for our property.
--   
--   <pre>
--   ./MyProgram
--   *** Failed! Falsifiable (after 1 test): 1
--   </pre>
--   
--   Hoed can help us determine which function is defective. We annotate
--   the functions <tt>isOdd</tt>, <tt>isEven</tt>, <tt>plusOne</tt> and
--   <tt>mod2</tt> as follows:
--   
--   <pre>
--   import Debug.Hoed.Pure
--   
--   isOdd :: Int -&gt; Bool
--   isOdd = observe "isOdd" isOdd'
--   isOdd' n = isEven (plusOne n)
--   
--   isEven :: Int -&gt; Bool
--   isEven = observe "isEven" isEven'
--   isEven' n = mod2 n == 0
--   
--   plusOne :: Int -&gt; Int
--   plusOne = observe "plusOne" plusOne'
--   plusOne' n = n + 1
--   
--   mod2 :: Int -&gt; Int
--   mod2 = observe "mod2" mod2'
--   mod2' n = div n 2
--   
--   prop_isOdd :: Int -&gt; Bool
--   prop_isOdd x = isOdd (2*x+1)
--   
--   main :: IO ()
--   main = printO (prop_isOdd 1)
--   </pre>
--   
--   After running the program a computation tree is constructed and
--   displayed in a web browser.
--   
--   <pre>
--   ./MyProgram
--   False
--   Listening on http://127.0.0.1:10000/
--   </pre>
--   
--   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 <tt>right</tt> or
--   <tt>wrong</tt> according to your intention. When enough statements are
--   judged the debugger tells you the location of the fault in your code.
--   
--   
--   Read more about Hoed on its project homepage
--   <a>https://wiki.haskell.org/Hoed</a>.
--   
--   Papers on the theory behind Hoed can be obtained via
--   <a>http://maartenfaddegon.nl/#pub</a>.
--   
--   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
--   <a>https://github.com/MaartenFaddegon/hoed/issues</a>.
module Debug.Hoed.Pure

-- | 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:
--   
--   <pre>
--   triple x = x + x
--   </pre>
--   
--   This function is annotated as follows:
--   
--   <pre>
--   triple y = (observe "triple" (\x -&gt; {# SCC "triple" #}  x + x)) y
--   </pre>
--   
--   To produce computation statements like:
--   
--   <pre>
--   triple 3 = 6
--   </pre>
--   
--   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:
--   
--   <pre>
--   data MyType = MyNumber Int | MyName String deriving Generic
--   
--   instance Observable MyType
--   </pre>
observe :: (Observable a) => String -> a -> a

-- | 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
--   <tt><a>http://localhost:10000/</a></tt> to which you can connect with
--   your webbrowser.
--   
--   For example:
--   
--   <pre>
--   main = runO $ do print (triple 3)
--                    print (triple 2)
--   </pre>
runO :: IO a -> IO ()

-- | Repeat and trace a failing testcase
testO :: Show a => (a -> Bool) -> a -> IO ()

-- | Short for <tt>runO . print</tt>.
printO :: (Show a) => a -> IO ()

-- | Trace and write computation tree to file. Useful for regression
--   testing.
logO :: FilePath -> IO a -> IO ()

-- | Use property based judging.
runOwp :: [Propositions] -> IO a -> IO ()

-- | Repeat and trace a failing testcase
testOwp :: Show a => [Propositions] -> (a -> Bool) -> a -> IO ()

-- | As logO, but with property-based judging.
logOwp :: PropVarGen String -> FilePath -> [Propositions] -> IO a -> IO ()
data Propositions
Propositions :: [Proposition] -> PropType -> String -> [Module] -> Propositions
[propositions] :: Propositions -> [Proposition]
[propType] :: Propositions -> PropType
[funName] :: Propositions -> String
[extraModules] :: Propositions -> [Module]
data PropType
Specify :: PropType
PropertiesOf :: PropType
type Proposition = (PropositionType, Module, String, [Int])
data PropositionType
BoolProposition :: PropositionType
QuickCheckProposition :: PropositionType
data Module
Module :: String -> String -> Module
[moduleName] :: Module -> String
[searchPath] :: Module -> String
propVarError :: PropVarGen String
propVarFresh :: PropVarGen String

-- | Only produces a trace. Useful for performance measurements.
traceOnly :: IO a -> IO ()
observeTempl :: String -> Q Exp
observedTypes :: String -> [Q Type] -> Q [Dec]
observeCC :: (Observable a) => String -> a -> a
class ParEq a where x === y = gParEq (from x) (from y)
(===) :: ParEq a => a -> a -> Maybe Bool
newtype Observer
O :: (forall a. (Observable a) => String -> a -> a) -> Observer
class Observable a where observer x c = to (gdmobserver (from x) c)
observer :: Observable a => a -> Parent -> a
(<<) :: (Observable a) => ObserverM (a -> b) -> a -> ObserverM b
thunk :: (a -> Parent -> a) -> a -> ObserverM a
nothunk :: a -> ObserverM a
send :: String -> ObserverM a -> Parent -> a
observeBase :: (Show a) => a -> Parent -> a
observeOpaque :: String -> a -> Parent -> a

-- | run some code and return the Trace
debugO :: IO a -> IO Trace
data CDS

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


-- | Hoed.Stk 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.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.
--   
--   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 <tt>right</tt> or
--   <tt>wrong</tt> 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 <a>http://maartenfaddegon.nl/#pub</a>.
--   
--   To use Hoed on your own program, annotate your program as described
--   below. For best results profiling is enabled and optimization
--   disabled. If you use cabal to build your project, this is be done
--   with:
--   
--   <pre>
--   cabal configure --disable-optimization --enable-profiling
--   </pre>
--   
--   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
--   <a>https://github.com/MaartenFaddegon/hoed/issues</a>.
module Debug.Hoed.Stk

-- | 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:
--   
--   <pre>
--   triple x = x + x
--   </pre>
--   
--   This function is annotated as follows:
--   
--   <pre>
--   triple y = (observe "triple" (\x -&gt; {# SCC "triple" #}  x + x)) y
--   </pre>
--   
--   To produce computation statements like:
--   
--   <pre>
--   triple 3 = 6
--   </pre>
--   
--   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:
--   
--   <pre>
--   data MyType = MyNumber Int | MyName String deriving Generic
--   
--   instance Observable MyType
--   </pre>
observe :: (Observable a) => String -> a -> a

-- | 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
--   <tt><a>http://localhost:10000/</a></tt> to which you can connect with
--   your webbrowser.
--   
--   For example:
--   
--   <pre>
--   main = runO $ do print (triple 3)
--                    print (triple 2)
--   </pre>
runO :: IO a -> IO ()

-- | Short for <tt>runO . print</tt>.
printO :: (Show a) => a -> IO ()
observeTempl :: String -> Q Exp
observedTypes :: String -> [Q Type] -> Q [Dec]
observeCC :: (Observable a) => String -> a -> a
observe' :: (Observable a) => String -> Identifier -> a -> (a, Int)
data Identifier
UnknownId :: Identifier
DependsJustOn :: Int -> Identifier
InSequenceAfter :: Int -> Identifier
logO :: FilePath -> IO a -> IO ()
newtype Observer
O :: (forall a. (Observable a) => String -> a -> a) -> Observer
class Observable a where observer x c = to (gdmobserver (from x) c)
observer :: Observable a => a -> Parent -> a
(<<) :: (Observable a) => ObserverM (a -> b) -> a -> ObserverM b
thunk :: (a -> Parent -> a) -> a -> ObserverM a
nothunk :: a -> ObserverM a
send :: String -> ObserverM a -> Parent -> a
observeBase :: (Show a) => a -> Parent -> a
observeOpaque :: String -> a -> Parent -> a

-- | run some code and return the CDS structure (for when you want to write
--   your own debugger).
debugO :: IO a -> IO [Event]
data CDS

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