Data.Portray.Prettyprinter

Provides rendering of Portrayal to Doc.

There are two intended uses of this module: firstly, to use prettyprinter'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 = renderStrict $ pretty (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 -> Text

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 -> Text

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

Eq a => Eq (WrappedPortray a)

Defined in Data.Portray.Prettyprinter

Methods

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

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

Ord a => Ord (WrappedPortray a)

Defined in Data.Portray.Prettyprinter

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

Show a => Show (WrappedPortray a)

Defined in Data.Portray.Prettyprinter

Methods

showsPrec :: Int -> WrappedPortray a -> ShowS

show :: WrappedPortray a -> String

showList :: [WrappedPortray a] -> ShowS

Portray a => Pretty (WrappedPortray a)

Provide an instance for Pretty by way of Portray.

Defined in Data.Portray.Prettyprinter

Methods

pretty :: WrappedPortray a -> Doc ann

prettyList :: [WrappedPortray a] -> Doc ann

Rendering Functions

With Associativity

type DocAssocPrec ann = Assoc -> Rational -> Doc ann

A Doc that varies according to associativity and precedence context.

toDocAssocPrecF :: PortrayalF (DocAssocPrec ann) -> DocAssocPrec ann

Render one layer of PortrayalF to DocAssocPrec.

toDocAssocPrec :: Portrayal -> DocAssocPrec ann

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

With Precedence

portrayalToDocPrecF :: PortrayalF (DocAssocPrec ann) -> Rational -> Doc ann

Render a PortrayalF to a Doc.

portrayalToDocPrec :: Portrayal -> Rational -> Doc ann

Render a Portrayal to a Doc with only operator precedence.

Convenience Functions

portrayalToDoc :: Portrayal -> Doc ann

Convert a Portrayal to a Doc.

prettyShowPortrayal :: Portrayal -> Text

Convenience function for rendering a Portrayal to a String.