Permalink
Browse files

Update docs.

  • Loading branch information...
1 parent 323e311 commit b4dca8315ebc6b2ea738a3b8e79e3b41a46018ca @bos committed May 20, 2011
View
@@ -1,5 +1,16 @@
{-# 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(..)
@@ -21,6 +32,7 @@ import Data.Word (Word, Word8, Word16, Word32, Word64)
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
View
@@ -1,28 +1,46 @@
{-# 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 as ST
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
@@ -32,19 +50,27 @@ build fmt ps = zipParams (map fromText . ST.splitOn "{}" $ fmt) xs
(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
@@ -1,5 +1,16 @@
{-# 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
(
(<>)
@@ -15,6 +26,8 @@ import GHC.Base
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 (<>) #-}
View
@@ -1,13 +1,13 @@
{-# 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
(
View
@@ -1,3 +1,14 @@
+-- |
+-- 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(..)
@@ -7,6 +18,8 @@ import Data.Text.Buildable
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]
@@ -22,7 +35,8 @@ instance (Buildable a, Buildable b) => Params (a,b) where
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]
@@ -31,34 +45,36 @@ instance (Buildable a, Buildable b, Buildable c, Buildable d, Buildable e)
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,
@@ -4,6 +4,8 @@
-- 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
(
View
@@ -1,5 +1,16 @@
{-# 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(..)
@@ -8,18 +19,34 @@ module Data.Text.Format.Types
, 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,

0 comments on commit b4dca83

Please sign in to comment.