Commits

Bryan O'Sullivan committed 445c2d0

Update docs.

  • Participants
  • Parent commits 954a4f4
  • Tags 0.1.0.0

Comments (0)

Files changed (7)

File Data/Text/Buildable.hs

 {-# LANGUAGE FlexibleInstances #-}
 
+-- |
+-- Module      : Data.Text.Buildable
+-- Copyright   : (c) 2011 MailRank, Inc.
+--
+-- License     : BSD-style
+-- Maintainer  : bos@mailrank.com
+-- Stability   : experimental
+-- Portability : GHC
+--
+-- Types that can be rendered to a 'Builder'.
+
 module Data.Text.Buildable
     (
       Buildable(..)
 import qualified Data.Text as ST
 import qualified Data.Text.Lazy as LT
 
+-- | The class of types that can be rendered to a 'Builder'.
 class Buildable p where
     build :: p -> Builder
 

File Data/Text/Format.hs

 {-# LANGUAGE OverloadedStrings #-}
 
+-- |
+-- Module      : Data.Text.Format
+-- Copyright   : (c) 2011 MailRank, Inc.
+--
+-- License     : BSD-style
+-- Maintainer  : bos@mailrank.com
+-- Stability   : experimental
+-- Portability : GHC
+--
+-- Fast, efficient, flexible support for formatting text strings.
+
 module Data.Text.Format
     (
-      Fast(..)
-    , Only(..)
+    -- * Types
+      Only(..)
+    -- ** Types for format control
+    , Fast(..)
+    , Shown(..)
+    -- * Functions
+    -- ** Rendering
     , format
-    , build
     , print
     , hprint
+    , build
+    -- ** Functions for format control
     , left
     , right
     ) where
 import qualified Data.Text.Buildable as B
 import Data.Text.Format.Params (Params(..))
 import Data.Text.Format.Functions ((<>))
-import Data.Text.Format.Types (Fast(..), Only(..))
+import Data.Text.Format.Types (Fast(..), Only(..), Shown(..))
 import Data.Text.Lazy.Builder
 import Prelude hiding (print)
 import System.IO (Handle)
 import qualified Data.Text.Lazy as LT
 import qualified Data.Text.Lazy.IO as LT
 
+-- | Render a format string and arguments to a 'Builder'.
 build :: Params ps => ST.Text -> ps -> Builder
 build fmt ps = zipParams (map fromText . ST.splitOn "{}" $ fmt) xs
   where zipParams (f:fs) (y:ys) = f <> y <> zipParams fs ys
                         (ST.count "{}" fmt, length xs)
         xs = buildParams ps
 
+-- | Render a format string and arguments to a 'LT.Text'.
 format :: Params ps => ST.Text -> ps -> LT.Text
 format fmt ps = toLazyText $ build fmt ps
 
+-- | Render a format string and arguments, then print the result.
 print :: Params ps => ST.Text -> ps -> IO ()
 print fmt ps = LT.putStr . toLazyText $ build fmt ps
 
+-- | Render a format string and arguments, then print the result to
+-- the given file handle.
 hprint :: Params ps => Handle -> ST.Text -> ps -> IO ()
 hprint h fmt ps = LT.hPutStr h . toLazyText $ build fmt ps
 
+-- | Pad the left hand side of a string until it reaches @k@
+-- characters wide, filling with character @c@.
 left :: B.Buildable a => Int -> Char -> a -> Builder
 left k c =
     fromLazyText . LT.justifyLeft (fromIntegral k) c . toLazyText . B.build
 
+-- | Pad the right hand side of a string until it reaches @k@
+-- characters wide, filling with character @c@.
 right :: B.Buildable a => Int -> Char -> a -> Builder
 right k c =
     fromLazyText . LT.justifyRight (fromIntegral k) c . toLazyText . B.build

File Data/Text/Format/Functions.hs

 {-# LANGUAGE MagicHash #-}
 
+-- |
+-- Module      : Data.Text.Format.Functions
+-- Copyright   : (c) 2011 MailRank, Inc.
+--
+-- License     : BSD-style
+-- Maintainer  : bos@mailrank.com
+-- Stability   : experimental
+-- Portability : GHC
+--
+-- Useful functions and combinators.
+
 module Data.Text.Format.Functions
     (
       (<>)
 i2d :: Int -> Char
 i2d (I# i#) = C# (chr# (ord# '0'# +# i#))
 
+-- | The normal 'mappend' function with right associativity instead of
+-- left.
 (<>) :: Builder -> Builder -> Builder
 (<>) = mappend
 {-# INLINE (<>) #-}

File Data/Text/Format/Int.hs

 {-# LANGUAGE BangPatterns, CPP, MagicHash, UnboxedTuples #-}
 
--- Module:      Blaze.Text.Int
+-- Module:      Data.Text.Format.Int
 -- Copyright:   (c) 2011 MailRank, Inc.
 -- License:     BSD3
 -- Maintainer:  Bryan O'Sullivan <bos@mailrank.com>
 -- Stability:   experimental
 -- Portability: portable
 --
--- Efficiently serialize an integral value as a lazy 'L.ByteString'.
+-- Efficiently serialize an integral value to a 'Builder'.
 
 module Data.Text.Format.Int
     (

File Data/Text/Format/Params.hs

+-- |
+-- Module      : Data.Text.Format.Params
+-- Copyright   : (c) 2011 MailRank, Inc.
+--
+-- License     : BSD-style
+-- Maintainer  : bos@mailrank.com
+-- Stability   : experimental
+-- Portability : GHC
+--
+-- Types that can be used as a collection of arguments for formatting.
+
 module Data.Text.Format.Params
     (
       Params(..)
 import Data.Text.Format.Types
 import Data.Text.Lazy.Builder
 
+-- | The class of types that can be used as a collection of arguments
+-- for formatting.
 class Params ps where
     buildParams :: ps -> [Builder]
 
 instance (Buildable a, Buildable b, Buildable c) => Params (a,b,c) where
     buildParams (a,b,c) = [build a, build b, build c]
 
-instance (Buildable a, Buildable b, Buildable c, Buildable d) => Params (a,b,c,d) where
+instance (Buildable a, Buildable b, Buildable c, Buildable d)
+    => Params (a,b,c,d) where
     buildParams (a,b,c,d) =
         [build a, build b, build c, build d]
 
     buildParams (a,b,c,d,e) =
         [build a, build b, build c, build d, build e]
 
-instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e, Buildable f)
+instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e,
+          Buildable f)
     => Params (a,b,c,d,e,f) where
     buildParams (a,b,c,d,e,f) =
         [build a, build b, build c, build d, build e,
          build f]
 
-instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e, Buildable f, Buildable g)
+instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e,
+          Buildable f, Buildable g)
     => Params (a,b,c,d,e,f,g) where
     buildParams (a,b,c,d,e,f,g) =
         [build a, build b, build c, build d, build e,
          build f, build g]
 
-instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e, Buildable f, Buildable g,
-          Buildable h)
+instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e,
+          Buildable f, Buildable g, Buildable h)
     => Params (a,b,c,d,e,f,g,h) where
     buildParams (a,b,c,d,e,f,g,h) =
         [build a, build b, build c, build d, build e,
          build f, build g, build h]
 
-instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e, Buildable f, Buildable g,
-          Buildable h, Buildable i)
+instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e,
+          Buildable f, Buildable g, Buildable h, Buildable i)
     => Params (a,b,c,d,e,f,g,h,i) where
     buildParams (a,b,c,d,e,f,g,h,i) =
         [build a, build b, build c, build d, build e,
          build f, build g, build h, build i]
 
-instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e, Buildable f, Buildable g,
-          Buildable h, Buildable i, Buildable j)
+instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e,
+          Buildable f, Buildable g, Buildable h, Buildable i, Buildable j)
     => Params (a,b,c,d,e,f,g,h,i,j) where
     buildParams (a,b,c,d,e,f,g,h,i,j) =
         [build a, build b, build c, build d, build e,

File Data/Text/Format/RealFloat.hs

 -- Module:    Data.Text.Format.RealFloat
 -- Copyright: (c) The University of Glasgow 1994-2002
 -- License:   see libraries/base/LICENSE
+--
+-- Serialize a floating point value to a 'Builder'.
 
 module Data.Text.Format.RealFloat
     (

File Data/Text/Format/Types.hs

 {-# LANGUAGE GeneralizedNewtypeDeriving #-}
 
+-- |
+-- Module      : Data.Text.Format.Types
+-- Copyright   : (c) 2011 MailRank, Inc.
+--
+-- License     : BSD-style
+-- Maintainer  : bos@mailrank.com
+-- Stability   : experimental
+-- Portability : GHC
+--
+-- Types for text mangling.
+
 module Data.Text.Format.Types
     (
       Format(..)
     , Shown(..)
     ) where
 
-data Format = Exponent | Fixed | Generic
+-- | Control the rendering of floating point numbers.
+data Format = Exponent
+              -- ^ Scientific notation (e.g. @2.3e123@).
+            | Fixed
+              -- ^ Standard decimal notation.
+            | Generic
+              -- ^ Use decimal notation for values between @0.1@ and
+              -- @9,999,999@, and scientific notation otherwise.
+            deriving (Enum, Read, Show)
 
+-- | Render a floating point number using a much faster algorithm than
+-- the default (up to 10x faster). This performance comes with a
+-- potential cost in readability, as the faster algorithm can produce
+-- strings that are longer than the default algorithm
+-- (e.g. \"@1.3300000000000001@\" instead of \"@1.33@\").
 newtype Fast a = Fast {
       fromFast :: a
     } deriving (Eq, Show, Read, Ord, Num, Fractional, Real, RealFrac,
                 Floating, RealFloat)
 
+-- | Use this @newtype@ wrapper for your single parameter if you are
+-- formatting a string containing exactly one substitution site.
 newtype Only a = Only {
       fromOnly :: a
     } deriving (Eq, Show, Read, Ord, Num, Fractional, Real, RealFrac,
                 Floating, RealFloat, Enum, Integral, Bounded)
 
+-- | Render a value using its 'Show' instance.
 newtype Shown a = Shown {
       shown :: a
     } deriving (Eq, Show, Read, Ord, Num, Fractional, Real, RealFrac,