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


-- | Simple trace-based debugger
--   
--   An easy to use debugger for viewing function calls and intermediate
--   variables. To use, annotate the function under test, run the code, and
--   view the generated web page. Full usage instructions are at
--   <a>Debug</a>.
@package debug
@version 0.1.1


-- | Module containing functions required by test code. Not part of the
--   public interface.
module Debug.Util
hasRankNTypes :: Type -> Bool
prettyPrint :: (Data a, Ppr a) => a -> String

-- | Trsansform infix operator into a valid variable name | For example
--   "++"" ---&gt; "plus_plus" | This transformed variable is not visible
--   in the UI
mkLegalInfixVar :: String -> String

-- | Discover the function name inside (possibly nested) let expressions
--   Transform strings of the form "let (var tag "f" -&gt; f) = f x in f_1"
--   into "f"
removeLet :: String -> String

-- | Remove possible _n suffix from discovered function names
removeExtraDigits :: String -> String


-- | Module for recording and manipulating debug traces. For most users,
--   the <tt>TemplateHaskell</tt> helpers in <a>Debug</a> should be
--   sufficient.
module Debug.DebugTrace

-- | A flat encoding of debugging observations.
data DebugTrace
DebugTrace :: [Function] -> [Text] -> [CallData] -> DebugTrace

-- | Flat list of all the functions traced
[functions] :: DebugTrace -> [Function]

-- | Flat list of all the variable values observed
[variables] :: DebugTrace -> [Text]

-- | Flat list of all the function calls traced
[calls] :: DebugTrace -> [CallData]

-- | Metadata about a function, used to drive the HTML view.
data Function
Function :: Text -> Text -> [Text] -> Text -> Function

-- | Function name
[funName] :: Function -> Text

-- | Function source, using <tt>n</tt> to break lines
[funSource] :: Function -> Text

-- | Variables for the arguments to the function
[funArguments] :: Function -> [Text]

-- | Variable for the result of the function
[funResult] :: Function -> Text

-- | A flat encoding of an observed call.
data CallData
CallData :: Int -> [(Text, Int)] -> [Int] -> [Int] -> CallData

-- | An index into the <a>functions</a> table
[callFunctionId] :: CallData -> Int

-- | The value name tupled with an index into the <a>variables</a> table
[callVals] :: CallData -> [(Text, Int)]

-- | Indexes into the <a>calls</a> table
[callDepends] :: CallData -> [Int]

-- | Indexes into the <a>calls</a> table
[callParents] :: CallData -> [Int]

-- | Print information about the observed function calls to <a>stdout</a>,
--   in a human-readable format.
debugPrintTrace :: DebugTrace -> IO ()

-- | 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.
debugJSONTrace :: DebugTrace -> ByteString

-- | Open a web browser showing information about observed functions.
debugViewTrace :: DebugTrace -> IO ()

-- | Save information about observed functions to the specified file, in
--   HTML format.
debugSaveTrace :: FilePath -> DebugTrace -> IO ()

-- | Along with the function metatdata, get a list of the variable names
--   and string values from the trace
getTraceVars :: DebugTrace -> [(Function, [(Text, Text)])]
instance GHC.Show.Show Debug.DebugTrace.DebugTrace
instance GHC.Generics.Generic Debug.DebugTrace.DebugTrace
instance GHC.Classes.Eq Debug.DebugTrace.DebugTrace
instance GHC.Show.Show Debug.DebugTrace.CallData
instance GHC.Generics.Generic Debug.DebugTrace.CallData
instance GHC.Classes.Eq Debug.DebugTrace.CallData
instance GHC.Show.Show Debug.DebugTrace.Function
instance GHC.Classes.Ord Debug.DebugTrace.Function
instance GHC.Generics.Generic Debug.DebugTrace.Function
instance GHC.Classes.Eq Debug.DebugTrace.Function
instance Data.Aeson.Types.FromJSON.FromJSON Debug.DebugTrace.DebugTrace
instance Data.Aeson.Types.ToJSON.ToJSON Debug.DebugTrace.DebugTrace
instance Control.DeepSeq.NFData Debug.DebugTrace.DebugTrace
instance Control.DeepSeq.NFData Debug.DebugTrace.CallData
instance Data.Aeson.Types.FromJSON.FromJSON Debug.DebugTrace.CallData
instance Data.Aeson.Types.ToJSON.ToJSON Debug.DebugTrace.CallData
instance Data.Hashable.Class.Hashable Debug.DebugTrace.Function
instance Control.DeepSeq.NFData Debug.DebugTrace.Function
instance Data.Aeson.Types.FromJSON.FromJSON Debug.DebugTrace.Function
instance Data.Aeson.Types.ToJSON.ToJSON Debug.DebugTrace.Function
instance GHC.Show.Show a


-- | Module for debugging Haskell programs. To use, take the functions that
--   you are interested in debugging, e.g.:
--   
--   <pre>
--   module QuickSort(quicksort) where
--   import Data.List
--   
--   quicksort :: Ord a =&gt; [a] -&gt; [a]
--   quicksort [] = []
--   quicksort (x:xs) = quicksort lt ++ [x] ++ quicksort gt
--       where (lt, gt) = partition (&lt;= x) xs
--   </pre>
--   
--   Turn on the <tt>TemplateHaskell</tt> and <tt>ViewPatterns</tt>
--   extensions, import <a>Debug</a>, indent your code and place it under a
--   call to <a>debug</a>, e.g.:
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell, ViewPatterns, PartialTypeSignatures #-}
--   {-# OPTIONS_GHC -Wno-partial-type-signatures #-}
--   module QuickSort(quicksort) where
--   import Data.List
--   import Debug
--   
--   debug [d|
--      quicksort :: Ord a =&gt; [a] -&gt; [a]
--      quicksort [] = []
--      quicksort (x:xs) = quicksort lt ++ [x] ++ quicksort gt
--          where (lt, gt) = partition (&lt;= x) xs
--      |]
--   </pre>
--   
--   We can now run our debugger with:
--   
--   <pre>
--   $ 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&gt; quicksort "haskell"
--   "aehklls"
--   *QuickSort&gt; debugView
--   </pre>
--   
--   The final call to <a>debugView</a> starts a web browser to view the
--   recorded information. Alternatively call <a>debugSave</a> 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 <tt>TemplateHaskell</tt>) see
--   <a>Debug.DebugTrace</a>.
module Debug.Variables

-- | A <tt>TemplateHaskell</tt> wrapper to convert a normal function into a
--   traced function. For an example see <a>Debug</a>. Inserts
--   <a>funInfo</a> and <a>var</a> calls.
debug :: Q [Dec] -> Q [Dec]

-- | Clear all debug information. Useful when working in <tt>ghci</tt> to
--   reset any previous debugging work and reduce the amount of output.
debugClear :: IO ()

-- | Run a computation and open a browser window showing observed function
--   calls.
--   
--   <pre>
--   main = debugRun $ do
--         ...
--   </pre>
debugRun :: IO a -> IO a

-- | Print information about the observed function calls to <a>stdout</a>,
--   in a human-readable format.
debugPrint :: IO ()

-- | 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.
debugJSON :: IO String

-- | Open a web browser showing information about observed functions.
debugView :: IO ()

-- | Save information about observed functions to the specified file, in
--   HTML format.
debugSave :: FilePath -> IO ()

-- | A flat encoding of debugging observations.
data DebugTrace
DebugTrace :: [Function] -> [Text] -> [CallData] -> DebugTrace

-- | Flat list of all the functions traced
[functions] :: DebugTrace -> [Function]

-- | Flat list of all the variable values observed
[variables] :: DebugTrace -> [Text]

-- | Flat list of all the function calls traced
[calls] :: DebugTrace -> [CallData]

-- | Returns all the information about the observed function accumulated so
--   far in the variables.
getDebugTrace :: IO DebugTrace

-- | A version of <a>fun</a> allowing you to pass further information about
--   the <a>Function</a> which is used when showing debug views.
funInfo :: Show a => Function -> (Call -> a) -> a

-- | Called under a lambda with a function name to provide a unique context
--   for a particular call, e.g.:
--   
--   <pre>
--   tracedAdd x y = fun "add" $ \t -&gt; var t "x" x + var t "y" y
--   </pre>
--   
--   This function involves giving identity to function calls, so is
--   unsafe, and will only work under a lambda.
fun :: Show a => String -> (Call -> a) -> a

-- | Used in conjunction with <a>fun</a> to annotate variables. See
--   <a>fun</a> for an example.
var :: Show a => Call -> String -> a -> a
instance GHC.Classes.Ord Debug.Variables.Var
instance GHC.Classes.Eq Debug.Variables.Var
instance GHC.Show.Show Debug.Variables.Var

module Debug


-- | An alternative backend for lazy debugging with call stacks built on
--   top of the <a>Hoed</a> package.
--   
--   Instrumentation is done via a TH wrapper, which requires the following
--   extensions:
--   
--   <ul>
--   <li><a>TemplateHaskell</a></li>
--   <li><a>PartialTypeSignatures</a></li>
--   <li><a>ViewPatterns</a></li>
--   <li><a>ExtendedDefaultRules</a></li>
--   <li><a>FlexibleContexts</a></li>
--   </ul>
--   
--   Moreover, <a>Observable</a> instances are needed for value inspection.
--   The <a>debug'</a> template haskell wrapper can automatically insert
--   these for <a>Generic</a> types.
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell, ViewPatterns, PartialTypeSignatures, ExtendedDefaultRules #-}
--   {-# OPTIONS_GHC -Wno-partial-type-signatures #-}
--   module QuickSort(quicksort) where
--   import Data.List
--   import Debug.Hoed
--   
--   debug [d|
--      quicksort :: Ord a =&gt; [a] -&gt; [a]
--      quicksort [] = []
--      quicksort (x:xs) = quicksort lt ++ [x] ++ quicksort gt
--          where (lt, gt) = partition (&lt;= x) xs
--      |]
--   </pre>
--   
--   Now we can debug our expression under <a>debugRun</a>:
--   
--   <pre>
--   $ ghci examples/QuickSortHoed.hs
--   GHCi, version 8.2.1: http://www.haskell.org/ghc/  :? for help
--   [1 of 1] Compiling QuickSortHoed    ( QuickSortHoed.hs, interpreted )
--   Ok, 1 module loaded.
--   *QuickSort&gt; debugRun $ quicksort "haskell"
--   "aehklls"
--   </pre>
--   
--   After our expression is evaluated a web browser is started displaying
--   the recorded information.
--   
--   To debug an entire program, wrap the <tt>main</tt> function below
--   <a>debugRun</a>.
module Debug.Hoed

-- | A <tt>TemplateHaskell</tt> wrapper to convert normal functions into
--   traced functions.
debug :: Q [Dec] -> Q [Dec]

-- | A <tt>TemplateHaskell</tt> wrapper to convert normal functions into
--   traced functions and optionally insert <a>Observable</a> and
--   <a>Generic</a> instances.
debug' :: Config -> Q [Dec] -> Q [Dec]
data Config
Config :: Bool -> Bool -> [String] -> Config

-- | Insert <tt>deriving stock Generic</tt> on type declarations that don't
--   already derive <a>Generic</a>. Requires <tt>DeriveGeneric</tt> and
--   <tt>DerivingStrategies</tt>.
[generateGenericInstances] :: Config -> Bool

-- | Insert <tt>deriving anyclass Observable</tt> on type declarations that
--   don't already derive <a>Observable</a>. Requires
--   <tt>DeriveAnyClass</tt> and <tt>DerivingStrategies</tt>.
[generateObservableInstances] :: Config -> Bool

-- | Exclude types from instance generation by name (unqualified).
[excludeFromInstanceGeneration] :: Config -> [String]

-- | Runs the program collecting a debugging trace and then opens a web
--   browser to inspect it.
--   
--   <pre>
--   main = debugRun $ do
--         ...
--   </pre>
debugRun :: IO () -> IO ()

-- | Runs the program collecting a debugging trace
getDebugTrace :: HoedOptions -> IO () -> IO DebugTrace

-- | Print information about the observed function calls to <a>stdout</a>,
--   in a human-readable format.
debugPrintTrace :: DebugTrace -> IO ()

-- | 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.
debugJSONTrace :: DebugTrace -> ByteString

-- | Open a web browser showing information about observed functions.
debugViewTrace :: DebugTrace -> IO ()

-- | Save information about observed functions to the specified file, in
--   HTML format.
debugSaveTrace :: FilePath -> DebugTrace -> IO ()

-- | 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
constrain :: Observable a => a -> a -> a

-- | 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

-- | 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
instance Data.Hashable.Class.Hashable Debug.Hoed.HoedCallDetails
instance GHC.Generics.Generic Debug.Hoed.HoedCallDetails
instance GHC.Classes.Eq Debug.Hoed.HoedCallDetails
instance GHC.Classes.Eq Debug.Hoed.HoedFunctionKey
instance Data.Hashable.Class.Hashable Debug.Hoed.HoedFunctionKey
