Heap.Console

Warning: "heap-console" is meant for debugging only - make sure you remove it in production.

This module provides combinators for spawning heap console in convenient way.

Console usage

Console startup is indicated by a message:

[Entering heap-view - use `:help` for more information]

followed by console's prompt:

heap-console>

here you can probe for values of bindings or use provided commands - e.g. when opening console with:

inspect (42, 'a')

you can inspect given value under name it:

heap-console> it
(_, 'a')

or see the value strictly evaluated (up to the configured depth):

heap-console> !it
(42, 'a')

or you can access it's parts by using selection:

heap-console> it.1
'a'

Bindings can be automatically created with functions like inspectD, added in arbitrary places in program using e.g. evidenceD or added in console directly by assigning results of selections:

heap-console> foo = bar.0.baz

Selections consist of sequence of dot-separated indexes, optionally prefixed with ! to force thunks along the way. Valid indexes are:

• positive integer (e.g. 3) - position of element in list, tuple or other data constructor
• record field name (e.g. foo) - name of field in record (only works when given enough information - that is, when value has Data instance available)

In general, it's recommended to prefer combinators suffixed with D when possible - they require Data instance for bindings being added, but provide ability to recover record syntax and information about unpacked fields - in case of combinators without D, unpacked fields appear as plain Word#s without any information about their origin and are not indexable. Data instances can be easily derived using -XDeriveDataTypeable.

Documentation

inspect :: a -> a

Opens console for inspecting argument before returning it. Argument is provided in console under name it.

>>> inspect 42
[Entering heap-view - use `:help` for more information]
...
[Exiting heap-view]
42

inspectD :: Data a => a -> a

Version of inspect providing more precise inspection using Data - prefer this one where possible.

>>> inspectD 42
[Entering heap-view - use `:help` for more information]
...
[Exiting heap-view]
42

inspecting :: a -> b -> b

Opens console for inspecting a before returning b. Argument a is provided in console under name it.

>>> inspecting 42 'a'
[Entering heap-view - use `:help` for more information]
...
[Exiting heap-view]
'a'

inspectingD :: Data a => a -> b -> b

Version of inspecting providing more precise inspection using Data - prefer this one where possible.

>>> inspectingD 42 'a'
[Entering heap-view - use `:help` for more information]
...
[Exiting heap-view]
'a'

inspectA :: Applicative f => a -> f ()

Opens console for inspecting argument. Argument is provided in console under name it.

>>> inspectA 42
[Entering heap-view - use `:help` for more information]
...
[Exiting heap-view]

inspectAD :: (Data a, Applicative f) => a -> f ()

Version of inspectA providing more precise inspection using Data - prefer this one where possible.

>>> inspectAD 42
[Entering heap-view - use `:help` for more information]
...
[Exiting heap-view]

investigate :: HasCallStack => a -> b

Opens console for inspecting argument before failing with error. Argument is provided in console under name it.

>>> investigate 42
[Entering heap-view - use `:help` for more information]
...
[Exiting heap-view]
*** Exception: Heap.Console.investigate: closed investigation
CallStack (from HasCallStack):
  investigate, called at <interactive>:1:1 in interactive:Ghci

investigateD :: (HasCallStack, Data a) => a -> b

Version of investigate providing more precise inspection using Data - prefer this one where possible.

>>> investigateD 42
[Entering heap-view - use `:help` for more information]
...
[Exiting heap-view]
*** Exception: Heap.Console.investigateD: closed investigation
CallStack (from HasCallStack):
  investigateD, called at <interactive>:1:1 in interactive:Ghci

inspection :: Applicative f => f ()

Opens console with recorded "evidence" in scope.

>>> inspection
[Entering heap-view - use `:help` for more information]
...
[Exiting heap-view]

withInspection :: a -> a

Opens console with recorded "evidence" in scope, before returning given argument.

>>> withInspection 42
[Entering heap-view - use `:help` for more information]
...
[Exiting heap-view]
42

investigation :: HasCallStack => a

Opens console with recorded "evidence" in scope before failing with error.

>>> investigation
[Entering heap-view - use `:help` for more information]
heap-console>
[Exiting heap-view]
*** Exception: Heap.Console.investigation: closed investigation
CallStack (from HasCallStack):
  investigation, called at <interactive>:1:1 in interactive:Ghci

withEvidence :: String -> a -> b -> b

Records a as "evidence" to be later provided in console under given name, before returning b.

>>> withEvidence "foo" 'a' inspection
[Entering heap-view - use `:help` for more information]
heap-console> foo
'a'
...
[Exiting heap-view]

withEvidenceD :: Data a => String -> a -> b -> b

Version of withEvidence providing more precise inspection using Data - prefer this one where possible.

>>> withEvidenceD "foo" 'a' inspection
[Entering heap-view - use `:help` for more information]
heap-console> foo
'a'
...
[Exiting heap-view]

evidence :: Applicative f => String -> a -> f ()

Records a as "evidence" to be later provided in console under given name.

>>> evidence "foo" 42
>>> inspection
[Entering heap-view - use `:help` for more information]
heap-console> foo
42
...
[Exiting heap-view]

evidenceD :: (Data a, Applicative f) => String -> a -> f ()

Version of evidence providing more precise inspection using Data - prefer this one where possible.

>>> evidenceD "foo" 42
>>> inspection
[Entering heap-view - use `:help` for more information]
heap-console> foo
42
...
[Exiting heap-view]