-- 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 -- Debug. @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 -- "++"" ---> "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" -> 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 TemplateHaskell helpers in Debug 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 n 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 functions table [callFunctionId] :: CallData -> Int -- | The value name tupled with an index into the variables table [callVals] :: CallData -> [(Text, Int)] -- | Indexes into the calls table [callDepends] :: CallData -> [Int] -- | Indexes into the calls table [callParents] :: CallData -> [Int] -- | Print information about the observed function calls to stdout, -- 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.: -- -- 
--   module QuickSort(quicksort) where
--   import Data.List
--   
--   quicksort :: Ord a => [a] -> [a]
--   quicksort [] = []
--   quicksort (x:xs) = quicksort lt ++ [x] ++ quicksort gt
--       where (lt, gt) = partition (<= x) xs
--
-- -- Turn on the TemplateHaskell and ViewPatterns -- extensions, import Debug, indent your code and place it under a -- call to debug, e.g.: -- -- 
--   {-# LANGUAGE TemplateHaskell, ViewPatterns, PartialTypeSignatures #-}
--   {-# OPTIONS_GHC -Wno-partial-type-signatures #-}
--   module QuickSort(quicksort) where
--   import Data.List
--   import Debug
--   
--   debug [d|
--      quicksort :: Ord a => [a] -> [a]
--      quicksort [] = []
--      quicksort (x:xs) = quicksort lt ++ [x] ++ quicksort gt
--          where (lt, gt) = partition (<= x) xs
--      |]
--
-- -- We can now run our debugger with: -- -- 
--   $ 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> quicksort "haskell"
--   "aehklls"
--   *QuickSort> debugView
--
-- -- The final call to debugView starts a web browser to view the -- recorded information. Alternatively call debugSave 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 TemplateHaskell) see -- Debug.DebugTrace. module Debug.Variables -- | A TemplateHaskell wrapper to convert a normal function into a -- traced function. For an example see Debug. Inserts -- funInfo and var calls. debug :: Q [Dec] -> Q [Dec] -- | Clear all debug information. Useful when working in ghci 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. -- -- 
--   main = debugRun $ do
--         ...
--
debugRun :: IO a -> IO a -- | Print information about the observed function calls to stdout, -- 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 fun allowing you to pass further information about -- the Function 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.: -- -- 
--   tracedAdd x y = fun "add" $ \t -> var t "x" x + var t "y" y
--
-- -- 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 fun to annotate variables. See -- fun 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 Hoed package. -- -- Instrumentation is done via a TH wrapper, which requires the following -- extensions: -- -- -- -- Moreover, Observable instances are needed for value inspection. -- The debug' template haskell wrapper can automatically insert -- these for Generic types. -- -- 
--   {-# 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 => [a] -> [a]
--      quicksort [] = []
--      quicksort (x:xs) = quicksort lt ++ [x] ++ quicksort gt
--          where (lt, gt) = partition (<= x) xs
--      |]
--
-- -- Now we can debug our expression under debugRun: -- -- 
--   $ 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> debugRun $ quicksort "haskell"
--   "aehklls"
--
-- -- After our expression is evaluated a web browser is started displaying -- the recorded information. -- -- To debug an entire program, wrap the main function below -- debugRun. module Debug.Hoed -- | A TemplateHaskell wrapper to convert normal functions into -- traced functions. debug :: Q [Dec] -> Q [Dec] -- | A TemplateHaskell wrapper to convert normal functions into -- traced functions and optionally insert Observable and -- Generic instances. debug' :: Config -> Q [Dec] -> Q [Dec] data Config Config :: Bool -> Bool -> [String] -> Config -- | Insert deriving stock Generic on type declarations that don't -- already derive Generic. Requires DeriveGeneric and -- DerivingStrategies. [generateGenericInstances] :: Config -> Bool -- | Insert deriving anyclass Observable on type declarations that -- don't already derive Observable. Requires -- DeriveAnyClass and DerivingStrategies. [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. -- -- 
--   main = debugRun $ do
--         ...
--
debugRun :: IO () -> IO () -- | Runs the program collecting a debugging trace getDebugTrace :: HoedOptions -> IO () -> IO DebugTrace -- | Print information about the observed function calls to stdout, -- 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. -- -- -- -- 
--   instance (Observable a, Observable b) => Observable (excluded, a,b) where
--          observe (excluded,a,b) = send "(,,)" (return (,,) excluded << a << b)
--
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: -- -- 
--   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
--
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