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


-- | Live visualization of data structures in GHCi
--   
--   Visualize live data structures in GHCi. Evaluation is not forced and
--   you can interact with the visualized data structures. This allows
--   seeing Haskell's lazy evaluation and sharing in action.
--   
--   To use this package add the accompanying <tt>ghci</tt> file to your
--   <tt>.ghci</tt> like this:
--   
--   <pre>
--   echo ":script $HOME/.cabal/share/ghc-vis-0.2/ghci" &gt;&gt; ~/.ghci
--   </pre>
--   
--   Now you can run ghci and experiment with <tt>ghc-vis</tt>. Start the
--   visualization:
--   
--   <pre>
--   $ ghci
--   GHCi, version 7.4.2: http://www.haskell.org/ghc/  :? for help
--   &gt; :vis
--   </pre>
--   
--   A blank window should appear now. This is the visualization window.
--   Add an expression to the visualization:
--   
--   <pre>
--   &gt; let a = [1..3]
--   &gt; :view a
--   &gt; let b = cycle a
--   &gt; :view b
--   &gt; :view "foo" ++ "bar"
--   </pre>
--   
--   <a>http://felsin9.de/nnis/ghc-vis/1.png</a>
--   
--   Functions are red, named objects are green and links to an already
--   shown object are blue.
--   
--   Notice how <tt>a</tt> is referenced by <tt>b</tt>.
--   
--   Evaluate an object that is shown in the visualization. You can also
--   click on the object to evaluate it.
--   
--   <pre>
--   &gt; :eval t1
--   </pre>
--   
--   <a>http://felsin9.de/nnis/ghc-vis/2.png</a>
--   
--   The first element of <tt>b</tt> has been evaluated. We see that it's a
--   reference to the value that's also referenced in a, as they share the
--   same name <a>t0</a>.
--   
--   Switch between the list view and the graph view:
--   
--   <pre>
--   &gt; :switch
--   </pre>
--   
--   <a>http://felsin9.de/nnis/ghc-vis/3.png</a>
--   
--   When an object is updated by accessing it, you have to call
--   <tt>:update</tt> to refresh the visualization window. You can also
--   click on an object to force an update:
--   
--   <pre>
--   &gt; a !! 2
--   3
--   &gt; :update
--   </pre>
--   
--   <a>http://felsin9.de/nnis/ghc-vis/4.png</a>
--   
--   Clear the visualization window, this also happens when you
--   <tt>:load</tt> or <tt>:reload</tt> a source file:
--   
--   <pre>
--   &gt; :clear
--   </pre>
@package ghc-vis
@version 0.2


module GHC.Vis.Types

-- | Signals that are sent to the GUI to signal changes
data Signal

-- | Add a new Box to be visualized
NewSignal :: Box -> String -> Signal

-- | Redraw
UpdateSignal :: Signal

-- | Remove all Boxes
ClearSignal :: Signal

-- | Switch to alternative view
SwitchSignal :: Signal

-- | Export the view to a file
ExportSignal :: String -> Signal

-- | Visualization views
data ViewType
ListView :: ViewType
GraphView :: ViewType

-- | The global state used for the visualizations.
data State
State :: Point -> ViewType -> State

-- | Current position of the mouse, updated with every movement
mousePos :: State -> Point

-- | What kind of visualization is currently running
view :: State -> ViewType

-- | An entry in a <a>HeapMap</a>, consisting of an identifier and a parsed
--   GHC heap entry
type HeapEntry = (Maybe String, Closure)

-- | A map of heap objects.
--   
--   We're using a slow, eq-based list instead of a proper map because
--   StableNames' hash values aren't stable enough
type HeapMap = [(Box, HeapEntry)]

-- | The second HeapMap includes BCO pointers, needed for list
--   visualization
type PrintState = State (Integer, HeapMap, HeapMap)

-- | Simple representation of objects on the heap, so they can be arranged
--   linearly
data VisObject
Unnamed :: String -> VisObject
Named :: String -> [VisObject] -> VisObject
Link :: String -> VisObject
Function :: String -> VisObject
instance Enum ViewType
instance Eq ViewType
instance Bounded ViewType
instance Eq VisObject
instance Show VisObject


module GHC.Vis.Internal

-- | Recursively walk down the heap objects and return the resulting map.
--   This function recognizes loops and avoids them. Big data structures
--   might still be very slow.
walkHeap :: [(Box, String)] -> IO HeapMap

-- | Walk the heap for a list of objects to be visualized and their
--   corresponding names.
parseBoxes :: [(Box, String)] -> IO [[VisObject]]

-- | Walk the heap for a list of objects to be visualized and their
--   corresponding names. Also return the resulting <a>HeapMap</a> and
--   another <a>HeapMap</a> that does not contain BCO pointers.
parseBoxesHeap :: [(Box, String)] -> IO ([[VisObject]], (Integer, HeapMap, HeapMap))

-- | Follows <a>BCOClosure</a>s, but not the debugging data structures
--   (ByteCodeInstr.BreakInfo) of GHC.
pointersToFollow2 :: Closure -> IO [Box]

-- | Textual representation of Heap objects, used in the graph
--   visualization.
showClosure :: Closure -> String


module GHC.Vis.GTK.Common

-- | Communication channel to the visualization
visSignal :: MVar Signal

-- | Whether a visualization is currently running
visRunning :: MVar Bool

-- | Internal state of the visualization
visState :: IORef State

-- | All the visualized boxes
visBoxes :: MVar [(Box, String)]

-- | Evaluate an object identified by a String.
evaluate :: String -> IO ()


module GHC.Vis.GTK.List

-- | Export the visualization to an SVG file
export :: String -> IO ()

-- | Draw visualization to screen, called on every update or when it's
--   requested from outside the program.
redraw :: WidgetClass w => w -> IO ()

-- | Handle a mouse click. If an object was clicked an <a>UpdateSignal</a>
--   is sent that causes the object to be evaluated and the screen to be
--   updated.
click :: IO ()

-- | Handle a mouse move. Causes an <a>UpdateSignal</a> if the mouse is
--   hovering a different object now, so the object gets highlighted and
--   the screen updated.
move :: WidgetClass w => w -> IO ()

-- | Something might have changed on the heap, update the view.
updateObjects :: [(Box, String)] -> IO ()


module GHC.Vis.Graph

-- | Take the objects to be visualized and run them through <tt>dot</tt>
--   and extract the drawing operations that have to be exectued to show
--   the graph of the heap map.
xDotParse :: [(Box, String)] -> IO ([(Maybe Node, Operation)], [Box], Rectangle)


module GHC.Vis.GTK.Graph

-- | Export the visualization to an SVG file
export :: String -> IO ()

-- | Draw visualization to screen, called on every update or when it's
--   requested from outside the program.
redraw :: WidgetClass w => w -> IO ()

-- | Handle a mouse click. If an object was clicked an <a>UpdateSignal</a>
--   is sent that causes the object to be evaluated and the screen to be
--   updated.
click :: IO ()

-- | Handle a mouse move. Causes an <a>UpdateSignal</a> if the mouse is
--   hovering a different object now, so the object gets highlighted and
--   the screen updated.
move :: WidgetClass w => w -> IO ()

-- | Something might have changed on the heap, update the view.
updateObjects :: [(Box, String)] -> IO ()


-- | Although ghc-vis is meant to be used in GHCi it can also be used as a
--   library in regular Haskell programs which are run or compiled by GHC.
--   You can run those programs using "runghc example.hs" or "ghc -threaded
--   example.hs &amp;&amp; ./example". Without the "-threaded"-Flag ghc-vis
--   does not work correctly. This is an example using ghc-vis outside of
--   GHCi:
--   
--   <pre>
--   import GHC.Vis
--   
--   main = do
--     putStrLn "Start"
--     let a = "teeest"
--     let b = [1..3]
--     let c = b ++ b
--     let d = [1..]
--     putStrLn $ show $ d !! 1
--   
--     visualization
--     view a "a"
--     view b "b"
--     view c "c"
--     view d "d"
--   
--     getChar
--     switch
--   
--     getChar
--     putStrLn "End"
--   </pre>
module GHC.Vis

-- | This is the main function. It's to be called from GHCi and launches a
--   graphical window in a new thread.
visualization :: IO ()

-- | Add expressions with a name to the visualization window.
view :: a -> String -> IO ()

-- | Evaluate an object that is shown in the visualization. (Names start
--   with <tt>t</tt>)
eval :: String -> IO ()

-- | Switch between the list view and the graph view
switch :: IO ()

-- | When an object is updated by accessing it, you have to call this to
--   refresh the visualization window. You can also click on an object to
--   force an update.
update :: IO ()

-- | Clear the visualization window, removing all expressions from it.
clear :: IO ()

-- | Export the current visualization view to an SVG file.
export :: String -> IO ()