portray-pretty 0.1.0.0 → 0.1.0.1

raw patch · 4 files changed

+71/−11 lines, 4 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

CHANGELOG.md +6/−0
portray-pretty.cabal +10/−4
src/Data/Portray/Pretty.hs +53/−7
test/Main.hs +2/−0

CHANGELOG.md view

@@ -1,3 +1,9 @@ # 0.1.0.0  Initial version.++# 0.1.0.1++* Fix needless parentheses around nullary function applications.+* Improve Haddock documentation.+* Improve the package description and synopsis.

portray-pretty.cabal view

@@ -4,12 +4,18 @@ -- -- see: https://github.com/sol/hpack ----- hash: ec86493a60d09bbf4f6c80bec86549dedd208dda4d0b516372d145ea259a5852+-- hash: 93aaf5ac8b3c548a84614877b51df32bc719f8111b0fd163f33fee8d6c7daf48  name:           portray-pretty-version:        0.1.0.0-synopsis:       "pretty" integration for "portray"-description:    This provides Pretty instances for types with Portray instances.+version:        0.1.0.1+synopsis:       A portray backend using the pretty package.+description:    This provides a <https://hackage.haskell.org/package/pretty pretty> backend+                for <https://hackage.haskell.org/package/portray portray>, along with+                derivable 'Text.PrettyPrint.HughesPJClass.Pretty' instances for types with+                'Data.Portray.Portray' instances.+                .+                See also+                <https://hackage.haskell.org/package/portray-prettyprinter portray-prettyprinter>. category:       Text homepage:       https://github.com/google/hs-portray#readme bug-reports:    https://github.com/google/hs-portray/issues

src/Data/Portray/Pretty.hs view

@@ -14,16 +14,61 @@  -- | Provides rendering of 'Portrayal' to 'Doc'. ----- The primary intended use of this module is to import 'WrappedPortray' and--- use it to derive 'Pretty' instances:+-- There are two intended uses of this module: firstly, to use @pretty@'s+-- layout and rendering algorithms to render 'Portray' instances, 'Diff's, or+-- other 'Portrayal's; and secondly, to derive 'Pretty' instances based on+-- existing 'Portray' instances.  I find the former more ergonomic, but in+-- established codebases that want to benefit from deriving, the latter may be+-- more achievable. --+-- The first usage is for codebases with pervasive use of 'Portray', and+-- involves using e.g. 'pp' and 'ppd' in GHCi, or 'showPortrayal' or 'showDiff'+-- in application code.  With this usage, anything you want to pretty-print+-- needs a 'Portray' instance, and the typeclass 'Pretty' is not involved in+-- any way.  With this approach, pretty-printable types and the types they+-- include should derive only 'Portray', and pretty-printing should be done+-- with the aforementioned utility functions:+-- -- @---     data MyRecord = MyRecord { anInt :: Int, anotherRecord :: MyRecord }---       deriving Generic---       deriving Portray via Wrapped Generic MyRecord---       deriving Pretty via WrappedPortray MyRecord+-- data MyRecord = MyRecord { anInt :: Int, anotherRecord :: MyOtherRecord }+--   deriving Generic+--   deriving Portray via Wrapped Generic MyRecord+--+-- example = 'showPortrayal' (MyRecord 2 ...) -- @ --+-- The second usage is to use @portray@'s generic deriving to provide derived+-- 'Pretty' instances, in a codebase that uses 'Pretty' as the preferred+-- typeclass for pretty-printable values.  With this usage, things you want to+-- pretty-print need 'Pretty' instances, and 'Portray' is needed for the+-- transitive closure of types included in types you want to derive 'Pretty'+-- instances for.  This may result in many types needing both instances of both+-- 'Pretty' (for direct pretty-printing) and 'Portray' (for deriving 'Portray'+-- on downstream types) instances.  Note that with this approach, types that+-- derive their 'Pretty' instances via 'Portray' will ignore any custom+-- 'Pretty' instances of nested types, since they recurse to nested 'Portray'+-- instances instead.+--+-- To derive an instance for a pretty-printable type, the type itself should+-- look like the following:+--+-- @+-- data MyRecord = MyRecord { anInt :: Int, anotherRecord :: MyOtherRecord }+--   deriving Generic+--   deriving Portray via Wrapped Generic MyRecord+--   deriving Pretty via WrappedPortray MyRecord+--+-- example = 'Text.PrettyPrint.HughesPJClass.prettyShow' (MyRecord 2 ...)+-- @+--+-- And any types transitively included in it should look like the following:+--+-- @+-- data MyOtherRecord = MyOtherRecord+--   deriving Generic+--   deriving Portray via Wrapped Generic MyRecord+-- @+-- -- This module also exports the underlying rendering functionality in a variety -- of forms for more esoteric uses. @@ -78,7 +123,7 @@ ppd :: Diff a => a -> a -> IO () ppd x = putStrLn . showDiff x --- | Pretty-print a diffe between to values using a 'Diff' instance.+-- | Pretty-print a diff between two values using a 'Diff' instance. showDiff :: Diff a => a -> a -> String showDiff x = maybe "_" prettyShowPortrayal . diff x @@ -127,6 +172,7 @@ toDocAssocPrecF :: PortrayalF DocAssocPrec -> DocAssocPrec toDocAssocPrecF = \case   AtomF txt -> \_ _ -> P.text (T.unpack txt)+  ApplyF fn [] -> \_ _ -> fn AssocL 10   ApplyF fn xs -> \lr p ->     P.maybeParens (not $ fixityCompatible (Infixity AssocL 10) lr p) $       P.sep

test/Main.hs view

@@ -37,6 +37,8 @@   , testGroup "Apply"       [ testCase "nullary" $           prettyShowPortrayal (Apply "Nothing" []) @?= "Nothing"+      , testCase "nullary 2" $+          prettyShowPortrayal (Apply "id" [Apply "Nothing" []]) @?= "id Nothing"       , testCase "unary" $           prettyShowPortrayal (Apply "Just" ["2"]) @?= "Just 2"       , testCase "parens" $