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 are values bound under concrete names in console. They 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]