| Copyright | (c) Dennis Gosnell 2016 |
|---|---|
| License | BSD-style (see LICENSE file) |
| Maintainer | cdep.illabout@gmail.com |
| Stability | experimental |
| Portability | POSIX |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Text.Pretty.Simple
Description
This module contains the functions pPrint, pShow, and pString for
pretty-printing any Haskell data type with a Show instance.
pPrint is the main go-to function when debugging Haskell code. pShow and
pString are slight variations on pPrint.
pPrint, pShow, and pString will pretty-print in color using ANSI escape
codes. They look good on a console with a dark (black) background. The
variations pPrintLightBg, pShowLightBg, and pStringLightBg are for
printing in color to a console with a light (white) background. The variations
pPrintNoColor, pShowNoColor, and pStringNoColor are for pretty-printing
without using color.
pPrint and pPrintLightBg will intelligently decide whether or not to use
ANSI escape codes for coloring depending on whether or not the output is
a TTY. This works in most cases. If you want to force color output,
you can use the pPrintForceColor or pPrintForceColorLightBg functions.
The variations pPrintOpt, pShowOpt, and pStringOpt are used when
specifying the OutputOptions. Most users can ignore these.
There are a few other functions available that are similar to pPrint.
See the Examples section at the end of this module for examples of acutally
using pPrint. See the
README.md
for examples of printing in color.
Synopsis
- pPrint :: (MonadIO m, Show a) => a -> m ()
- pHPrint :: (MonadIO m, Show a) => Handle -> a -> m ()
- pPrintString :: MonadIO m => String -> m ()
- pHPrintString :: MonadIO m => Handle -> String -> m ()
- pPrintForceColor :: (MonadIO m, Show a) => a -> m ()
- pHPrintForceColor :: (MonadIO m, Show a) => Handle -> a -> m ()
- pPrintStringForceColor :: MonadIO m => String -> m ()
- pHPrintStringForceColor :: MonadIO m => Handle -> String -> m ()
- pShow :: Show a => a -> Text
- pString :: String -> Text
- pPrintDarkBg :: (MonadIO m, Show a) => a -> m ()
- pHPrintDarkBg :: (MonadIO m, Show a) => Handle -> a -> m ()
- pPrintStringDarkBg :: MonadIO m => String -> m ()
- pHPrintStringDarkBg :: MonadIO m => Handle -> String -> m ()
- pPrintForceColorDarkBg :: (MonadIO m, Show a) => a -> m ()
- pHPrintForceColorDarkBg :: (MonadIO m, Show a) => Handle -> a -> m ()
- pPrintStringForceColorDarkBg :: MonadIO m => String -> m ()
- pHPrintStringForceColorDarkBg :: MonadIO m => Handle -> String -> m ()
- pShowDarkBg :: Show a => a -> Text
- pStringDarkBg :: String -> Text
- pPrintLightBg :: (MonadIO m, Show a) => a -> m ()
- pHPrintLightBg :: (MonadIO m, Show a) => Handle -> a -> m ()
- pPrintStringLightBg :: MonadIO m => String -> m ()
- pHPrintStringLightBg :: MonadIO m => Handle -> String -> m ()
- pPrintForceColorLightBg :: (MonadIO m, Show a) => a -> m ()
- pHPrintForceColorLightBg :: (MonadIO m, Show a) => Handle -> a -> m ()
- pPrintStringForceColorLightBg :: MonadIO m => String -> m ()
- pHPrintStringForceColorLightBg :: MonadIO m => Handle -> String -> m ()
- pShowLightBg :: Show a => a -> Text
- pStringLightBg :: String -> Text
- pPrintNoColor :: (MonadIO m, Show a) => a -> m ()
- pHPrintNoColor :: (MonadIO m, Show a) => Handle -> a -> m ()
- pPrintStringNoColor :: MonadIO m => String -> m ()
- pHPrintStringNoColor :: MonadIO m => Handle -> String -> m ()
- pShowNoColor :: Show a => a -> Text
- pStringNoColor :: String -> Text
- pPrintOpt :: (MonadIO m, Show a) => CheckColorTty -> OutputOptions -> a -> m ()
- pHPrintOpt :: (MonadIO m, Show a) => CheckColorTty -> OutputOptions -> Handle -> a -> m ()
- pPrintStringOpt :: MonadIO m => CheckColorTty -> OutputOptions -> String -> m ()
- pHPrintStringOpt :: MonadIO m => CheckColorTty -> OutputOptions -> Handle -> String -> m ()
- pShowOpt :: Show a => OutputOptions -> a -> Text
- pStringOpt :: OutputOptions -> String -> Text
- data OutputOptions = OutputOptions {}
- data StringOutputStyle
- defaultOutputOptionsDarkBg :: OutputOptions
- defaultOutputOptionsLightBg :: OutputOptions
- defaultOutputOptionsNoColor :: OutputOptions
- data CheckColorTty
- defaultColorOptionsDarkBg :: ColorOptions
- defaultColorOptionsLightBg :: ColorOptions
- data ColorOptions = ColorOptions {
- colorQuote :: Style
- colorString :: Style
- colorError :: Style
- colorNum :: Style
- colorRainbowParens :: [Style]
- data Style = Style {
- styleColor :: Maybe (Color, Intensity)
- styleBold :: Bool
- styleItalic :: Bool
- styleUnderlined :: Bool
- data Color
- data Intensity
- colorNull :: Style
Output with color on dark background
pPrint :: (MonadIO m, Show a) => a -> m () Source #
Pretty-print any data type that has a Show instance.
If you've never seen MonadIO before, you can think of this function as
having the following type signature:
pPrint :: Show a => a -> IO ()
This function will only use colors if it detects it's printing to a TTY.
This function is for printing to a dark background. Use pPrintLightBg for
printing to a terminal with a light background. Different colors are used.
Prints to stdout. Use pHPrint to print to a different Handle.
>>>pPrint [Just (1, "hello")][ Just ( 1 , "hello" ) ]
pPrintString :: MonadIO m => String -> m () Source #
pHPrintString :: MonadIO m => Handle -> String -> m () Source #
Similar to pHPrintString, but take a Handle to print to.
>>>pHPrintString stdout $ show [ Just (1, "hello"), Nothing ][ Just ( 1 , "hello" ) , Nothing ]
pPrintForceColor :: (MonadIO m, Show a) => a -> m () Source #
pHPrintForceColor :: (MonadIO m, Show a) => Handle -> a -> m () Source #
Similar to pPrintForceColor, but take a Handle to print to.
See pHPrint for an example of how to use this function.
pPrintStringForceColor :: MonadIO m => String -> m () Source #
Similar to pPrintString, but print in color regardless of whether the
output goes to a TTY or not.
See pPrintString for an example of how to use this function.
pHPrintStringForceColor :: MonadIO m => Handle -> String -> m () Source #
Similar to pHPrintString, but print in color regardless of whether the
output goes to a TTY or not.
See pHPrintString for an example of how to use this function.
pShow :: Show a => a -> Text Source #
Similar to pPrintForceColor, but just return the resulting pretty-printed
data type as a Text instead of printing it to the screen.
This function is for printing to a dark background.
See pShowNoColor for an example of how to use this function.
pString :: String -> Text Source #
Similar to pShow, but the first argument is a String representing a
data type that has already been showed.
This will work on any String that is similar to a Haskell data type. The
only requirement is that the strings are quoted, and braces, parentheses, and
brackets are correctly used to represent indentation. For example,
pString will correctly pretty-print JSON.
This function is for printing to a dark background.
See pStringNoColor for an example of how to use this function.
Aliases for output with color on dark background
pPrintStringDarkBg :: MonadIO m => String -> m () Source #
Alias for pPrintString.
pHPrintStringDarkBg :: MonadIO m => Handle -> String -> m () Source #
Alias for pHPrintString.
pPrintForceColorDarkBg :: (MonadIO m, Show a) => a -> m () Source #
Alias for pPrintForceColor.
pHPrintForceColorDarkBg :: (MonadIO m, Show a) => Handle -> a -> m () Source #
Alias for pHPrintForceColor.
pPrintStringForceColorDarkBg :: MonadIO m => String -> m () Source #
Alias for pPrintStringForceColor.
pHPrintStringForceColorDarkBg :: MonadIO m => Handle -> String -> m () Source #
Alias for pHPrintStringForceColor.
Output with color on light background
pPrintLightBg :: (MonadIO m, Show a) => a -> m () Source #
Just like pPrintDarkBg, but for printing to a light background.
pHPrintLightBg :: (MonadIO m, Show a) => Handle -> a -> m () Source #
Just like pHPrintDarkBg, but for printing to a light background.
pPrintStringLightBg :: MonadIO m => String -> m () Source #
Just like pPrintStringDarkBg, but for printing to a light background.
pHPrintStringLightBg :: MonadIO m => Handle -> String -> m () Source #
Just like pHPrintStringDarkBg, but for printing to a light background.
pPrintForceColorLightBg :: (MonadIO m, Show a) => a -> m () Source #
Just like pPrintForceColorDarkBg, but for printing to a light
background.
pHPrintForceColorLightBg :: (MonadIO m, Show a) => Handle -> a -> m () Source #
Just like pHPrintForceColorDarkBg, but for printing to a light
background.
pPrintStringForceColorLightBg :: MonadIO m => String -> m () Source #
Just like pPrintStringForceColorDarkBg, but for printing to a light
background.
pHPrintStringForceColorLightBg :: MonadIO m => Handle -> String -> m () Source #
Just like pHPrintStringForceColorDarkBg, but for printing to a light
background.
pShowLightBg :: Show a => a -> Text Source #
Just like pShowDarkBg, but for printing to a light background.
pStringLightBg :: String -> Text Source #
Just like pStringDarkBg, but for printing to a light background.
Output with NO color
pPrintNoColor :: (MonadIO m, Show a) => a -> m () Source #
Similar to pPrint, but doesn't print in color. However, data types
will still be indented nicely.
>>>pPrintNoColor $ Just ["hello", "bye"]Just [ "hello" , "bye" ]
pHPrintNoColor :: (MonadIO m, Show a) => Handle -> a -> m () Source #
Like pPrintNoColor, but take a Handle to determine where to print to.
>>>pHPrintNoColor stdout $ Just ["hello", "bye"]Just [ "hello" , "bye" ]
pPrintStringNoColor :: MonadIO m => String -> m () Source #
Similar to pPrintString, but doesn't print in color. However, data types
will still be indented nicely.
>>>pPrintStringNoColor $ show $ Just ["hello", "bye"]Just [ "hello" , "bye" ]
pHPrintStringNoColor :: MonadIO m => Handle -> String -> m () Source #
Like pPrintStringNoColor, but take a Handle to determine where to print to.
>>>pHPrintStringNoColor stdout $ show $ Just ["hello", "bye"]Just [ "hello" , "bye" ]
pShowNoColor :: Show a => a -> Text Source #
Like pShow, but without color.
>>>pShowNoColor [ Nothing, Just (1, "hello") ]"[ Nothing\n, Just\n ( 1\n , \"hello\"\n )\n]"
pStringNoColor :: String -> Text Source #
LIke pString, but without color.
>>>pStringNoColor $ show [1, 2, 3]"[ 1\n, 2\n, 3\n]"
Output With OutputOptions
pPrintOpt :: (MonadIO m, Show a) => CheckColorTty -> OutputOptions -> a -> m () Source #
Similar to pPrint but takes OutputOptions to change how the
pretty-printing is done.
For example, pPrintOpt can be used to make the indentation much smaller
than normal.
This is what the normal indentation looks like:
>>>pPrintOpt NoCheckColorTty defaultOutputOptionsNoColor $ Just ("hello", "bye")Just ( "hello" , "bye" )
This is what smaller indentation looks like:
>>>let smallIndent = defaultOutputOptionsNoColor {outputOptionsIndentAmount = 1}>>>pPrintOpt CheckColorTty smallIndent $ Just ("hello", "bye")Just ( "hello" , "bye" )
Lines in strings get indented
>>>pPrintOpt NoCheckColorTty defaultOutputOptionsNoColor (1, (2, "foo\nbar\nbaz", 3))( 1 , ( 2 , "foo bar baz" , 3 ) )
Lines get indented even in custom show instances
>>>data Foo = Foo>>>instance Show Foo where show _ = "foo\nbar\nbaz">>>pPrintOpt CheckColorTty defaultOutputOptionsNoColor (1, (2, Foo, 3))( 1 , ( 2 , foo bar baz , 3 ) )
CheckColorTty determines whether to test stdout for whether or not it is
connected to a TTY.
If set to NoCheckColorTty, then pPrintOpt won't
check if stdout is a TTY. It will print in color depending on the value
of outputOptionsColorOptions.
If set to CheckColorTty, then pPrintOpt will check if stdout is
conneted to a TTY. If stdout is determined to be connected to a TTY, then
it will print in color depending on the value of
outputOptionsColorOptions. If stdout is determined to NOT be connected
to a TTY, then it will NOT print in color, regardless of the value of
outputOptionsColorOptions.
pHPrintOpt :: (MonadIO m, Show a) => CheckColorTty -> OutputOptions -> Handle -> a -> m () Source #
pPrintStringOpt :: MonadIO m => CheckColorTty -> OutputOptions -> String -> m () Source #
pHPrintStringOpt :: MonadIO m => CheckColorTty -> OutputOptions -> Handle -> String -> m () Source #
Similar to pPrintStringOpt, but take a Handle to determine where to
print to.
>>>let foo = show (1, (2, "hello", 3))>>>pHPrintStringOpt CheckColorTty defaultOutputOptionsNoColor stdout foo( 1 , ( 2 , "hello" , 3 ) )
pShowOpt :: Show a => OutputOptions -> a -> Text Source #
Like pShow but takes OutputOptions to change how the
pretty-printing is done.
pStringOpt :: OutputOptions -> String -> Text Source #
Like pString but takes OutputOptions to change how the
pretty-printing is done.
OutputOptions
data OutputOptions Source #
Data-type wrapping up all the options available when rendering the list
of Outputs.
Constructors
| OutputOptions | |
Fields
| |
Instances
data StringOutputStyle Source #
Control how escaped and non-printable are output for strings.
See outputOptionsStringStyle for what the output looks like with each of
these options.
Constructors
| Literal | Output string literals by printing the source characters exactly. For examples: without this option the printer will insert a newline in
place of |
| EscapeNonPrintable | Replace non-printable characters with hexadecimal escape sequences. |
| DoNotEscapeNonPrintable | Output non-printable characters without modification. |
Instances
defaultOutputOptionsDarkBg :: OutputOptions Source #
Default values for OutputOptions when printing to a console with a dark
background. outputOptionsIndentAmount is 4, and
outputOptionsColorOptions is defaultColorOptionsDarkBg.
defaultOutputOptionsLightBg :: OutputOptions Source #
Default values for OutputOptions when printing to a console with a light
background. outputOptionsIndentAmount is 4, and
outputOptionsColorOptions is defaultColorOptionsLightBg.
defaultOutputOptionsNoColor :: OutputOptions Source #
Default values for OutputOptions when printing using using ANSI escape
sequences for color. outputOptionsIndentAmount is 4, and
outputOptionsColorOptions is Nothing.
data CheckColorTty Source #
Determines whether pretty-simple should check if the output Handle is a
TTY device. Normally, users only want to print in color if the output
Handle is a TTY device.
Constructors
| CheckColorTty | Check if the output |
| NoCheckColorTty | Don't check if the output |
Instances
| Generic CheckColorTty Source # | |
Defined in Text.Pretty.Simple.Internal.Printer Associated Types type Rep CheckColorTty :: Type -> Type # | |
| Show CheckColorTty Source # | |
Defined in Text.Pretty.Simple.Internal.Printer Methods showsPrec :: Int -> CheckColorTty -> ShowS # show :: CheckColorTty -> String # showList :: [CheckColorTty] -> ShowS # | |
| Eq CheckColorTty Source # | |
Defined in Text.Pretty.Simple.Internal.Printer Methods (==) :: CheckColorTty -> CheckColorTty -> Bool # (/=) :: CheckColorTty -> CheckColorTty -> Bool # | |
| type Rep CheckColorTty Source # | |
Defined in Text.Pretty.Simple.Internal.Printer | |
ColorOptions
defaultColorOptionsDarkBg :: ColorOptions Source #
Default color options for use on a dark background.
defaultColorOptionsLightBg :: ColorOptions Source #
Default color options for use on a light background.
data ColorOptions Source #
These options are for colorizing the output of functions like pPrint.
If you don't want to use a color for one of the options, use colorNull.
Constructors
| ColorOptions | |
Fields
| |
Instances
Ways to style terminal output.
Constructors
| Style | |
Fields
| |
Instances
| Generic Style Source # | |
| Show Style Source # | |
| Eq Style Source # | |
| type Rep Style Source # | |
Defined in Text.Pretty.Simple.Internal.Color type Rep Style = D1 ('MetaData "Style" "Text.Pretty.Simple.Internal.Color" "pretty-simple-4.1.2.0-GMnRiTYYdgPHrTLYlYPD9K" 'False) (C1 ('MetaCons "Style" 'PrefixI 'True) ((S1 ('MetaSel ('Just "styleColor") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe (Color, Intensity))) :*: S1 ('MetaSel ('Just "styleBold") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool)) :*: (S1 ('MetaSel ('Just "styleItalic") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool) :*: S1 ('MetaSel ('Just "styleUnderlined") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool)))) | |
Dull or vivid coloring, as supported by ANSI terminals.
Instances
| Show Intensity | |
| Eq Intensity | |
| Ord Intensity | |
Defined in Prettyprinter.Render.Terminal.Internal | |
Examples
Here are some examples of using pPrint on different data types. You can
look at these examples to get an idea of what pPrint will output.
Simple Haskell data type
>>>data Foo a = Foo a String Char deriving Show
>>>pPrint $ Foo 3 "hello" 'a'Foo 3 "hello" 'a'
List
>>>pPrint $ [1,2,3][ 1 , 2 , 3 ]
Slightly more complicated list
>>>pPrint $ [ Foo [ (), () ] "hello" 'b' ][ Foo [ () , () ] "hello" 'b' ]
>>>pPrint $ [ Foo [ "bar", "baz" ] "hello" 'a', Foo [] "bye" 'b' ][ Foo [ "bar" , "baz" ] "hello" 'a' , Foo [] "bye" 'b' ]
Record
>>>:{data Bar b = Bar { barInt :: Int , barA :: b , barList :: [Foo Double] } deriving Show :}
>>>pPrint $ Bar 1 [10, 11] [Foo 1.1 "" 'a', Foo 2.2 "hello" 'b']Bar { barInt = 1 , barA = [ 10 , 11 ] , barList = [ Foo 1.1 "" 'a' , Foo 2.2 "hello" 'b' ] }
Newtype
>>>newtype Baz = Baz { unBaz :: [String] } deriving Show
>>>pPrint $ Baz ["hello", "bye"]Baz { unBaz = [ "hello" , "bye" ] }
Newline Rules
>>>data Foo = A | B Foo | C [Foo] [Foo] deriving Show
>>>pPrint $ B ( B A )B ( B A )
>>>pPrint $ B ( B ( B A ) )B ( B ( B A ) )
>>>pPrint $ B ( B ( B ( B A ) ) )B ( B ( B ( B A ) ) )
>>>pPrint $ B ( C [A, A] [B A, B (B (B A))] )B ( C [ A , A ] [ B A , B ( B ( B A ) ) ] )
Laziness
>>>take 100 . unpack . pShowNoColor $ [1..]"[ 1\n, 2\n, 3\n, 4\n, 5\n, 6\n, 7\n, 8\n, 9\n, 10\n, 11\n, 12\n, 13\n, 14\n, 15\n, 16\n, 17\n, 18\n, 19\n, 20\n, 21\n, 22"
Unicode
>>>pPrint $ Baz ["猫", "犬", "ヤギ"]Baz { unBaz = [ "猫" , "犬" , "ヤギ" ] }
Compactness options
>>>pPrintStringOpt CheckColorTty defaultOutputOptionsDarkBg {outputOptionsCompact = True} "AST [] [Def ((3,1),(5,30)) (Id \"fact'\" \"fact'\") [] (Forall ((3,9),(3,26)) [((Id \"n\" \"n_0\"),KPromote (TyCon (Id \"Nat\" \"Nat\")))])]"AST [] [ Def ( ( 3, 1 ), ( 5, 30 ) ) ( Id "fact'" "fact'" ) [] ( Forall ( ( 3, 9 ), ( 3, 26 ) ) [ ( ( Id "n" "n_0" ), KPromote ( TyCon ( Id "Nat" "Nat" ) ) ) ] ) ]
>>>pPrintOpt CheckColorTty defaultOutputOptionsDarkBg {outputOptionsCompactParens = True} $ B ( C [A, A] [B A, B (B (B A))] )B ( C [ A , A ] [ B A , B ( B ( B A ) ) ] )
>>>pPrintOpt CheckColorTty defaultOutputOptionsDarkBg {outputOptionsCompact = True} $ [("id", 123), ("state", 1), ("pass", 1), ("tested", 100), ("time", 12345)][ ( "id", 123 ), ( "state", 1 ), ( "pass", 1 ), ( "tested", 100 ), ( "time", 12345 ) ]
Initial indent
>>>pPrintOpt CheckColorTty defaultOutputOptionsDarkBg {outputOptionsInitialIndent = 3} $ B ( B ( B ( B A ) ) )B ( B ( B ( B A ) ) )
Weird/illegal show instances
>>>pPrintString "2019-02-18 20:56:24.265489 UTC"2019-02-18 20:56:24.265489 UTC
>>>pPrintString "a7ed86f7-7f2c-4be5-a760-46a3950c2abf"a7ed86f7-7f2c-4be5-a760-46a3950c2abf
>>>pPrintString "192.168.0.1:8000"192.168.0.1:8000
>>>pPrintString "A @\"type\" 1"A @"type" 1
>>>pPrintString "2+2"2+2
>>>pPrintString "1.0e-2"1.0e-2
>>>pPrintString "0x1b"0x1b
Other
Making sure the spacing after a string is correct.
>>>data Foo = Foo String Int deriving Show
>>>pPrint $ Foo "bar" 0Foo "bar" 0
Non-printable characters will get escaped.
>>>pPrint "this string has non-printable characters: \x8 and \x9""this string has non-printable characters: \x8 and \x9"
If you don't want non-printable characters to be escaped, take a look at
outputOptionsStringStyle and StringOutputStyle.