-- 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.
@package Hoed
@version 0.5.1

module Debug.Hoed.Observe
type UID = Int
data Event
Event :: {-# UNPACK #-} !Parent -> !Change -> Event
[eventParent] :: Event -> {-# UNPACK #-} !Parent
[change] :: Event -> !Change
data EventWithId
EventWithId :: !UID -> !Event -> EventWithId
[eventUID] :: EventWithId -> !UID
[event] :: EventWithId -> !Event
data Change
Observe :: !Text -> Change
Cons :: !Word8 -> !Text -> Change
ConsChar :: !Char -> Change
Enter :: Change
Fun :: Change
type ParentPosition = Word8
data Parent
Parent :: !UID -> !ParentPosition -> Parent
[parentUID] :: Parent -> !UID
[parentPosition] :: Parent -> !ParentPosition
root :: Parent
isRootEvent :: Event -> Bool
type Trace = Vector Event
endEventStream :: IO Trace
sendEvent :: Int -> Parent -> Change -> IO ()
lookupOrAddString :: Text -> IO Int
events :: Rope IO MVector Event
strings :: MVar (Pair Int (HashMap Text Int))
stringsLookupTable :: IORef (Vector Text)
lookupString :: Int -> Text
initUniq :: IO ()
getUniq :: IO UID
peepUniq :: IO UID
uniq :: IORef UID

-- | A type class for observable values.
--   
--   <ul>
--   <li>For <a>Generic</a> datatypes it can be derived automatically.</li>
--   <li>For opaque datatypes, use <a>observeOpaque</a> or rely on the
--   catch-all <tt><a>?</a></tt> instance.</li>
--   <li>Custom implementations can exclude one or more fields from the
--   observation:</li>
--   </ul>
--   
--   <pre>
--   instance (Observable a, Observable b) =&gt; Observable (excluded, a,b) where
--          observe (excluded,a,b) = send "(,,)" (return (,,) excluded &lt;&lt; a &lt;&lt; b)
--   </pre>
class Observable a
observer :: Observable a => a -> Parent -> a
observer :: (Observable a, Generic a, GObservable (Rep a)) => a -> Parent -> a
constrain :: Observable a => a -> a -> a
constrain :: (Observable a, Generic a, GConstrain (Rep a)) => a -> a -> a
class GObservable f
gdmobserver :: GObservable f => f a -> Parent -> f a
gdmObserveArgs :: GObservable f => f a -> ObserverM (f a)
gdmShallowShow :: GObservable f => f a -> Text
constrainBase :: (Show a, Eq a) => a -> a -> a
class GConstrain f
gconstrain :: GConstrain f => f a -> f a -> f a
gdmFunObserver :: (Observable a, Observable b) => Parent -> (a -> b) -> (a -> b)
observeBase :: (Show a) => a -> Parent -> a
observeOpaque :: Text -> a -> Parent -> a
newtype ObserverM a
ObserverM :: Int -> Word8 -> (a, Word8) -> ObserverM a
[runMO] :: ObserverM a -> Int -> Word8 -> (a, Word8)
thunk :: (a -> Parent -> a) -> a -> ObserverM a
gthunk :: (GObservable f) => f a -> ObserverM (f a)
(<<) :: (Observable a) => ObserverM (a -> b) -> a -> ObserverM b
infixl 9 <<
gdMapM :: (Monad m) => (a -> m a) -> m (a -> b) -> a -> m b

-- | <a>observe</a> observes data structures in flight.
--   
--   An example of use is <tt> map (+1) . observe "intermeduate" . map (+2)
--   </tt>
--   
--   In this example, we observe the value that flows from the producer
--   <tt>map (+2)</tt> to the consumer <tt>map (+1)</tt>.
--   
--   <a>observe</a> can also observe functions as well a structural values.
gobserve :: (a -> Parent -> a) -> Text -> a -> (a, Int)

-- | 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) => Text -> a -> a
observer_ :: (a -> Parent -> a) -> a -> Parent -> a
gdmobserver_ :: (GObservable f) => f a -> Parent -> f a
unsafeWithUniq :: (Int -> IO a) -> a
generateContext :: (a -> Parent -> a) -> Text -> a -> (a, Int)
send :: Text -> ObserverM a -> Parent -> a
sendEnterPacket :: (a -> Parent -> a) -> a -> Parent -> a
gsendEnterPacket :: (GObservable f) => f a -> Parent -> f a
evaluate :: a -> IO a
sendObserveFnPacket :: ObserverM a -> Parent -> a
ourCatchAllIO :: IO a -> (SomeException -> IO a) -> IO a
handleExc :: Parent -> SomeException -> IO a
instance Debug.Hoed.Observe.Observable a => Debug.Hoed.Observe.GConstrain (GHC.Generics.K1 i a)
instance Debug.Hoed.Observe.Observable a => Debug.Hoed.Observe.GObservable (GHC.Generics.K1 i a)
instance (Debug.Hoed.Observe.Observable a, Debug.Hoed.Observe.Observable b) => Debug.Hoed.Observe.Observable (a -> b)
instance Debug.Hoed.Observe.Observable GHC.Types.Int
instance Debug.Hoed.Observe.Observable GHC.Types.Bool
instance Debug.Hoed.Observe.Observable GHC.Integer.Type.Integer
instance Debug.Hoed.Observe.Observable GHC.Types.Float
instance Debug.Hoed.Observe.Observable GHC.Types.Double
instance Debug.Hoed.Observe.Observable GHC.Types.Char
instance Debug.Hoed.Observe.Observable ()
instance (Debug.Hoed.Observe.Observable a, Debug.Hoed.Observe.Observable b) => Debug.Hoed.Observe.Observable (a, b)
instance (Debug.Hoed.Observe.Observable a, Debug.Hoed.Observe.Observable b, Debug.Hoed.Observe.Observable c) => Debug.Hoed.Observe.Observable (a, b, c)
instance (Debug.Hoed.Observe.Observable a, Debug.Hoed.Observe.Observable b, Debug.Hoed.Observe.Observable c, Debug.Hoed.Observe.Observable d) => Debug.Hoed.Observe.Observable (a, b, c, d)
instance (Debug.Hoed.Observe.Observable a, Debug.Hoed.Observe.Observable b, Debug.Hoed.Observe.Observable c, Debug.Hoed.Observe.Observable d, Debug.Hoed.Observe.Observable e) => Debug.Hoed.Observe.Observable (a, b, c, d, e)
instance Debug.Hoed.Observe.Observable a => Debug.Hoed.Observe.Observable [a]
instance Debug.Hoed.Observe.Observable a => Debug.Hoed.Observe.Observable (GHC.Base.Maybe a)
instance (Debug.Hoed.Observe.Observable a, Debug.Hoed.Observe.Observable b) => Debug.Hoed.Observe.Observable (Data.Either.Either a b)
instance (GHC.Arr.Ix a, Debug.Hoed.Observe.Observable a, Debug.Hoed.Observe.Observable b) => Debug.Hoed.Observe.Observable (GHC.Arr.Array a b)
instance Debug.Hoed.Observe.Observable a => Debug.Hoed.Observe.Observable (GHC.Types.IO a)
instance Debug.Hoed.Observe.Observable GHC.Exception.SomeException
instance Debug.Hoed.Observe.Observable Data.Dynamic.Dynamic
instance (Debug.Hoed.Fields.FieldLimit ('Debug.Hoed.Fields.S ('Debug.Hoed.Fields.S ('Debug.Hoed.Fields.S ('Debug.Hoed.Fields.S ('Debug.Hoed.Fields.S ('Debug.Hoed.Fields.S 'Debug.Hoed.Fields.Z)))))) a, Debug.Hoed.Observe.GObservable a) => Debug.Hoed.Observe.GObservable (GHC.Generics.M1 GHC.Generics.D d a)
instance (Debug.Hoed.Observe.GObservable a, GHC.Generics.Selector s) => Debug.Hoed.Observe.GObservable (GHC.Generics.M1 GHC.Generics.S s a)
instance (Debug.Hoed.Observe.GObservable a, GHC.Generics.Constructor c) => Debug.Hoed.Observe.GObservable (GHC.Generics.M1 GHC.Generics.C c a)
instance Debug.Hoed.Observe.GObservable GHC.Generics.U1
instance (Debug.Hoed.Observe.GObservable a, Debug.Hoed.Observe.GObservable b) => Debug.Hoed.Observe.GObservable (a GHC.Generics.:+: b)
instance (Debug.Hoed.Observe.GObservable a, Debug.Hoed.Observe.GObservable b) => Debug.Hoed.Observe.GObservable (a GHC.Generics.:*: b)
instance GHC.Base.Functor Debug.Hoed.Observe.ObserverM
instance GHC.Base.Applicative Debug.Hoed.Observe.ObserverM
instance GHC.Base.Monad Debug.Hoed.Observe.ObserverM
instance (Debug.Hoed.Observe.GConstrain a, Debug.Hoed.Observe.GConstrain b) => Debug.Hoed.Observe.GConstrain (a GHC.Generics.:+: b)
instance (Debug.Hoed.Observe.GConstrain a, Debug.Hoed.Observe.GConstrain b) => Debug.Hoed.Observe.GConstrain (a GHC.Generics.:*: b)
instance Debug.Hoed.Observe.GConstrain GHC.Generics.U1
instance Debug.Hoed.Observe.GConstrain a => Debug.Hoed.Observe.GConstrain (GHC.Generics.M1 GHC.Generics.D d a)
instance (Debug.Hoed.Observe.GConstrain a, GHC.Generics.Selector s) => Debug.Hoed.Observe.GConstrain (GHC.Generics.M1 GHC.Generics.S s a)
instance (Debug.Hoed.Observe.GConstrain a, GHC.Generics.Constructor c) => Debug.Hoed.Observe.GConstrain (GHC.Generics.M1 GHC.Generics.C c a)
instance Data.Vector.Unboxed.Base.Unbox Debug.Hoed.Observe.Event
instance Data.Vector.Generic.Mutable.Base.MVector Data.Vector.Unboxed.Base.MVector Debug.Hoed.Observe.Event
instance Data.Vector.Generic.Base.Vector Data.Vector.Unboxed.Base.Vector Debug.Hoed.Observe.Event
instance Data.Vector.Unboxed.Base.Unbox Debug.Hoed.Observe.Parent
instance Data.Vector.Generic.Mutable.Base.MVector Data.Vector.Unboxed.Base.MVector Debug.Hoed.Observe.Parent
instance Data.Vector.Generic.Base.Vector Data.Vector.Unboxed.Base.Vector Debug.Hoed.Observe.Parent
instance Data.Vector.Unboxed.Base.Unbox Debug.Hoed.Observe.Change
instance Data.Vector.Generic.Mutable.Base.MVector Data.Vector.Unboxed.Base.MVector Debug.Hoed.Observe.Change
instance Data.Vector.Generic.Base.Vector Data.Vector.Unboxed.Base.Vector Debug.Hoed.Observe.Change
instance GHC.Generics.Generic Debug.Hoed.Observe.Event
instance GHC.Classes.Eq Debug.Hoed.Observe.Event
instance GHC.Generics.Generic Debug.Hoed.Observe.Parent
instance GHC.Classes.Eq Debug.Hoed.Observe.Parent
instance GHC.Generics.Generic Debug.Hoed.Observe.Change
instance GHC.Show.Show Debug.Hoed.Observe.Change
instance GHC.Classes.Eq Debug.Hoed.Observe.Change
instance GHC.Show.Show Debug.Hoed.Observe.EventWithId
instance GHC.Show.Show Debug.Hoed.Observe.Event
instance GHC.Show.Show Debug.Hoed.Observe.Parent


-- | Hoed is a tracer and debugger for the programming language Haskell.
--   
--   This is a drop-in replacement of the Debug.Hoed.Pure or Debug.Hoed.Stk
--   modules and disables tracing (all functions are variations of id).
--   
--   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.NoHoed
observe :: String -> a -> a
runO :: IO a -> IO ()
printO :: (Show a) => a -> IO ()
testO :: Show a => (a -> Bool) -> a -> IO ()
observeBase :: a -> Parent -> a
class Observable a
observer :: Observable a => a -> Parent -> a
observer :: (Observable a, (Generic a)) => a -> Parent -> a
constrain :: Observable a => a -> a -> a
constrain :: (Observable a, (Generic a)) => a -> a -> a
data Parent
Parent :: Parent

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <tt>id</tt>
--   <a>to</a> . <a>from</a> ≡ <tt>id</tt>
--   </pre>
class Generic a where {
    type family Rep a :: * -> *;
}

-- | Convert from the datatype to its representation
from :: Generic a => a -> Rep a x

-- | Convert from the representation to the datatype
to :: Generic a => Rep a x -> a
send :: String -> ObserverM a -> Parent -> a
newtype ObserverM a
ObserverM :: Int -> Int -> (a, Int) -> ObserverM a
[runMO] :: ObserverM a -> Int -> Int -> (a, Int)
(<<) :: (Observable a) => ObserverM (a -> b) -> a -> ObserverM b
instance GHC.Base.Functor Debug.NoHoed.ObserverM
instance GHC.Base.Applicative Debug.NoHoed.ObserverM
instance GHC.Base.Monad Debug.NoHoed.ObserverM
instance Debug.NoHoed.Observable GHC.Types.Int
instance Debug.NoHoed.Observable GHC.Types.Bool
instance Debug.NoHoed.Observable GHC.Integer.Type.Integer
instance Debug.NoHoed.Observable GHC.Types.Float
instance Debug.NoHoed.Observable GHC.Types.Double
instance Debug.NoHoed.Observable GHC.Types.Char
instance Debug.NoHoed.Observable ()
instance Debug.NoHoed.Observable a => Debug.NoHoed.Observable [a]

module Debug.Hoed.Render
data CompStmt
CompStmt :: !Text -> !UID -> !StmtDetails -> CompStmt
[stmtLabel] :: CompStmt -> !Text
[stmtIdentifier] :: CompStmt -> !UID
[stmtDetails] :: CompStmt -> !StmtDetails
data StmtDetails
StmtCon :: Hashed Text -> Hashed Text -> StmtDetails
[stmtCon] :: StmtDetails -> Hashed Text
[stmtPretty] :: StmtDetails -> Hashed Text
StmtLam :: [Hashed Text] -> Hashed Text -> Hashed Text -> StmtDetails
[stmtLamArgs] :: StmtDetails -> [Hashed Text]
[stmtLamRes] :: StmtDetails -> Hashed Text
[stmtPretty] :: StmtDetails -> Hashed Text
stmtRes :: CompStmt -> Text
renderCompStmts :: (?statementWidth :: Int) => CDSSet -> [CompStmt]
data CDS
eventsToCDS :: Trace -> CDSSet
noNewlines :: String -> String

-- | Sort a list by comparing the results of a key function applied to each
--   element. <tt>sortOn f</tt> is equivalent to <tt>sortBy (comparing
--   f)</tt>, but has the performance advantage of only evaluating
--   <tt>f</tt> once for each element in the input list. This is called the
--   decorate-sort-undecorate paradigm, or Schwartzian transform.
--   
--   Elements are arranged from from lowest to highest, keeping duplicates
--   in the order they appeared in the input.
--   
--   <pre>
--   &gt;&gt;&gt; sortOn fst [(2, "world"), (4, "!"), (1, "Hello")]
--   [(1,"Hello"),(2,"world"),(4,"!")]
--   </pre>
sortOn :: Ord b => a -> b -> [a] -> [a]
instance GHC.Base.Monad Debug.Hoed.Render.MemoM
instance GHC.Base.Functor Debug.Hoed.Render.MemoM
instance GHC.Base.Applicative Debug.Hoed.Render.MemoM
instance GHC.Show.Show Debug.Hoed.Render.Output
instance GHC.Classes.Ord Debug.Hoed.Render.Output
instance GHC.Classes.Eq Debug.Hoed.Render.Output
instance GHC.Generics.Generic Debug.Hoed.Render.CDS
instance GHC.Classes.Ord Debug.Hoed.Render.CDS
instance GHC.Classes.Eq Debug.Hoed.Render.CDS
instance GHC.Show.Show Debug.Hoed.Render.CDS
instance GHC.Generics.Generic Debug.Hoed.Render.CompStmt
instance GHC.Generics.Generic Debug.Hoed.Render.StmtDetails
instance GHC.Classes.Eq Debug.Hoed.Render.CDSsansUID
instance GHC.Classes.Ord Debug.Hoed.Render.CDSsansUID
instance Data.Hashable.Class.Hashable Debug.Hoed.Render.CDSsansUID
instance GHC.Exts.IsList Debug.Hoed.Render.ParentList
instance Control.DeepSeq.NFData Debug.Hoed.Render.CDS
instance Control.DeepSeq.NFData Debug.Hoed.Render.CompStmt
instance GHC.Classes.Eq Debug.Hoed.Render.CompStmt
instance GHC.Classes.Ord Debug.Hoed.Render.CompStmt
instance Data.Hashable.Class.Hashable Debug.Hoed.Render.CompStmt
instance GHC.Show.Show Debug.Hoed.Render.CompStmt
instance Control.DeepSeq.NFData Debug.Hoed.Render.StmtDetails

module Debug.Hoed.CompTree

-- | The forest of computation trees. Also see the Libgraph library.
type CompTree = Graph Vertex ()
data Vertex
RootVertex :: Vertex
Vertex :: CompStmt -> Judgement -> Vertex
[vertexStmt] :: Vertex -> CompStmt
[vertexJmt] :: Vertex -> Judgement
mkCompTree :: [CompStmt] -> Dependencies -> CompTree
isRootVertex :: Vertex -> Bool
vertexUID :: Vertex -> UID
vertexRes :: Vertex -> String
replaceVertex :: CompTree -> Vertex -> CompTree
getJudgement :: Vertex -> Judgement
setJudgement :: Vertex -> Judgement -> Vertex
isRight :: Vertex -> Bool
isWrong :: Vertex -> Bool
isUnassessed :: Vertex -> Bool
isAssisted :: Vertex -> Bool
isInconclusive :: Vertex -> Bool
isPassing :: Vertex -> Bool
leafs :: CompTree -> [Vertex]
data ConstantValue
ConstantValue :: !UID -> !Location -> !UID -> !UID -> ConstantValue
[valStmt] :: ConstantValue -> !UID
[valLoc] :: ConstantValue -> !Location
[valMin] :: ConstantValue -> !UID
[valMax] :: ConstantValue -> !UID
CVRoot :: ConstantValue

-- | Approximates the complexity of a computation tree by summing the
--   length of the unjudged computation statements (i.e not Right or Wrong)
--   in the tree.
unjudgedCharacterCount :: CompTree -> Int
data TraceInfo
TraceInfo :: !SpanZipper -> !Dependencies -> TraceInfo
[computations] :: TraceInfo -> !SpanZipper
[dependencies] :: TraceInfo -> !Dependencies
traceInfo :: Verbosity -> Trace -> IO TraceInfo
data Graph vertex arc
Graph :: vertex -> [vertex] -> [Arc vertex arc] -> Graph vertex arc
[root] :: Graph vertex arc -> vertex
[vertices] :: Graph vertex arc -> [vertex]
[arcs] :: Graph vertex arc -> [Arc vertex arc]
instance GHC.Show.Show Debug.Hoed.CompTree.TraceInfo
instance GHC.Classes.Eq Debug.Hoed.CompTree.TopLvlFun
instance GHC.Classes.Eq Debug.Hoed.CompTree.ConstantValue
instance GHC.Generics.Generic Debug.Hoed.CompTree.Vertex
instance GHC.Classes.Ord Debug.Hoed.CompTree.Vertex
instance GHC.Show.Show Debug.Hoed.CompTree.Vertex
instance GHC.Show.Show Debug.Hoed.CompTree.ConstantValue
instance GHC.Classes.Eq Debug.Hoed.CompTree.Vertex
instance Data.Hashable.Class.Hashable Debug.Hoed.CompTree.Vertex
instance Control.DeepSeq.NFData Debug.Hoed.CompTree.Vertex
instance Control.DeepSeq.NFData Data.Graph.Libgraph.AlgoDebug.AssistedMessage
instance Control.DeepSeq.NFData Data.Graph.Libgraph.AlgoDebug.Judgement
instance (Control.DeepSeq.NFData a, Control.DeepSeq.NFData b) => Control.DeepSeq.NFData (Data.Graph.Libgraph.Core.Arc a b)


-- | 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 console.
--   
--   With Hoed you can list and search observed functions applied to
--   argument values and the result values. Hoed also provides algorithmic
--   debugging. An algorithmic debugger finds defects in programs by
--   systematic search. The programmer directs the search by answering a
--   series of yes/no questions about the correctness of specific function
--   applications and their results. Hoed also allows the use of
--   (QuickCheck-style) properties to answer automatically some of the
--   questions arising during algorithmic debugging, and to replace others
--   by simpler questions.
--   
--   <h1>Example usage</h1>
--   
--   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
--   
--   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 the
--   algorithmic debugger is launched in the console.
--   
--   <pre>
--   False
--   
--   === program terminated ===
--   Please wait while the computation tree is constructed...
--   
--   === Statistics ===
--   
--   28 events
--   4 computation statements
--   4 nodes + 1 virtual root node in the computation tree
--   4 edges in computation tree
--   computation tree has a branch factor of 1.3333333333333333 (i.e the average number of children of non-leaf nodes)
--   
--   === Debug Session ===
--   
--   hdb&gt; adb
--   ======================================================================= [0-0/4]
--   isOdd 3  = False
--   ? 
--   right  Judge computation statements right
--           according to the intended behaviour/specification of the function.
--   wrong  Judge computation statements wrong
--           according to the intended behaviour/specification of the function.
--   ======================================================================= [0-0/4]
--   isOdd 3  = False
--   ? wrong
--   ======================================================================= [1-0/4]
--   isEven 4  = False
--   ? wrong
--   ======================================================================= [2-0/4]
--   mod2 4  = 2
--   ? wrong
--   ======================================================================= [3-0/4]
--   Fault located! In:
--   mod2 4  = 2
--   hdb&gt;
--   </pre>
--   
--   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

-- | 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) => Text -> 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 ()

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

-- | Configuration options for running Hoed
data HoedOptions
HoedOptions :: Verbosity -> Int -> HoedOptions
[verbose] :: HoedOptions -> Verbosity
[prettyWidth] :: HoedOptions -> Int

-- | The default is to run silent and pretty print with a width of 110
--   characters
defaultHoedOptions :: HoedOptions

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

-- | Repeat and trace a failing testcase
testOwp :: Show a => [Propositions] -> (a -> Bool) -> 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
data Proposition
Proposition :: PropositionType -> Module -> String -> [Signature] -> Maybe Int -> TestGen -> Proposition
[propositionType] :: Proposition -> PropositionType
[propModule] :: Proposition -> Module
[propName] :: Proposition -> String
[signature] :: Proposition -> [Signature]
[maxSize] :: Proposition -> Maybe Int
[testgen] :: Proposition -> TestGen
mkProposition :: Module -> String -> Proposition
ofType :: Proposition -> PropositionType -> Proposition
withSignature :: Proposition -> [Signature] -> Proposition
sizeHint :: Proposition -> Int -> Proposition
withTestGen :: Proposition -> TestGen -> Proposition
data TestGen
TestGenQuickCheck :: TestGen
TestGenLegacyQuickCheck :: TestGen
data PropositionType
IOProposition :: PropositionType
BoolProposition :: PropositionType
LegacyQuickCheckProposition :: PropositionType
QuickCheckProposition :: PropositionType
data Module
Module :: String -> String -> Module
[moduleName] :: Module -> String
[searchPath] :: Module -> String
data Signature
Argument :: Int -> Signature
SubjectFunction :: Signature
Random :: Signature
class ParEq a
parEq :: ParEq a => a -> a -> Maybe Bool
parEq :: (ParEq a, Generic a, GParEq (Rep a)) => a -> a -> Maybe Bool
(===) :: ParEq a => a -> a -> Bool

-- | Hoed internal function that stores a serialized version of the tree on
--   disk (assisted debugging spawns new instances of Hoed).
runOstore :: String -> IO a -> IO ()
conAp :: Observable b => (a -> b) -> b -> a -> b
data HoedAnalysis
HoedAnalysis :: Trace -> CompTree -> HoedAnalysis
[hoedTrace] :: HoedAnalysis -> Trace
[hoedCompTree] :: HoedAnalysis -> CompTree

-- | Entry point giving you access to the internals of Hoed. Also see:
--   runO.
runO' :: HoedOptions -> IO a -> IO HoedAnalysis

-- | Use propositions to judge a computation statement. First tries
--   restricted and bottom for unevaluated expressions, then unrestricted,
--   and finally with randomly generated values for unevaluated
--   expressions.
judge :: Trace -> Propositions -> Vertex -> (CompTree -> Int) -> CompTree -> IO Judge

-- | Approximates the complexity of a computation tree by summing the
--   length of the unjudged computation statements (i.e not Right or Wrong)
--   in the tree.
unjudgedCharacterCount :: CompTree -> Int

-- | The forest of computation trees. Also see the Libgraph library.
type CompTree = Graph Vertex ()
data Vertex
RootVertex :: Vertex
Vertex :: CompStmt -> Judgement -> Vertex
[vertexStmt] :: Vertex -> CompStmt
[vertexJmt] :: Vertex -> Judgement
data CompStmt
CompStmt :: !Text -> !UID -> !StmtDetails -> CompStmt
[stmtLabel] :: CompStmt -> !Text
[stmtIdentifier] :: CompStmt -> !UID
[stmtDetails] :: CompStmt -> !StmtDetails
data Judge

-- | Returns a Judgement (see Libgraph library).
Judge :: Judgement -> Judge

-- | Found counter example with simpler computation tree.
AlternativeTree :: CompTree -> Trace -> Judge
data Verbosity
Verbose :: Verbosity
Silent :: Verbosity

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

-- | As logO, but with property-based judging.
logOwp :: UnevalHandler -> FilePath -> [Propositions] -> IO a -> IO ()

-- | Only produces a trace. Useful for performance measurements.
traceOnly :: IO a -> IO ()
data UnevalHandler
RestrictedBottom :: UnevalHandler
Bottom :: UnevalHandler
Forall :: UnevalHandler
FromList :: [String] -> UnevalHandler

-- | A type class for observable values.
--   
--   <ul>
--   <li>For <a>Generic</a> datatypes it can be derived automatically.</li>
--   <li>For opaque datatypes, use <a>observeOpaque</a> or rely on the
--   catch-all <tt><a>?</a></tt> instance.</li>
--   <li>Custom implementations can exclude one or more fields from the
--   observation:</li>
--   </ul>
--   
--   <pre>
--   instance (Observable a, Observable b) =&gt; Observable (excluded, a,b) where
--          observe (excluded,a,b) = send "(,,)" (return (,,) excluded &lt;&lt; a &lt;&lt; b)
--   </pre>
class Observable a
observer :: Observable a => a -> Parent -> a
observer :: (Observable a, Generic a, GObservable (Rep a)) => a -> Parent -> a
constrain :: Observable a => a -> a -> a
constrain :: (Observable a, Generic a, GConstrain (Rep a)) => a -> a -> a
(<<) :: (Observable a) => ObserverM (a -> b) -> a -> ObserverM b
infixl 9 <<
thunk :: (a -> Parent -> a) -> a -> ObserverM a
send :: Text -> ObserverM a -> Parent -> a
observeOpaque :: Text -> a -> Parent -> a
observeBase :: (Show a) => a -> Parent -> a
constrainBase :: (Show a, Eq a) => a -> a -> a

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

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <tt>id</tt>
--   <a>to</a> . <a>from</a> ≡ <tt>id</tt>
--   </pre>
class Generic a
instance Debug.Hoed.Observe.Observable a

module Debug.Hoed.TH

-- | A handy TH wrapper for debugging functions, offering more information
--   than <a>obs</a>
--   
--   <pre>
--   debug [d|
--     quicksort [] = []
--     quicksort (x:xs) = quicksort lt ++ [x] ++ quicksort gt
--         where (lt, gt) = partition (&lt;= x) xs
--           |]
--   
--   </pre>
--   
--   expands to:
--   
--   <pre>
--   quicksort = observe "quicksort" quicksort'
--   quicksort' [] = []
--   quicksort' (x:xs) = quicksort lt ++ [x] ++ quicksort gt
--         where (observe "lt" -&gt; lt, observe "lt" -&gt; gt) = partition (&lt;= x) xs
--   
--   </pre>
--   
--   The additional information may lead to unnecessary questions in
--   algorithmic debugging, <a>obs</a> is the recommended wrapper for that
--   purpose.
debug :: Q [Dec] -> Q [Dec]

-- | A handy TH wrapper for observing functions.
--   
--   <pre>
--   obs [d|
--     trimPat :: Exp S -&gt; Pat S -&gt; Pat S
--     trimPat vs = filterPat ((<a>member</a> freeVars vs) . void)
--       |]
--   
--   </pre>
--   
--   is equivalent to:
--   
--   <pre>
--   trimPat = observe "trimPat" trimPat'
--   trimPat' vs = filterPat ....
--   
--   </pre>
--   
--   <a>obs</a> accepts multiple declarations, and all the functions inside
--   will be wrapped as above, while the rest of declarations will stay
--   unchanged. As such it can be used to observe entire modules.
obs :: Q [Dec] -> Q [Dec]
