Safe Haskell	None
Language	GHC2021

GHC.Debugger.View.Class

Contents

Writing custom debug visualizations
Utilities
The internals

Description

The home of customizability for visualizing variables and values with haskell-debugger

Synopsis

class DebugView a where
- debugValue :: a -> VarValue
- debugFields :: a -> VarFields
data VarValue = VarValue {
- varValue :: String
- varExpandable :: Bool
}
newtype VarFields = VarFields {
- varFields :: [(String, VarFieldValue)]
}
data VarFieldValue = VarFieldValue a
newtype BoringTy a = BoringTy a
data VarValueIO = VarValueIO {
- varValueIO :: IO String
- varExpandableIO :: Bool
}
debugValueIOWrapper :: DebugView a => a -> IO [VarValueIO]
newtype VarFieldsIO = VarFieldsIO {
- varFieldsIO :: [(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 -> 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 VarValue has varExpandable = True.

Instances

Instances details

DebugView ByteString Source #
Instance details Defined in GHC.Debugger.View.ByteString Methods debugValue :: ByteString -> VarValue Source # debugFields :: ByteString -> VarFields Source #
DebugView Text Source #
Instance details Defined in GHC.Debugger.View.Text Methods debugValue :: Text -> VarValue Source # debugFields :: Text -> VarFields Source #
DebugView String Source #
Instance details Defined in GHC.Debugger.View.Class Methods debugValue :: String -> VarValue Source # debugFields :: String -> VarFields Source #
DebugView Integer Source #
Instance details Defined in GHC.Debugger.View.Class Methods debugValue :: Integer -> VarValue Source # debugFields :: Integer -> VarFields Source #
DebugView Char Source #
Instance details Defined in GHC.Debugger.View.Class Methods debugValue :: Char -> VarValue Source # debugFields :: Char -> VarFields Source #
DebugView Double Source #
Instance details Defined in GHC.Debugger.View.Class Methods debugValue :: Double -> VarValue Source # debugFields :: Double -> VarFields Source #
DebugView Float Source #
Instance details Defined in GHC.Debugger.View.Class Methods debugValue :: Float -> VarValue Source # debugFields :: Float -> VarFields Source #
DebugView Int Source #
Instance details Defined in GHC.Debugger.View.Class Methods debugValue :: Int -> VarValue Source # debugFields :: Int -> VarFields Source #
DebugView Word Source #
Instance details Defined in GHC.Debugger.View.Class Methods debugValue :: Word -> VarValue Source # debugFields :: Word -> VarFields Source #
DebugView (IntMap a) Source #
Instance details Defined in GHC.Debugger.View.Containers Methods debugValue :: IntMap a -> VarValue Source # debugFields :: IntMap a -> VarFields Source #
Show a => DebugView (BoringTy a) Source #
Instance details Defined in GHC.Debugger.View.Class Methods debugValue :: BoringTy a -> VarValue Source # debugFields :: BoringTy a -> VarFields Source #
Show k => DebugView (Map k a) Source #
Instance details Defined in GHC.Debugger.View.Containers Methods debugValue :: Map k a -> VarValue Source # debugFields :: Map k a -> VarFields Source #
DebugView (a, b) Source #
Instance details Defined in GHC.Debugger.View.Class Methods debugValue :: (a, b) -> VarValue Source # debugFields :: (a, b) -> VarFields Source #

data VarValue Source #

The representation of the value for some variable on the debugger

Constructors

VarValue
Fields varValue :: String The value to display inline for this variable varExpandable :: Bool Can this variable further be expanded (s.t. `debugFields` is not null?)

Instances

Instances details

Read VarValue Source #
Instance details Defined in GHC.Debugger.View.Class Methods readsPrec :: Int -> ReadS VarValue # readList :: ReadS [VarValue] # readPrec :: ReadPrec VarValue # readListPrec :: ReadPrec [VarValue] #
Show VarValue Source #
Instance details Defined in GHC.Debugger.View.Class Methods showsPrec :: Int -> VarValue -> ShowS # show :: VarValue -> String # showList :: [VarValue] -> ShowS #

newtype VarFields Source #

The representation for fields of a value which is expandable in the debugger

Constructors

VarFields
Fields varFields :: [(String, VarFieldValue)]

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 DebugView instance for the existential a (the instance is found at runtime), or the generic runtime term inspection mechanisms otherwise.

Constructors

VarFieldValue a

Utilities

These can make it easier to write your own custom instances. We also use them for the built-in custom instances.

newtype BoringTy a Source #

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

Instances

Instances details

Show a => DebugView (BoringTy a) Source #
Instance details Defined in GHC.Debugger.View.Class Methods debugValue :: BoringTy a -> VarValue Source # debugFields :: BoringTy a -> VarFields Source #

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 varValueIO :: IO String varExpandableIO :: Bool

debugValueIOWrapper :: DebugView a => a -> IO [VarValueIO] Source #

newtype VarFieldsIO Source #

Constructors

VarFieldsIO
Fields varFieldsIO :: [(IO String, VarFieldValue)]

debugFieldsIOWrapper :: DebugView a => a -> IO [VarFieldsIO] Source #