Skip to content

Commit f0a4bcb

Browse files
cdepillaboutcdepillabout
committed
Add some additional pPrintString functions and documentation.
1 parent 9fc29c7 commit f0a4bcb

1 file changed

Lines changed: 183 additions & 19 deletions

File tree

‎src/Text/Pretty/Simple.hs‎

Lines changed: 183 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,16 @@ printing in color to a console with a light (white) background. The variations
2727
'pPrintNoColor', 'pShowNoColor', and 'pStringNoColor' are for pretty-printing
2828
without using color.
2929
30+
'pPrint' and 'pPrintLightBg' will intelligently decide whether or not to use
31+
ANSI escape codes for coloring depending on whether or not the output is
32+
a TTY. This works in most cases. If you want to force color output,
33+
you can use the 'pPrintForceColor' or 'pPrintForceColorLightBg' functions.
34+
3035
The variations 'pPrintOpt', 'pShowOpt', and 'pStringOpt' are used when
3136
specifying the 'OutputOptions'. Most users can ignore these.
3237
38+
There are a few other functions available that are similar to 'pPrint'.
39+
3340
See the Examples section at the end of this module for examples of acutally
3441
using 'pPrint'. See the
3542
<https://github.com/cdepillabout/pretty-simple#textprettysimple README.md>
@@ -40,35 +47,48 @@ module Text.Pretty.Simple
4047
-- * Output with color on dark background
4148
pPrint
4249
, pHPrint
50+
, pPrintString
51+
, pHPrintString
4352
, pPrintForceColor
4453
, pHPrintForceColor
54+
, pPrintStringForceColor
55+
, pHPrintStringForceColor
4556
, pShow
4657
, pString
47-
, pPrintString
4858
-- * Aliases for output with color on dark background
4959
, pPrintDarkBg
5060
, pHPrintDarkBg
61+
, pPrintStringDarkBg
62+
, pHPrintStringDarkBg
5163
, pPrintForceColorDarkBg
5264
, pHPrintForceColorDarkBg
65+
, pPrintStringForceColorDarkBg
66+
, pHPrintStringForceColorDarkBg
5367
, pShowDarkBg
5468
, pStringDarkBg
5569
-- * Output with color on light background
5670
, pPrintLightBg
5771
, pHPrintLightBg
72+
, pPrintStringLightBg
73+
, pHPrintStringLightBg
5874
, pPrintForceColorLightBg
5975
, pHPrintForceColorLightBg
76+
, pPrintStringForceColorLightBg
77+
, pHPrintStringForceColorLightBg
6078
, pShowLightBg
6179
, pStringLightBg
6280
-- * Output with NO color
6381
, pPrintNoColor
6482
, pHPrintNoColor
83+
, pPrintStringNoColor
84+
, pHPrintStringNoColor
6585
, pShowNoColor
6686
, pStringNoColor
6787
-- * Output With 'OutputOptions'
68-
, pPrintStringOpt
69-
, pHPrintStringOpt
7088
, pPrintOpt
7189
, pHPrintOpt
90+
, pPrintStringOpt
91+
, pHPrintStringOpt
7292
, pShowOpt
7393
, pStringOpt
7494
-- * 'OutputOptions'
@@ -125,26 +145,85 @@ import Text.Pretty.Simple.Internal
125145
-- printing to a terminal with a light background. Different colors are used.
126146
--
127147
-- Prints to 'stdout'. Use 'pHPrint' to print to a different 'Handle'.
148+
--
149+
-- >>> pPrint [Just (1, "hello")]
150+
-- [ Just
151+
-- ( 1
152+
-- , "hello"
153+
-- )
154+
-- ]
128155
pPrint :: (MonadIO m, Show a) => a -> m ()
129156
pPrint = pPrintOpt CheckColorTty defaultOutputOptionsDarkBg
130157

131158
-- | Similar to 'pPrint', but take a 'Handle' to print to.
159+
--
160+
-- >>> pHPrint stdout [Just (1, "hello")]
161+
-- [ Just
162+
-- ( 1
163+
-- , "hello"
164+
-- )
165+
-- ]
132166
pHPrint :: (MonadIO m, Show a) => Handle -> a -> m ()
133167
pHPrint = pHPrintOpt CheckColorTty defaultOutputOptionsDarkBg
134168

169+
-- | Similar to 'pPrint', but the first argument is a 'String' representing a
170+
-- data type that has already been 'show'ed.
171+
--
172+
-- >>> pPrintString $ show [ Just (1, "hello"), Nothing ]
173+
-- [ Just
174+
-- ( 1
175+
-- , "hello"
176+
-- )
177+
-- , Nothing
178+
-- ]
179+
pPrintString :: MonadIO m => String -> m ()
180+
pPrintString = pPrintStringOpt CheckColorTty defaultOutputOptionsDarkBg
181+
182+
-- | Similar to 'pHPrintString', but take a 'Handle' to print to.
183+
--
184+
-- >>> pHPrintString stdout $ show [ Just (1, "hello"), Nothing ]
185+
-- [ Just
186+
-- ( 1
187+
-- , "hello"
188+
-- )
189+
-- , Nothing
190+
-- ]
191+
pHPrintString :: MonadIO m => Handle -> String -> m ()
192+
pHPrintString = pHPrintStringOpt CheckColorTty defaultOutputOptionsDarkBg
193+
135194
-- | Similar to 'pPrint', but print in color regardless of whether the output
136195
-- goes to a TTY or not.
196+
--
197+
-- See 'pPrint' for an example of how to use this function.
137198
pPrintForceColor :: (MonadIO m, Show a) => a -> m ()
138199
pPrintForceColor = pPrintOpt NoCheckColorTty defaultOutputOptionsDarkBg
139200

140201
-- | Similar to 'pPrintForceColor', but take a 'Handle' to print to.
202+
--
203+
-- See 'pHPrint' for an example of how to use this function.
141204
pHPrintForceColor :: (MonadIO m, Show a) => Handle -> a -> m ()
142205
pHPrintForceColor = pHPrintOpt NoCheckColorTty defaultOutputOptionsDarkBg
143206

207+
-- | Similar to 'pPrintString', but print in color regardless of whether the
208+
-- output goes to a TTY or not.
209+
--
210+
-- See 'pPrintString' for an example of how to use this function.
211+
pPrintStringForceColor :: MonadIO m => String -> m ()
212+
pPrintStringForceColor = pPrintStringOpt NoCheckColorTty defaultOutputOptionsDarkBg
213+
214+
-- | Similar to 'pHPrintString', but print in color regardless of whether the
215+
-- output goes to a TTY or not.
216+
--
217+
-- See 'pHPrintString' for an example of how to use this function.
218+
pHPrintStringForceColor :: MonadIO m => Handle -> String -> m ()
219+
pHPrintStringForceColor = pHPrintStringOpt NoCheckColorTty defaultOutputOptionsDarkBg
220+
144221
-- | Similar to 'pPrintForceColor', but just return the resulting pretty-printed
145222
-- data type as a 'Text' instead of printing it to the screen.
146223
--
147224
-- This function is for printing to a dark background.
225+
--
226+
-- See 'pShowNoColor' for an example of how to use this function.
148227
pShow :: Show a => a -> Text
149228
pShow = pShowOpt defaultOutputOptionsDarkBg
150229

@@ -157,14 +236,11 @@ pShow = pShowOpt defaultOutputOptionsDarkBg
157236
-- 'pString' will correctly pretty-print JSON.
158237
--
159238
-- This function is for printing to a dark background.
239+
--
240+
-- See 'pStringNoColor' for an example of how to use this function.
160241
pString :: String -> Text
161242
pString = pStringOpt defaultOutputOptionsDarkBg
162243

163-
-- | Similar to 'pPrint', but the first argument is a 'String' representing a
164-
-- data type that has already been 'show'ed.
165-
pPrintString :: MonadIO m => String -> m ()
166-
pPrintString = pPrintStringOpt CheckColorTty defaultOutputOptionsDarkBg
167-
168244
--------------------------------------------------------
169245
-- aliases for printing in color to a dark background --
170246
--------------------------------------------------------
@@ -177,6 +253,14 @@ pPrintDarkBg = pPrint
177253
pHPrintDarkBg :: (MonadIO m, Show a) => Handle -> a -> m ()
178254
pHPrintDarkBg = pHPrint
179255

256+
-- | Alias for 'pPrintString'.
257+
pPrintStringDarkBg :: MonadIO m => String -> m ()
258+
pPrintStringDarkBg = pPrintString
259+
260+
-- | Alias for 'pHPrintString'.
261+
pHPrintStringDarkBg :: MonadIO m => Handle -> String -> m ()
262+
pHPrintStringDarkBg = pHPrintString
263+
180264
-- | Alias for 'pPrintForceColor'.
181265
pPrintForceColorDarkBg :: (MonadIO m, Show a) => a -> m ()
182266
pPrintForceColorDarkBg = pPrintForceColor
@@ -185,6 +269,14 @@ pPrintForceColorDarkBg = pPrintForceColor
185269
pHPrintForceColorDarkBg :: (MonadIO m, Show a) => Handle -> a -> m ()
186270
pHPrintForceColorDarkBg = pHPrintForceColor
187271

272+
-- | Alias for 'pPrintStringForceColor'.
273+
pPrintStringForceColorDarkBg :: MonadIO m => String -> m ()
274+
pPrintStringForceColorDarkBg = pPrintStringForceColor
275+
276+
-- | Alias for 'pHPrintStringForceColor'.
277+
pHPrintStringForceColorDarkBg :: MonadIO m => Handle -> String -> m ()
278+
pHPrintStringForceColorDarkBg = pHPrintStringForceColor
279+
188280
-- | Alias for 'pShow'.
189281
pShowDarkBg :: Show a => a -> Text
190282
pShowDarkBg = pShow
@@ -205,6 +297,14 @@ pPrintLightBg = pPrintOpt CheckColorTty defaultOutputOptionsLightBg
205297
pHPrintLightBg :: (MonadIO m, Show a) => Handle -> a -> m ()
206298
pHPrintLightBg = pHPrintOpt CheckColorTty defaultOutputOptionsLightBg
207299

300+
-- | Just like 'pPrintStringDarkBg', but for printing to a light background.
301+
pPrintStringLightBg :: MonadIO m => String -> m ()
302+
pPrintStringLightBg = pPrintStringOpt CheckColorTty defaultOutputOptionsLightBg
303+
304+
-- | Just like 'pHPrintStringDarkBg', but for printing to a light background.
305+
pHPrintStringLightBg :: MonadIO m => Handle -> String -> m ()
306+
pHPrintStringLightBg = pHPrintStringOpt CheckColorTty defaultOutputOptionsLightBg
307+
208308
-- | Just like 'pPrintForceColorDarkBg', but for printing to a light
209309
-- background.
210310
pPrintForceColorLightBg :: (MonadIO m, Show a) => a -> m ()
@@ -215,6 +315,16 @@ pPrintForceColorLightBg = pPrintOpt NoCheckColorTty defaultOutputOptionsLightBg
215315
pHPrintForceColorLightBg :: (MonadIO m, Show a) => Handle -> a -> m ()
216316
pHPrintForceColorLightBg = pHPrintOpt NoCheckColorTty defaultOutputOptionsLightBg
217317

318+
-- | Just like 'pPrintStringForceColorDarkBg', but for printing to a light
319+
-- background.
320+
pPrintStringForceColorLightBg :: MonadIO m => String -> m ()
321+
pPrintStringForceColorLightBg = pPrintStringOpt NoCheckColorTty defaultOutputOptionsLightBg
322+
323+
-- | Just like 'pHPrintStringForceColorDarkBg', but for printing to a light
324+
-- background.
325+
pHPrintStringForceColorLightBg :: MonadIO m => Handle -> String -> m ()
326+
pHPrintStringForceColorLightBg = pHPrintStringOpt NoCheckColorTty defaultOutputOptionsLightBg
327+
218328
-- | Just like 'pShowDarkBg', but for printing to a light background.
219329
pShowLightBg :: Show a => a -> Text
220330
pShowLightBg = pShowOpt defaultOutputOptionsLightBg
@@ -239,14 +349,47 @@ pPrintNoColor :: (MonadIO m, Show a) => a -> m ()
239349
pPrintNoColor = pPrintOpt NoCheckColorTty defaultOutputOptionsNoColor
240350

241351
-- | Like 'pPrintNoColor', but take a 'Handle' to determine where to print to.
352+
--
353+
-- >>> pHPrintNoColor stdout $ Just ["hello", "bye"]
354+
-- Just
355+
-- [ "hello"
356+
-- , "bye"
357+
-- ]
242358
pHPrintNoColor :: (MonadIO m, Show a) => Handle -> a -> m ()
243359
pHPrintNoColor = pHPrintOpt NoCheckColorTty defaultOutputOptionsNoColor
244360

361+
-- | Similar to 'pPrintString', but doesn't print in color. However, data types
362+
-- will still be indented nicely.
363+
--
364+
-- >>> pPrintStringNoColor $ show $ Just ["hello", "bye"]
365+
-- Just
366+
-- [ "hello"
367+
-- , "bye"
368+
-- ]
369+
pPrintStringNoColor :: MonadIO m => String -> m ()
370+
pPrintStringNoColor = pPrintStringOpt NoCheckColorTty defaultOutputOptionsNoColor
371+
372+
-- | Like 'pPrintStringNoColor', but take a 'Handle' to determine where to print to.
373+
--
374+
-- >>> pHPrintStringNoColor stdout $ show $ Just ["hello", "bye"]
375+
-- Just
376+
-- [ "hello"
377+
-- , "bye"
378+
-- ]
379+
pHPrintStringNoColor :: MonadIO m => Handle -> String -> m ()
380+
pHPrintStringNoColor = pHPrintStringOpt NoCheckColorTty defaultOutputOptionsNoColor
381+
245382
-- | Like 'pShow', but without color.
383+
--
384+
-- >>> pShowNoColor [ Nothing, Just (1, "hello") ]
385+
-- "[ Nothing\n, Just \n ( 1\n , \"hello\" \n ) \n] "
246386
pShowNoColor :: Show a => a -> Text
247387
pShowNoColor = pShowOpt defaultOutputOptionsNoColor
248388

249389
-- | LIke 'pString', but without color.
390+
--
391+
-- >>> pStringNoColor $ show [1, 2, 3]
392+
-- "[ 1\n, 2\n, 3\n] "
250393
pStringNoColor :: String -> Text
251394
pStringNoColor = pStringOpt defaultOutputOptionsNoColor
252395

@@ -334,25 +477,34 @@ pHPrintOpt ::
334477
pHPrintOpt checkColorTty outputOptions handle a =
335478
pHPrintStringOpt checkColorTty outputOptions handle $ show a
336479

337-
-- | Like 'pShow' but takes 'OutputOptions' to change how the
338-
-- pretty-printing is done.
339-
pShowOpt :: Show a => OutputOptions -> a -> Text
340-
pShowOpt outputOptions = pStringOpt outputOptions . show
341-
342-
-- | Like 'pString' but takes 'OutputOptions' to change how the
343-
-- pretty-printing is done.
344-
pStringOpt :: OutputOptions -> String -> Text
345-
pStringOpt outputOptions =
346-
render outputOptions . toList . expressionsToOutputs . expressionParse
347-
348480
-- | Similar to 'pPrintOpt', but the last argument is a string representing a
349481
-- data structure that has already been 'show'ed.
482+
--
483+
-- >>> let foo = show (1, (2, "hello", 3))
484+
-- >>> pPrintStringOpt CheckColorTty defaultOutputOptionsNoColor foo
485+
-- ( 1
486+
-- ,
487+
-- ( 2
488+
-- , "hello"
489+
-- , 3
490+
-- )
491+
-- )
350492
pPrintStringOpt :: MonadIO m => CheckColorTty -> OutputOptions -> String -> m ()
351493
pPrintStringOpt checkColorTty outputOptions =
352494
pHPrintStringOpt checkColorTty outputOptions stdout
353495

354496
-- | Similar to 'pPrintStringOpt', but take a 'Handle' to determine where to
355497
-- print to.
498+
--
499+
-- >>> let foo = show (1, (2, "hello", 3))
500+
-- >>> pHPrintStringOpt CheckColorTty defaultOutputOptionsNoColor stdout foo
501+
-- ( 1
502+
-- ,
503+
-- ( 2
504+
-- , "hello"
505+
-- , 3
506+
-- )
507+
-- )
356508
pHPrintStringOpt ::
357509
MonadIO m
358510
=> CheckColorTty
@@ -366,6 +518,18 @@ pHPrintStringOpt checkColorTty outputOptions handle str = do
366518
CheckColorTty -> hCheckTTY handle outputOptions
367519
NoCheckColorTty -> pure outputOptions
368520
liftIO $ LText.hPutStrLn handle $ pStringOpt realOutputOpts str
521+
522+
-- | Like 'pShow' but takes 'OutputOptions' to change how the
523+
-- pretty-printing is done.
524+
pShowOpt :: Show a => OutputOptions -> a -> Text
525+
pShowOpt outputOptions = pStringOpt outputOptions . show
526+
527+
-- | Like 'pString' but takes 'OutputOptions' to change how the
528+
-- pretty-printing is done.
529+
pStringOpt :: OutputOptions -> String -> Text
530+
pStringOpt outputOptions =
531+
render outputOptions . toList . expressionsToOutputs . expressionParse
532+
369533
-- $colorOptions
370534
--
371535
-- Additional settings for color options can be found in

0 commit comments

Comments
 (0)