diff --git a/GenericPretty.cabal b/GenericPretty.cabal --- a/GenericPretty.cabal +++ b/GenericPretty.cabal @@ -7,7 +7,7 @@ -- The package version. See the Haskell package versioning policy -- (http://www.haskell.org/haskellwiki/Package_versioning_policy) for -- standards guiding when and how versions should be incremented. -Version: 1.1.5 +Version: 1.1.6 -- A short (one-line) description of the package. Synopsis: A generic, derivable, haskell pretty printer. diff --git a/README b/README --- a/README +++ b/README @@ -55,9 +55,9 @@ The package is installed in the same way as any other package. The steps are: 0. Make sure you have a version of ghc >= 7.2 installed and that you can use the 'runhaskell' command from the command line. - 1. Download and unpack "GenericPretty-1.1.5.tar.gz" + 1. Download and unpack "GenericPretty-1.1.6.tar.gz" 2. Move to the correct directory: - $ cd GenericPretty-1.1.5 + $ cd GenericPretty-1.1.6 3. Run the following haskell commands to install the library globally: $ runhaskell Setup configure $ runhaskell Setup build @@ -253,7 +253,7 @@ examples integrated with QuickCheck can be found in 'TestSuite/Tests.hs'. Further information can be found in the API: - http://hackage.haskell.org/packages/archive/GenericPretty/1.1.4/doc/html/Text-PrettyPrint-GenericPretty.html + http://hackage.haskell.org/packages/archive/GenericPretty/1.1.6/doc/html/Text-PrettyPrint-GenericPretty.html and in the source code itself. =============================================================================== diff --git a/Text/PrettyPrint/GenericPretty.hs b/Text/PrettyPrint/GenericPretty.hs --- a/Text/PrettyPrint/GenericPretty.hs +++ b/Text/PrettyPrint/GenericPretty.hs @@ -1,35 +1,17 @@ {-# LANGUAGE TypeOperators, FlexibleInstances, FlexibleContexts #-} {-| - 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 'Prelude.show', - except it has extra whitespace. - - This requires the use of the new GHC.Generics features: . - 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: . - - There are however several changes between the mechanism - described in the paper and the one implemented in GHC which are described here: - . + GenericPretty is a Haskell library that supports automatic + derivation of pretty printing functions on user defined data + types. - 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 -} + 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 examples of usage please see the README file included in the package +-} module Text.PrettyPrint.GenericPretty(pp, ppLen, ppStyle, pretty, prettyLen, prettyStyle, fullPP, genOut, wrapParens, outputIO, outputStr, @@ -43,13 +25,13 @@ -- | The class 'Out' is the equivalent of 'Prelude.Show' -- --- Conversion of values to pretty printable 'Pretty.Doc's. +-- It provides conversion of values to pretty printable Pretty.Doc's. -- -- Minimal complete definition: 'docPrec' or 'doc'. -- -- Derived instances of 'Out' have the following properties -- --- * The result of 'show' is a syntactically correct Haskell +-- * The result of 'docPrec' 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, @@ -65,7 +47,7 @@ -- 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' +-- * If the constructor is defined using record syntax, then 'docPrec' -- will produce the record-syntax form, with the fields given in the -- same order as the original declaration. -- @@ -93,18 +75,22 @@ -- > parenLen = if(d > appPrec) then 1 else 0 class Out a where - -- | 'docPrec' is the equivalent of 'Prelude.showsPrec' + -- | 'docPrec' is the equivalent of 'Prelude.showsPrec'. + -- -- Convert a value to a pretty printable 'Pretty.Doc'. docPrec :: 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' + -> Doc -- ^ the resulting Doc + -- | 'doc' is the equivalent of 'Prelude.show' - -- A specialised variant of 'docPrec', using precedence context zero. + -- + -- This is a specialised variant of 'docPrec', using precedence context zero. doc :: a -> Doc - -- | 'docList' is the equivalent of 'Prelude.showList' + -- | 'docList' is the equivalent of 'Prelude.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 @@ -116,10 +102,13 @@ docPrec _ = doc docList = docListWith doc --- | 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' +-- | Default generic 'docPrec' 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 Doc's +-- +-- It can 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) @@ -145,9 +134,7 @@ middle [x] = [x] middle (x:xs) = init xs --- |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 +-- |Utility function used to wrap the passed value in parens if the bool is true. wrapParens :: Bool -> [Doc] -> [Doc] wrapParens _ [] = [] wrapParens False s = s @@ -278,12 +265,13 @@ isNullary _ = False -- | 'fullPP' is a fully customizable Pretty Printer +-- -- Every other pretty printer just gives some default values to 'fullPP' -fullPP :: (Out a) => Mode -- ^The 'Pretty' mode to use /(eg: 'Pretty.PageMode')/ +fullPP :: (Out a) => 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)/ + -> 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') )/ -> a -- ^The value to pretty print @@ -294,6 +282,7 @@ doc = docPrec 0 a -- | '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() outputIO td act = do @@ -306,8 +295,9 @@ decode (Chr c) = [c] decode (Str s) = s --- | 'outputStr' just leaves the text as a string, --- usefull is you want to further process the pretty printed result. +-- | 'outputStr' just leaves the text as a string which 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'. outputStr :: TextDetails -> String -> String outputStr td str = decode td ++ str @@ -318,33 +308,39 @@ decode (Chr c) = [c] decode (Str s) = s --- | Customizable pretty printer, takes a user defined 'Style' as a parameter --- uses 'outputStr' to obtain the result +-- | Customizable pretty printer +-- +-- Takes a user defined 'Text.PrettyPrint.MyPretty.Style' as a parameter and uses 'outputStr' to obtain the result prettyStyle :: (Out a) => Style -> a -> String prettyStyle s = fullPP (mode s) (lineLength s) (ribbonsPerLine s) outputStr "" --- | Semi-customizable pretty printer. Takes the lineLength as a parameter --- uses mode = 'Pretty.PageMode' and ribbonsPerLine = 1 +-- | Semi-customizable pretty printer. +-- +-- Takes the lineLength as a parameter and uses mode = Pretty.PageMode and ribbonsPerLine = 1 prettyLen :: (Out a) => Int -> a -> String prettyLen l = fullPP PageMode l 1 outputStr "" -- | The default pretty printer returning 'String's --- uses the default 'MyPretty.Style', 'style' +-- +-- Uses the default 'Text.PrettyPrint.MyPretty.Style', called 'style' pretty :: (Out a) => a -> String pretty = prettyStyle style --- | Customizable pretty printer, takes a user defined 'MyPretty.Style' as a parameter --- uses 'outputIO' to obtain the result +-- | Customizable pretty printer. +-- +-- Takes a user defined 'Text.PrettyPrint.MyPretty.Style' as a parameter and uses 'outputIO' to obtain the result ppStyle :: (Out a) => Style -> a -> IO() ppStyle s = fullPP (mode s) (lineLength s) (ribbonsPerLine s) outputIO (putChar '\n') --- | Semi-customizable pretty printer. Takes the lineLength as a parameter --- uses mode = 'Pretty.PageMode' and ribbonsPerLine = 1 +-- | Semi-customizable pretty printer. +-- +-- Takes the lineLength as a parameter and uses mode = Pretty.PageMode and ribbonsPerLine = 1 ppLen :: (Out a) => Int -> a -> IO() ppLen l = fullPP PageMode l 1 outputIO (putChar '\n') -- | The default Pretty Printer, --- uses the default 'MyPretty.Style', 'style' +-- +-- Uses the default 'Text.PrettyPrint.MyPretty.Style', called 'style' pp :: (Out a) => a -> IO() pp = ppStyle style diff --git a/Text/PrettyPrint/MyPretty.hs b/Text/PrettyPrint/MyPretty.hs --- a/Text/PrettyPrint/MyPretty.hs +++ b/Text/PrettyPrint/MyPretty.hs @@ -1,17 +1,19 @@ {-| 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". + 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. 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". + his types or define a custom printing 'Style'. + The syntax used for defining custom documents 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. -|-} + see the README file and the haskell source files under TestSuite, both included in the package. +-} module Text.PrettyPrint.MyPretty( module Pretty, Style(..), renderStyle, style @@ -27,8 +29,7 @@ , ribbonsPerLine :: Float -- ^ Ratio of ribbon length to line length } --- | Render a document using a particular style --- internally calls 'Pretty.fullRender' +-- | Render a document using a particular style. renderStyle :: Style -> Doc -> String renderStyle s = fullRender (mode s) (lineLength s) (ribbonsPerLine s) outputStr "" where