| Safe Haskell | None |
|---|---|
| Language | GHC2021 |
GHC.Debugger.View.Class
Description
The home of customizability for visualizing variables and values with haskell-debugger
Synopsis
- class DebugView a where
- debugValue :: a -> VarValue
- debugFields :: a -> Program VarFields
- data VarValue = VarValue {}
- newtype VarFields = VarFields {
- varFields :: [(String, VarFieldValue)]
- data VarFieldValue = VarFieldValue a
- simpleValue :: String -> Bool -> VarValue
- data Program a where
- PureProgram :: forall a. a -> Program a
- ProgramAp :: forall a1 a. Program (a1 -> a) -> Program a1 -> Program a
- ProgramBranch :: forall a. Program Bool -> Program a -> Program a -> Program a
- ProgramAskThunk :: forall a1. a1 -> Program Bool
- isThunk :: a -> Program Bool
- ifP :: Program Bool -> Program a -> Program a -> Program a
- newtype BoringTy a = BoringTy a
- data VarValueIO = VarValueIO {
- varValueIO :: Program (IO String)
- varExpandableIO :: Bool
- debugValueIOWrapper :: DebugView a => a -> IO [VarValueIO]
- newtype VarFieldsIO = VarFieldsIO {
- varFieldsIO :: Program [(IO String, VarFieldValue)]
- debugFieldsIOWrapper :: DebugView a => a -> IO [VarFieldsIO]
Writing custom debug visualizations
The entry point for custom visualizations is DebugView.
There are two axis of configuration:
- What to display inline in front of the variable name and whether it is expandable
- What fields are displayed when the value is expanded and what are their corresponding values
The former is answered by debugValue / VarValue and the latter by
debugFields / VarFields.
class DebugView a where Source #
Custom handling of debug terms (e.g. in the variables pane, or when inspecting a lazy variable)
Methods
debugValue :: a -> VarValue Source #
Compute the representation of a variable with the given value.
INVARIANT: this method should only called on values which are already in WHNF, never thunks.
That said, this method is responsible for determining how much it is forced when displaying it inline as a variable.
For instance, for String, a will be fully forced to display the entire
string in one go rather than as a linked list of Char
debugFields :: a -> Program VarFields Source #
Compute the fields to display when expanding a value of type a.
This method should only be called to get the fields if the corresponding
VarValuevarExpandable = True
Instances
The representation of the value for some variable on the debugger
Constructors
| VarValue | |
Fields
| |
The representation for fields of a value which is expandable in the debugger
Constructors
| VarFields | |
Fields
| |
data VarFieldValue Source #
A box for subfields of a value.
Used to construct the debug-view list of fields one gets from expanding a datatype.
See, for instance, the DebugView (a, b) instance for an example of how it is used.
The boxed value is returned as is and can be further forced or expanded by
the debugger, using either the existing DebugViewa (the instance is found at runtime), or the generic runtime
term inspection mechanisms otherwise.
Constructors
| VarFieldValue a |
A Program can describe a more complicated visualisation method which
The Program abstraction allows more complicated DebugView instances
to be constructed. The debugger will interpreter a Program lazily when
determining how to display a variable.
At the moment the only interesting query when constructing a program is determining if a value is already evaluated or not. This can be used to only display the evaluated prefix of a list for example.
Constructors
| PureProgram :: forall a. a -> Program a | Lift a value to a program |
| ProgramAp :: forall a1 a. Program (a1 -> a) -> Program a1 -> Program a | Program application |
| ProgramBranch :: forall a. Program Bool -> Program a -> Program a -> Program a | Evaluate the conditional, and branch on the result |
| ProgramAskThunk :: forall a1. a1 -> Program Bool | Is the value a thunk or evaluated? |
ifP :: Program Bool -> Program a -> Program a -> Program a Source #
Construct a program which branches
Utilities
These can make it easier to write your own custom instances. We also use them for the built-in custom instances.
Boring types scaffolding.
Meant to be used like:
deriving via (BoringTy Int) instance (DebugView Int)
to derive a DebugView for a type whose terms should always be fully forced
and displayed whole rather than as parts.
A boring type is one for which we don't care about the structure and would rather see "whole" when being inspected. Strings and literals are a good example, because it's more useful to see the string value than it is to see a linked list of characters where each has to be forced individually.
Constructors
| BoringTy a |
The internals
These are used by haskell-debugger when invoking these instances at
runtime and reconstructing the result from the heap.
They should never be used by a user looking to write custom visualizations.
data VarValueIO Source #
Wrapper to make evaluating from debugger easier
Constructors
| VarValueIO | |
Fields
| |
debugValueIOWrapper :: DebugView a => a -> IO [VarValueIO] Source #
newtype VarFieldsIO Source #
Constructors
| VarFieldsIO | |
Fields
| |
debugFieldsIOWrapper :: DebugView a => a -> IO [VarFieldsIO] Source #