packages feed

GenericPretty 1.1.5 → 1.1.6

raw patch · 4 files changed

+68/−71 lines, 4 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

GenericPretty.cabal view
@@ -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.
README view
@@ -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.
 
 ===============================================================================
Text/PrettyPrint/GenericPretty.hs view
@@ -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: <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>.
+  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
Text/PrettyPrint/MyPretty.hs view
@@ -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(<http://www.haskell.org/ghc/docs/7.0.4/html/libraries/ghc-7.0.4/Pretty.html>)
+    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