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


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

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

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

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

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

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

-- | A single function call, used to attach additional information
data Call

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

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

-- | 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 ()
instance GHC.Show.Show Debug.Record.Function
instance GHC.Classes.Ord Debug.Record.Function
instance GHC.Classes.Eq Debug.Record.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 #-}
--   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.Record</a>.
module Debug

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

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

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

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