prettyprinter

A modern, easy to use, well-documented, extensible pretty-printer. http://github.com/quchen/prettyprinter

Version on this page:1.2.1
LTS Haskell 12.22:1.2.1
Stackage Nightly 2018-12-14:1.2.1
Latest on Hackage:1.2.1

See all snapshots prettyprinter appears in

BSD2 licensed by Phil Wadler, Daan Leijen, Max Bolingbroke, Edward Kmett, David Luposchainsky
Maintained by David Luposchainsky <dluposchainsky at google>

Module documentation for 1.2.1

There are no documented modules for this package.

A modern Wadler/Leijen Prettyprinter


tl;dr

A prettyprinter/text rendering engine. Easy to use, well-documented, ANSI terminal backend exists, HTML backend is trivial to implement, no name clashes, Text-based, extensible.

let prettyType = align . sep . zipWith (<+>) ("::" : repeat "->")
    prettySig name ty = pretty name <+> prettyType ty
in  prettySig "example" ["Int", "Bool", "Char", "IO ()"]
-- Output for wide enough formats:
example :: Int -> Bool -> Char -> IO ()

-- Output for narrow formats:
example :: Int
        -> Bool
        -> Char
        -> IO ()

Longer; want to read

This package defines a prettyprinter to format text in a flexible and convenient way. The idea is to combine a document out of many small components, then using a layouter to convert it to an easily renderable simple document, which can then be rendered to a variety of formats, for example plain Text, or Markdown. What you are reading right now was generated by this library (see GenerateReadme.hs).

Why another prettyprinter?

Haskell, more specifically Hackage, has a zoo of Wadler/Leijen based prettyprinters already. Each of them addresses a different concern with the classic wl-pprint package. This package solves all these issues, and then some.

Text instead of String

String has exactly one use, and that’s showing Hello World in tutorials. For all other uses, Text is what people should be using. The prettyprinter uses no String definitions anywhere; using a String means an immediate conversion to the internal Text-based format.

Extensive documentation

The library is stuffed with runnable examples, showing use cases for the vast majority of exported values. Many things reference related definitions, everything comes with at least a sentence explaining its purpose.

No name clashes

Many prettyprinters use the legacy API of the first Wadler/Leijen prettyprinter, which used e.g. (<$>) to separate lines, which clashes with the ubiquitous synonym for fmap that’s been in Base for ages. These definitions were either removed or renamed, so there are no name clashes with standard libraries anymore.

Annotation support

Text is not all letters and newlines. Often, we want to add more information, the simplest kind being some form of styling. An ANSI terminal supports coloring, a web browser a plethora of different formattings.

More complex uses of annotations include e.g. adding type annotations for mouse-over hovers when printing a syntax tree, adding URLs to documentation, or adding source locations to show where a certain piece of output comes from. Idris is a project that makes extensive use of such a feature.

Special care has been applied to make annotations unobtrusive, so that if you don’t need or care about them there is no overhead, neither in terms of usability nor performance.

Extensible backends

A document can be rendered in many different ways, for many different clients. There is plain text, there is the ANSI terminal, there is the browser. Each of these speak different languages, and the backend is responsible for the translation to those languages. Backends should be readily available, or easy to implement if a custom solution is desired.

As a result, each backend requires only minimal dependencies; if you don’t want to print to an ANSI terminal for example, there is no need to have a dependency on a terminal library.

Performance

Rendering large documents should be done efficiently, and the library should make it easy to optimize common use cases for the programmer.

Open implementation

The type of documents is abstract in most of the other Wadler/Leijen prettyprinters, making it hard to impossible to write adaptors from one library to another. The type should be exposed for such purposes so it is possible to write adaptors from library to library, or each of them is doomed to live on its own small island of incompatibility. For this reason, the Doc type is fully exposed in a semi-internal module for this specific use case.

The prettyprinter family

The prettyprinter family of packages consists of:

  • prettyprinter is the core package. It defines the language to generate nicely laid out documents, which can then be given to renderers to display them in various ways, e.g. HTML, or plain text.
  • prettyprinter-ansi-terminal provides a renderer suitable for ANSI terminal output including colors (at the cost of a dependency more).
  • prettyprinter-compat-wl-pprint provides a drop-in compatibility layer for previous users of the wl-pprint package. Use it for easy adaption of the new prettyprinter, but don’t develop anything new with it.
  • prettyprinter-compat-ansi-wl-pprint is the same, but for previous users of ansi-wl-pprint.
  • prettyprinter-compat-annotated-wl-pprint is the same, but for previous users of annotated-wl-pprint.
  • prettyprinter-convert-ansi-wl-pprint is a converter, not a drop-in replacement, for documents generated by ansi-wl-pprint. Useful for interfacing with other libraries that use the other format, like Trifecta and Optparse-Applicative.

Differences to the old Wadler/Leijen prettyprinters

The library originally started as a fork of ansi-wl-pprint until every line had been touched. The result is still in the same spirit as its predecessors, but modernized to match the current ecosystem and needs.

The most significant changes are:

  1. (<$>) is removed as an operator, since it clashes with the common alias for fmap.
  2. All but the essential <> and <+> operators were removed or replaced by ordinary names.
  3. Everything extensively documented, with references to other functions and runnable code examples.
  4. Use of Text instead of String.
  5. A fuse function to optimize often-used documents before rendering for efficiency.
  6. SimpleDoc was renamed SimpleDocStream, to contrast the new SimpleDocTree.
  7. In the ANSI backend, instead of providing an own colorization function for each color/intensity/layer combination, they have been combined in /color/ /colorDull/, /bgColor/, and /bgColorDull/ functions, which can be found in the ANSI terminal specific @prettyprinter-ansi-terminal@ package.

Historical notes

This module is based on previous work by Daan Leijen and Max Bolingbroke, who implemented and significantly extended the prettyprinter given by a paper by Phil Wadler in his 1997 paper »A Prettier Printer«, by adding lots of convenience functions, styling, and new functionality. Their package, ansi-wl-pprint is widely used in the Haskell ecosystem, and is at the time of writing maintained by Edward Kmett.

Changes

1.2.1

  • Add function to trim trailing space in layouted SimpleDocStream, removeTrailingWhitespace
  • Add Pretty instances for Identity and Const

1.2.0.1

  • Fix alterAnnotationsS (and thus unAnnotateS), which removed pushing, but not popping, style frames. This led to them throwing errors in pretty much all use cases.

1.2

  • encloseSep does no longer include an align wrapper; in other words,

    encloseSep_old … = align (encloseSep_new …)
    
  • Change the default ribbon fraction to 1 (was 0.4)

  • Expose viaShow and unsafeViaShow from the public module

  • Fix layoutSmart behaving as if there was no space left for unbounded pages

1.1.1

  • Add panicPeekedEmpty and panicPoppedEmpty to the panic module

1.1.0.1

  • Rendering directly to a handle is now more efficient in the Text renderer, since no intermediate Text is generated anymore.
  • Remove upper version bounds from .cabal files

1.1

  • Allow alterAnnotations to convert one annotation to multiple ones, to support e.g. Keyword ---> Green+Bold
  • Remove Pretty instance for Doc: the implicit un-annotation done by it did more harm than good.

1.0.1

  • Add alterAnnotations, which allows changing or removing annotations. reAnnotate and unAnnotate are now special cases of this.
  • Fix »group« potentially taking exponential time, by making the (internal) flatten function detect whether it is going to have any effect inside group.
  • Add proper version bounds for all dependencies and backport them to version 1
  • Haddock: example for Pretty Void

1

  • Add Foldable/Traversable instances for SimpleDocTree, SimpleDocStream
  • Add Functor instances for Doc, SimpleDocTree, SimpleDocStream
  • Add the simplified renderers renderSimplyDecorated and renderSimplyDecoratedA to the tree and stack renderer modules
  • Lots of typo fixes and doc tweaks
  • Add a changelog :-)

0.1

Initial release.

comments powered byDisqus