diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ If you run this in `ghci` and type `print bar`, you'll get output like this: ```haskell +> print bar Bar {bar1 = 10, bar2 = [Foo {foo1 = 3, foo2 = ["hello","goodbye"], foo3 = 3.3},Foo {foo1 = 3, foo2 = ["hello","goodbye"], foo3 = 3.3}], bar3 = 10.55} ``` @@ -50,7 +51,8 @@ ``` Once you get a prompt in `ghci`, you can use `import` to get `pretty-simple`'s -`pPrint` function in scope. +[`pPrint`](https://hackage.haskell.org/package/pretty-simple/docs/Text-Pretty-Simple.html#v:pPrint) +function in scope. ```haskell > import Text.Pretty.Simple (pPrint) @@ -68,20 +70,21 @@ ## Features -`pretty-simple` has these features: - - Easy-to-read - Complex data types are simple to understand. - Color - Prints in color using ANSI escape codes. - - It is possible to print without color by using the `pPrintNoColor` + - It is possible to print without color by using the + [`pPrintNoColor`](https://hackage.haskell.org/package/pretty-simple/docs/Text-Pretty-Simple.html#v:pPrintNoColor) function. - Rainbox Parentheses - Easy to understand deeply nested data types. - Configurable Indentation - - Amount of indentation is configurable with the `pPrintOpt` function. + - Amount of indentation is configurable with the + [`pPrintOpt`](https://hackage.haskell.org/package/pretty-simple-1.0.0.6/docs/Text-Pretty-Simple.html#v:pPrintOpt) + function. - Fast - - No problem with data types thousands of lines long. + - No problem pretty-printing data types thousands of lines long. - Works with any data type with a `Show` instance - Some common Haskell data types have a `Show` instance that produces non-valid Haskell code. `pretty-simple` will pretty-print even these @@ -99,4 +102,7 @@ ## Contributions -Feel free to open an issue or PR for any bugs/problems/suggestions/improvements. +Feel free to open an +[issue](https://github.com/cdepillabout/pretty-simple/issues) or +[PR](https://github.com/cdepillabout/pretty-simple/pulls) for any +bugs/problems/suggestions/improvements. diff --git a/pretty-simple.cabal b/pretty-simple.cabal --- a/pretty-simple.cabal +++ b/pretty-simple.cabal @@ -1,5 +1,5 @@ name: pretty-simple -version: 1.0.0.6 +version: 1.1.0.0 synopsis: pretty printer for data types with a 'Show' instance. description: Please see README.md homepage: https://github.com/cdepillabout/pretty-simple diff --git a/src/Text/Pretty/Simple.hs b/src/Text/Pretty/Simple.hs --- a/src/Text/Pretty/Simple.hs +++ b/src/Text/Pretty/Simple.hs @@ -14,6 +14,16 @@ Stability : experimental Portability : POSIX +This module contains the functions 'pPrint', 'pShow', and 'pString', for +pretty-printing any Haskell data type with a show instance. + +'pPrint' should be the main go-to function when debugging in GHCi. + +There are other variations of 'pPrint', 'pShow', and 'pString' for printing +without color and changing the indentation amount. Most users can ignore these. + +See the Examples section at the end of this module for examples of acutally +using 'pPrint'. -} module Text.Pretty.Simple ( @@ -56,12 +66,24 @@ -- normal (color) functions -- ------------------------------ +-- | 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 () +-- @ pPrint :: (MonadIO m, Show a) => a -> m () pPrint = pPrintOpt defaultOutputOptions +-- | Similar to 'pPrint', but just return the resulting pretty-printed data +-- type as a 'Text' instead of printing it to the screen. pShow :: Show a => a -> Text pShow = pShowOpt defaultOutputOptions +-- | Similar to 'pShow', but the first argument is a 'String' representing a +-- data type that has already been 'show'ed. pString :: String -> Text pString = pStringOpt defaultOutputOptions @@ -69,28 +91,66 @@ -- no-color functions -- ------------------------ +-- | Similar to 'pPrint', but doesn't print in color. However, data types +-- will still be indented nicely. +-- +-- >>> pPrintNoColor $ Just ["hello", "bye"] +-- Just +-- [ "hello" +-- , "bye" +-- ] pPrintNoColor :: (MonadIO m, Show a) => a -> m () pPrintNoColor = pPrintOpt noColorOutputOptions +-- | Like 'pShow', but without color. pShowNoColor :: Show a => a -> Text pShowNoColor = pShowOpt noColorOutputOptions +-- | LIke 'pString', but without color. pStringNoColor :: String -> Text pStringNoColor = pStringOpt noColorOutputOptions +-- | 'noColorOutputOptions' is just like 'defaultOutputOptions', but +-- 'outputOptionsUseColor' is set to 'NoColor'. noColorOutputOptions :: OutputOptions -noColorOutputOptions = defaultOutputOptions {_useColor = NoColor} +noColorOutputOptions = defaultOutputOptions {outputOptionsUseColor = NoColor} --------------------------------- -- functions that take options -- --------------------------------- +-- | 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 noColorOutputOptions $ Just ("hello", "bye") +-- Just +-- ( "hello" +-- , "bye" +-- ) +-- +-- This is what smaller indentation looks like: +-- +-- >>> let smallIndent = noColorOutputOptions {outputOptionsIndentAmount = 1} +-- >>> pPrintOpt smallIndent $ Just ("hello", "bye") +-- Just +-- ( "hello" +-- , "bye" +-- ) pPrintOpt :: (MonadIO m, Show a) => OutputOptions -> a -> m () pPrintOpt outputOptions = liftIO . LText.putStrLn . pShowOpt outputOptions +-- | Like 'pShow' but takes 'OutputOptions' to change how the +-- pretty-printing is done. pShowOpt :: Show a => OutputOptions -> a -> Text pShowOpt outputOptions = pStringOpt outputOptions . show +-- | Like 'pString' but takes 'OutputOptions' to change how the +-- pretty-printing is done. pStringOpt :: OutputOptions -> String -> Text pStringOpt outputOptions string = case expressionParse string of @@ -99,14 +159,24 @@ render outputOptions . toList $ expressionsToOutputs expressions -- $examples --- Simple Haskell datatype: -- +-- 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. +-- +-- The following examples are all using 'pPrintNoColor' instead of 'pPrint' +-- because their output is being checked using +-- . 'pPrint' outputs ANSI +-- escape codes in order to produce color, so the following examples would be +-- hard to read had 'pPrint' been used. +-- +-- __Simple Haskell data type__ +-- -- >>> data Foo a = Foo a String deriving Show -- -- >>> pPrintNoColor $ Foo 3 "hello" -- Foo 3 "hello" -- --- Lists: +-- __List__ -- -- >>> pPrintNoColor $ [1,2,3] -- [ 1 @@ -114,7 +184,7 @@ -- , 3 -- ] -- --- Slightly more complicated lists: +-- __Slightly more complicated list__ -- -- >>> pPrintNoColor $ [ Foo [ (), () ] "hello" ] -- [ Foo @@ -131,7 +201,7 @@ -- , Foo [] "bye" -- ] -- --- Record: +-- __Record__ -- -- >>> :{ -- data Bar b = Bar @@ -154,7 +224,7 @@ -- ] -- } -- --- Newtype: +-- __Newtype__ -- -- >>> newtype Baz = Baz { unBaz :: [String] } deriving Show -- diff --git a/src/Text/Pretty/Simple/Internal/OutputPrinter.hs b/src/Text/Pretty/Simple/Internal/OutputPrinter.hs --- a/src/Text/Pretty/Simple/Internal/OutputPrinter.hs +++ b/src/Text/Pretty/Simple/Internal/OutputPrinter.hs @@ -25,9 +25,7 @@ import Control.Applicative #endif -import Control.Lens (view) -import Control.Lens.TH (makeLenses) -import Control.Monad.Reader (MonadReader, runReader) +import Control.Monad.Reader (MonadReader(reader), runReader) import Data.Data (Data) import Data.Foldable (fold, foldlM) import Data.Semigroup ((<>)) @@ -52,18 +50,19 @@ -- | Data-type wrapping up all the options available when rendering the list -- of 'Output's. data OutputOptions = OutputOptions - { _indentAmount :: Int + { outputOptionsIndentAmount :: Int -- ^ Number of spaces to use when indenting. It should probably be either 2 -- or 4. - , _useColor :: UseColor + , outputOptionsUseColor :: UseColor -- ^ Whether or not to use ansi escape sequences to print colors. } deriving (Data, Eq, Generic, Read, Show, Typeable) -makeLenses ''OutputOptions --- | Default values for 'OutputOptions'. '_indentAmount' defaults to 4, and --- '_useColor' defaults to 'UseColor'. +-- | Default values for 'OutputOptions'. 'outputOptionsIndentAmount' defaults +-- to 4, and 'outputOptionsUseColor' defaults to 'UseColor'. defaultOutputOptions :: OutputOptions -defaultOutputOptions = OutputOptions {_indentAmount = 4, _useColor = UseColor} +defaultOutputOptions = + OutputOptions + {outputOptionsIndentAmount = 4, outputOptionsUseColor = UseColor} render :: OutputOptions -> [Output] -> Text render options outputs = toLazyText $ runReader (renderOutputs outputs) options @@ -89,7 +88,7 @@ renderOutput (Output nest OutputCloseParen) = renderRaibowParenFor nest ")" renderOutput (Output nest OutputComma) = renderRaibowParenFor nest "," renderOutput (Output _ OutputIndent) = do - indentSpaces <- view indentAmount + indentSpaces <- reader outputOptionsIndentAmount pure . mconcat $ replicate indentSpaces " " renderOutput (Output _ OutputNewLine) = pure "\n" renderOutput (Output nest OutputOpenBrace) = renderRaibowParenFor nest "{" @@ -195,7 +194,7 @@ canUseColor :: MonadReader OutputOptions m => m Bool canUseColor = do - color <- view useColor + color <- reader outputOptionsUseColor case color of NoColor -> pure False UseColor -> pure True