Data.Portray.Pretty

Provides rendering of Portrayal to Doc.

There are two intended uses of this module: firstly, to use pretty's layout and rendering algorithms to render Portray instances, Diffs, or other Portrayals; 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 :: 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 = 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.

Pretty-Printing

showPortrayal :: Portray a => a -> String

Pretty-print a value using its Portray instance.

pp :: Portray a => a -> IO ()

Pretty-print a value to stdout using its Portray instance.

Diffing

showDiff :: Diff a => a -> a -> String

Pretty-print a diff between two values using a Diff instance.

ppd :: Diff a => a -> a -> IO ()

Pretty-print a diff between two values to stdout using a Diff instance.

DerivingVia wrapper

newtype WrappedPortray a

A newtype providing a Pretty instance via Portray, for DerivingVia.

Sadly we can't use Wrapped since it would be an orphan instance. Oh well. We'll just define a unique WrappedPortray newtype in each pretty-printer-integration package.

Constructors

WrappedPortray

Fields

• unWrappedPortray :: a

Instances

Show a => Show (WrappedPortray a)

Defined in Data.Portray.Pretty

Methods

showsPrec :: Int -> WrappedPortray a -> ShowS

show :: WrappedPortray a -> String

showList :: [WrappedPortray a] -> ShowS

Eq a => Eq (WrappedPortray a)

Defined in Data.Portray.Pretty

Methods

(==) :: WrappedPortray a -> WrappedPortray a -> Bool

(/=) :: WrappedPortray a -> WrappedPortray a -> Bool

Ord a => Ord (WrappedPortray a)

Defined in Data.Portray.Pretty

Methods

compare :: WrappedPortray a -> WrappedPortray a -> Ordering

(<) :: WrappedPortray a -> WrappedPortray a -> Bool

(<=) :: WrappedPortray a -> WrappedPortray a -> Bool

(>) :: WrappedPortray a -> WrappedPortray a -> Bool

(>=) :: WrappedPortray a -> WrappedPortray a -> Bool

max :: WrappedPortray a -> WrappedPortray a -> WrappedPortray a

min :: WrappedPortray a -> WrappedPortray a -> WrappedPortray a

Portray a => Pretty (WrappedPortray a)

Provide an instance for Pretty by way of Portray.

Defined in Data.Portray.Pretty

Methods

pPrintPrec :: PrettyLevel -> Rational -> WrappedPortray a -> Doc

pPrint :: WrappedPortray a -> Doc

pPrintList :: PrettyLevel -> [WrappedPortray a] -> Doc

Rendering Functions

With Associativity

type DocAssocPrec = Assoc -> Rational -> Doc

A Doc that varies according to associativity and precedence context.

toDocAssocPrecF :: PortrayalF DocAssocPrec -> DocAssocPrec

Render one layer of PortrayalF to DocAssocPrec.

toDocAssocPrec :: Portrayal -> DocAssocPrec

Render a Portrayal to a Doc with support for operator associativity.

With Precedence

portrayalToDocPrecF :: PortrayalF DocAssocPrec -> PrettyLevel -> Rational -> Doc

Render a PortrayalF to a Doc.

portrayalToDocPrec :: Portrayal -> PrettyLevel -> Rational -> Doc

Render a Portrayal to a Doc with only operator precedence.

Convenience Functions

portrayalToDoc :: Portrayal -> Doc

Convert a Portrayal to a Doc.

prettyShowPortrayal :: Portrayal -> String

Convenience function for rendering a Portrayal to a String.

pPrintPortrayal :: PrettyLevel -> Rational -> Portrayal -> Doc

portrayalToDocPrec with arguments ordered for use in pPrintPrec.