-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A generic, derivable, haskell pretty printer.
--
-- GenericPretty is a Haskell library that supports automatic derivation
-- of pretty printing functions on user defined data types.
--
-- The form of geenrics used is based on that introduced in the paper:
-- Magalhaes, Dijkstra, Jeuring, and Loh, A Generic Deriving Mechanism
-- for Haskell, 3'rd ACM Symposium on Haskell, pp. 37-48, September 2010,
-- http://dx.doi.org/10.1145/1863523.1863529. Changes from the
-- original paper in the GHC implementation are described here:
-- http://www.haskell.org/haskellwiki/Generics#Changes_from_the_paper.
--
-- This package requires the use of the new GHC.Generics features
-- http://www.haskell.org/haskellwiki/Generics, present from GHC
-- 7.2. Use of these features is indicated by the DeriveGeneric pragma.
-- or the flag -XDeriveGeneric.
--
-- Pretty printing produces values of type Pretty.Doc, using the Pretty
-- library
-- http://www.haskell.org/ghc/docs/7.0.4/html/libraries/ghc-7.0.4/Pretty.html.
--
-- The Pretty library plans to incorporate a Style datatype to control
-- details of printing (such as line length). The library MyPretty is
-- provided as a thin wrapper around the Pretty library, to support Style
-- related features. Once the Pretty library supports Style, MyPretty
-- will become obsolete and be replaced by Pretty.
--
-- The output provided is a pretty printed version of that provided by
-- Prelude.show. That is, rendering the document provided by this pretty
-- printer yields an output identical to that of Prelude.show, except for
-- extra whitespace.
--
-- For information about the functions exported by the package please see
-- the API linked further down this page. For examples of usage, both
-- basic and more complex see the README file and the haskell source code
-- files in the TestSuite folder, both included in the package. Finally
-- for installation instructions also see the README file or this page:
-- http://www.haskell.org/haskellwiki/Cabal/How_to_install_a_Cabal_package
@package GenericPretty
@version 1.1.5
-- | MyPretty is a library that can be used in conjuncture with
-- Text.PrettyPrint.GenericPretty.
--
-- This library is a thin wrapper around the Pretty library and
-- implements only Style related features. These features are
-- planned to be added to the Pretty library itself. When that happens
-- MyPretty will become obsolete and will be replaced by
-- Pretty.
--
-- This library can be imported if the user wants to make custom pretty
-- printing definitions for his types or define a custom printing Style.
-- The syntax used is that of Pretty and
-- Text.PrettyPrint.HughesPJ.
--
-- For an example of a custom definition for a data type and usage of a
-- custom Style see the README file included in the package. |
module Text.PrettyPrint.MyPretty
-- | A rendering style
data Style
Style :: Mode -> Int -> Float -> Style
-- | The rendering mode
mode :: Style -> Mode
-- | Length of line, in chars
lineLength :: Style -> Int
-- | Ratio of ribbon length to line length
ribbonsPerLine :: Style -> Float
-- | Render a document using a particular style internally calls
-- fullRender
renderStyle :: Style -> Doc -> String
-- | The default Style used for
-- Text.PrettyPrint.GenericPretty (mode=PageMode, lineLength=80,
-- ribbonsPerLine=1.5)
style :: Style
-- | 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
-- Pretty.Doc types.
--
-- The library MyPretty is also provided. This library is a thin
-- wrapper around the Pretty library and implements only
-- MyPretty.Style related features. These features are planned
-- to be added to the Pretty library itself. When that happens
-- MyPretty will become obsolete and will be replaced by
-- Pretty.
--
-- 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. These features are
-- present in versions of GHC >= 7.2.
--
-- The Generics used are based on those described in the paper A
-- Generic Deriving Mechanism for Haskell - by Magalhaes, Dijkstra,
-- Jeuring and Loh in Proceedings of the third ACM Haskell symposium on
-- Haskell (Haskell'2010), pp. 37-48, ACM, 2010:
-- 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.
--
-- This generics mechanism supports deriving for all haskell datatypes
-- EXCEPT for constrained datatypes. That is to say, datatypes which have
-- a context will fail. For instance, data (Eq a) => Constr a =
-- Constr a will fail because of the (Eq a) context.
--
-- For examples of usage please see the README file included in the
-- package
module Text.PrettyPrint.GenericPretty
-- | The default Pretty Printer, uses the default MyPretty.Style,
-- style
pp :: Out a => a -> IO ()
-- | Semi-customizable pretty printer. Takes the lineLength as a parameter
-- uses mode = Pretty.PageMode and ribbonsPerLine = 1
ppLen :: Out a => Int -> a -> IO ()
-- | Customizable pretty printer, takes a user defined
-- MyPretty.Style as a parameter uses outputIO to obtain
-- the result
ppStyle :: Out a => Style -> a -> IO ()
-- | The default pretty printer returning Strings uses the default
-- MyPretty.Style, style
pretty :: Out a => a -> String
-- | Semi-customizable pretty printer. Takes the lineLength as a parameter
-- uses mode = Pretty.PageMode and ribbonsPerLine = 1
prettyLen :: Out a => Int -> a -> String
-- | Customizable pretty printer, takes a user defined Style as a
-- parameter uses outputStr to obtain the result
prettyStyle :: Out a => Style -> a -> String
-- | fullPP is a fully customizable Pretty Printer Every other
-- pretty printer just gives some default values to fullPP
fullPP :: Out a => Mode -> Int -> Float -> (TextDetails -> b -> b) -> b -> a -> b
-- | 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 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 pretty printing function like
-- pp and pretty on data of type Tree
genOut :: (Generic a, GOut (Rep a)) => Int -> a -> 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
wrapParens :: Bool -> [Doc] -> [Doc]
-- | 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.
outputIO :: TextDetails -> IO () -> IO ()
-- | outputStr just leaves the text as a string, usefull is you want
-- to further process the pretty printed result. This is another example
-- of a function that can handle the text conversion for fullPP.
outputStr :: TextDetails -> String -> String
-- | The class Out is the equivalent of Show
--
-- Conversion of values to pretty printable Pretty.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
--
class Out a
docPrec :: Out a => Int -> a -> Doc
doc :: Out a => a -> Doc
docList :: Out a => [a] -> Doc
-- | Representable types of kind *. This class is derivable in GHC with the
-- XDeriveRepresentable flag on.
class Generic a
instance (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)
instance (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)
instance (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)
instance (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)
instance (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)
instance (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)
instance (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)
instance (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)
instance (Out a, Out b, Out c, Out d, Out e, Out f, Out g) => Out (a, b, c, d, e, f, g)
instance (Out a, Out b, Out c, Out d, Out e, Out f) => Out (a, b, c, d, e, f)
instance (Out a, Out b, Out c, Out d, Out e) => Out (a, b, c, d, e)
instance (Out a, Out b, Out c, Out d) => Out (a, b, c, d)
instance (Out a, Out b, Out c) => Out (a, b, c)
instance (Out a, Out b) => Out (a, b)
instance (Out a, Out b) => Out (Either a b)
instance Out a => Out (Maybe a)
instance Out Int
instance Out Bool
instance Out a => Out [a]
instance Out Integer
instance Out Char
instance (GOut f, GOut g) => GOut (f :*: g)
instance (GOut f, GOut g) => GOut (f :+: g)
instance Out f => GOut (K1 t f)
instance (GOut f, Constructor c) => GOut (M1 C c f)
instance (GOut f, Selector c) => GOut (M1 S c f)
instance (GOut f, Datatype c) => GOut (M1 D c f)
instance GOut U1