Text.PrettyPrint.GenericPretty

GenericPretty is a haskell library that provides support for automatic derivation of pretty printing functions on user defined data types. The Pretty library is used underneath, the work is done over Doc types.

The output provided by the library functions is identical to that of show, except it has extra whitespace.

This requires the use of the new GHC.Generics features: http://www.haskell.org/haskellwiki/Generics. As of 9.08.2011, these aren't present in the stable GHC releases, but seem to be present in the GHC HEAD development snapshots >= 7.1.20110601.

The Generics used are based on those described in the paper "A Generic Deriving Mechanism for Haskell" : http://dreixel.net/research/pdf/gdmh.pdf . There are however several changes between the mechanism described in the paper and the one implemented in GHC which are described here: http://www.haskell.org/haskellwiki/Generics#Changes_from_the_paper.

For more info and examples of usage please see the README file included in the package

Documentation

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

The default Pretty Printer,

It uses the default style, defStyle

ppLen :: Out a => Int -> a -> IO ()

Semi-customizable pretty printer. Takes the lineLength as a parameter uses mode = PageMode and ribbonsPerLine = 1

ppStyle :: Out a => Style -> a -> IO ()

Customizable pretty printer, takes a user defined Style as a parameter and uses outputIO to obtain the result

pretty :: Out a => a -> String

The default pretty printer returning Strings

It uses the default style, defStyle

prettyLen :: Out a => Int -> a -> String

Semi-customizable pretty printer. Takes the lineLength as a parameter uses mode = PageMode and ribbonsPerLine = 1

prettyStyle :: Out a => Style -> a -> String

Customizable pretty printer, takes a user defined Style as a parameter and uses outputStr to obtain the result

fullPP

Arguments

:: Out a

=> a

The value to pretty print

-> Mode

The Pretty mode to use (eg: 'Pretty.PageMode')

-> Int

The maximum line length

-> Float

The number of ribbons per line (the fraction of line length over the max length of non-indentation text per line; eg: lineLength = 80 and ribbonsPerLine = 1.5 => max of 53 non-indentation characters per line)

-> (TextDetails -> b -> b)

Function that handles the text conversion (eg: 'outputIO')

-> b

The end element of the result ( eg: "" or putChar('\n') )

-> b

The pretty printed result

fullPP is a fully customizable Pretty Printer Every other pretty printer just gives some default values to fullPP

genOut :: (Generic a, GOut (Rep a)) => Int -> a -> Doc

The default generic out method, converts the type into a sum of products and passes it on to the generic pretty printing functions, finally it concatenates all of the SDoc's

It needs to be used in code to define the instance for Out

For instance, given the declaration:

 data Tree a =  Leaf a  |  Node (Tree a) (Tree a) deriving (Generic)

The user would need to write an instance declaration like:

 instance (Out a) => Out (Tree a) where
   docPrec = genOut

After doing this, the user can now use pretty printing function like pp and pretty on data of type Tree

outputIO :: TextDetails -> IO () -> IO ()

outputIO transforms the text into strings and outputs it directly.

This is one example of a function that can handle the text conversion for fullPP.

outputStr :: TextDetails -> String -> String

outputStr just leaves the text as a string. This is usefull if you want to further process the pretty printed result.

This is another example of a function that can handle the text conversion for fullPP.

wrapParens :: Bool -> [Doc] -> [Doc]

Utility function used to wrap the passed value in parens if the bool is true A single paren should never occupy a whole line, so they are concatenated to the first and last elements in the list, instead of just adding them to the list

defStyle :: Style

The default Style used for pp and pretty (mode=PageMode, lineLength=100, ribbonsPerLine=1.5)

class Out a where

The class Out is the equivalent of Show

Conversion of values to pretty printable Docs.

Minimal complete definition: docPrec or doc.

Derived instances of Out have the following properties

• The result of show is a syntactically correct Haskell expression containing only constants, given the fixity declarations in force at the point where the type is declared. It contains only the constructor names defined in the data type, parentheses, and spaces. When labelled constructor fields are used, braces, commas, field names, and equal signs are also used.
• If the constructor is defined to be an infix operator, then docPrec will produce infix applications of the constructor.
• the representation will be enclosed in parentheses if the precedence of the top-level constructor in x is less than d (associativity is ignored). Thus, if d is 0 then the result is never surrounded in parentheses; if d is 11 it is always surrounded in parentheses, unless it is an atomic expression.
• If the constructor is defined using record syntax, then doc will produce the record-syntax form, with the fields given in the same order as the original declaration.

For example, given the declarations

 data Tree a =  Leaf a  |  Node (Tree a) (Tree a) deriving (Generic)

The derived instance of Out is equivalent to:

 instance (Out a) => Out (Tree a) where
  
         docPrec d (Leaf m) = Pretty.sep $ wrapParens (d > appPrec) $
              text "Leaf" : [nest (constrLen + parenLen) (docPrec (appPrec+1) m)]
           where appPrec = 10
                 constrLen = 5;
                 parenLen = if(d > appPrec) then 1 else 0
 
         docPrec d (Node u v) = Pretty.sep $ wrapParens (d > appPrec) $
              text "Node" : 
              nest (constrLen + parenLen) (docPrec (appPrec+1) u) : 
              [nest (constrLen + parenLen) (docPrec (appPrec+1) v)]
           where appPrec = 10
                 constrLen = 5
                 parenLen = if(d > appPrec) then 1 else 0

Methods

docPrec

Arguments

:: Int

the operator precedence of the enclosing context (a number from 0 to 11). Function application has precedence 10.

-> a

the value to be converted to a String

-> Doc

the resulting Doc

docPrec is the equivalent of showsPrec Convert a value to a pretty printable Doc.

doc :: a -> Doc

doc is the equivalent of show

A specialised variant of docPrec, using precedence context zero.

docList :: [a] -> Doc

docList is the equivalent of showList

The method docList is provided to allow the programmer to give a specialised way of showing lists of values. For example, this is used by the predefined Out instance of the Char type, where values of type String should be shown in double quotes, rather than between square brackets.

Instances

Out Bool

Out Char

Out Int

Out Integer

Out a => Out [a]

Out a => Out (Maybe a)

(Out a, Out b) => Out (Either a b)

(Out a, Out b) => Out (a, b)

(Out a, Out b, Out c) => Out (a, b, c)

(Out a, Out b, Out c, Out d) => Out (a, b, c, d)

(Out a, Out b, Out c, Out d, Out e) => Out (a, b, c, d, e)

(Out a, Out b, Out c, Out d, Out e, Out f) => Out (a, b, c, d, e, f)

(Out a, Out b, Out c, Out d, Out e, Out f, Out g) => Out (a, b, c, d, e, f, g)

(Out a, Out b, Out c, Out d, Out e, Out f, Out g, Out h) => Out (a, b, c, d, e, f, g, h)

(Out a, Out b, Out c, Out d, Out e, Out f, Out g, Out h, Out i) => Out (a, b, c, d, e, f, g, h, i)

(Out a, Out b, Out c, Out d, Out e, Out f, Out g, Out h, Out i, Out j) => Out (a, b, c, d, e, f, g, h, i, j)

(Out a, Out b, Out c, Out d, Out e, Out f, Out g, Out h, Out i, Out j, Out k) => Out (a, b, c, d, e, f, g, h, i, j, k)

(Out a, Out b, Out c, Out d, Out e, Out f, Out g, Out h, Out i, Out j, Out k, Out l) => Out (a, b, c, d, e, f, g, h, i, j, k, l)

(Out a, Out b, Out c, Out d, Out e, Out f, Out g, Out h, Out i, Out j, Out k, Out l, Out m) => Out (a, b, c, d, e, f, g, h, i, j, k, l, m)

(Out a, Out b, Out c, Out d, Out e, Out f, Out g, Out h, Out i, Out j, Out k, Out l, Out m, Out n) => Out (a, b, c, d, e, f, g, h, i, j, k, l, m, n)

(Out a, Out b, Out c, Out d, Out e, Out f, Out g, Out h, Out i, Out j, Out k, Out l, Out m, Out n, Out o) => Out (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)

data Style

A rendering style

Constructors

Style

Fields

mode :: Mode

The rendering mode

lineLength :: Int

Length of line, in chars

ribbonsPerLine :: Float

Ratio of ribbon length to line length

class Generic a

Representable types of kind *. This class is derivable in GHC with the XDeriveRepresentable flag on.

Instances

Generic Bool

Generic Char

Generic Double

Generic Float

Generic Int

Generic ()

Generic [a]

Generic (Maybe a)

Generic (Either a b)

Generic (a, b)

Generic (a, b, c)

Generic (a, b, c, d)

Generic (a, b, c, d, e)

Generic (a, b, c, d, e, f)

Generic (a, b, c, d, e, f, g)