-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | simple printf-style string formatting -- -- The Text.PercentFormat library provides printf-style string -- formatting. It provides a % operator (as in Ruby or Python) -- and uses the old C-printf-style format you know and love. @package percent-format @version 0.0.2 -- | This file is part of PercentFormat a library for printf-style string -- formatting. -- -- This module provides the Spec type which represents a %... -- specification format. module Text.PercentFormat.Spec data Spec Spec :: SpecType -> Int -> Bool -> Char -> Int -> Maybe Int -> Int -> String -> Bool -> Spec [ty] :: Spec -> SpecType [width] :: Spec -> Int [leftAlign] :: Spec -> Bool [padWith] :: Spec -> Char -- | only for Number types [base] :: Spec -> Int -- | only for Number types, Nothing for infinite [precision] :: Spec -> Maybe Int -- | minimum precision to show [minPrecision] :: Spec -> Int [positivePrefix] :: Spec -> String -- | whether to capitalize (hex) digits [capitalizeDigits] :: Spec -> Bool data SpecType NumberSpec :: SpecType ReprSpec :: SpecType StringSpec :: SpecType CharSpec :: SpecType Percent :: SpecType spec :: Spec parseSpec :: String -> (Spec, String) instance GHC.Show.Show Text.PercentFormat.Spec.SpecType instance GHC.Classes.Eq Text.PercentFormat.Spec.SpecType instance GHC.Show.Show Text.PercentFormat.Spec.Spec instance GHC.Classes.Eq Text.PercentFormat.Spec.Spec -- | This file is part of PercentFormat a library for printf-style string -- formatting. -- -- This module provides miscellaneous utility functions. module Text.PercentFormat.Utils -- | Reads a value encoded as a string, return Just the value or -- Nothing on error. maybeRead :: Read a => String -> Maybe a align :: Bool -> Char -> Int -> String -> String -- | rightAlign c w s aligns String s to the right -- in a field of width w using Char c as -- padding. -- -- 
--   right ' ' 5 "123"
--
-- -- " 123" rightAlign :: Char -> Int -> String -> String -- | left c w s aligns String s to the left in a -- field of width w using Char c as padding. -- -- 
--   left ' ' 5 "123"
--
-- -- "123 " leftAlign :: Char -> Int -> String -> String -- | showWithBase b n returns a string representation of -- n in base b. -- -- 
--   showWithBase 2 10
--
-- -- "1010" > showWithBase 16 49406 "c0f3" > showWithBase 10 (-1234) -- "-1234" showWithBase :: Integral a => Int -> a -> String applyWhen :: Bool -> (a -> a) -> a -> a intsToDigits :: [Int] -> String theLast :: Int -> [a] -> [a] -- | Like cycle, but return an empty list when the source list is empty. loop :: [a] -> [a] none :: (a -> Bool) -> [a] -> Bool -- | Given an integer, returns a list of digits. Signal is ignored. integerToDigits :: Integral a => Int -> a -> [Int] -- | The Quotient datatype. Similar to Rational but allows -- Infinity and NaN. module Text.PercentFormat.Quotient -- | Our own Ratio type that allows Infinity and NaN data Quotient -- | Smart-constructor for Quotients (%) :: Integer -> Integer -> Quotient infixl 7 % -- | Infinity. infinity :: Quotient -- | Not a number (0 / 0). nan :: Quotient -- | Returns whether a given quotient is an infinity (+/-). isInfinite :: Quotient -> Bool -- | Returns if the quotient is not a number. isNaN :: Quotient -> Bool readQ :: String -> Quotient maybeReadQ :: String -> Maybe Quotient -- | Given a quotient (rational number), returns a tuple with its integer -- part, its fractional digits and the period size (last fractional -- digits). The signal is ignored. -- -- 
--   > digits 10 (1234567 / 100)
--   Right ([1,2,3,4,5],[6,7],[])
--   > digits 10 (1/3)
--   Right ([0],[3],1)
--   > digits 10 (1/6)
--   Right ([0],[1,6],1)
--   > digits 10 (1/7)
--   Right ([0],[1,4,2,8,5,7],6)
--   > digits 10 (1/11)
--   Right ([0],[0,9],2)
--   digits 10 (1/12)
--   Right ([0],[0,8,3],1)
--   > digits 10 (1/13)
--   Right ([0],[0,7,6,9,2,3],6)
--   > digits 10 123
--   Right ([1,2,3],[],[])
--   > digits 10 (-4/3)
--   Right ([1],[],[3])
--   > digits 10 (-1/3)
--   Right ([0],[],[3])
--
digits :: Int -> Quotient -> Either String ([Int], [Int], [Int]) -- | Givent a base, returns the fractional digits of a Quotient (including -- a period if present). -- -- 
--   > fracDigits 10 (123 / 100)
--   ([2,3],[])
--   > fracDigits 10 (12345 / 100)
--   ([4,5],[])
--   > fracDigits 10 (12345 / 10)
--   ([5],[])
--   > fracDigits 10 (100 / 10)
--   ([],[])
--   > fracDigits 10 (1 / 3)
--   ([],[3])
--   > fracDigits 10 (1 / 7)
--   ([],[1,4,2,8,5,7])
--
fracDigits :: Int -> Quotient -> ([Int], [Int]) instance GHC.Classes.Eq Text.PercentFormat.Quotient.Quotient instance GHC.Classes.Ord Text.PercentFormat.Quotient.Quotient instance GHC.Show.Show Text.PercentFormat.Quotient.Quotient instance GHC.Num.Num Text.PercentFormat.Quotient.Quotient instance GHC.Real.Fractional Text.PercentFormat.Quotient.Quotient instance GHC.Real.Real Text.PercentFormat.Quotient.Quotient instance GHC.Real.RealFrac Text.PercentFormat.Quotient.Quotient -- | The Text.PercentFormat library provides printf-style string -- formatting. It provides a % operator (as in Ruby or Python) and -- uses the old C-printf-style format you know and love. -- -- This library differs from Text.Printf in that it does not rely -- on custom typeclasses -- it works on anything that is a Show -- instance that produces output in the supported formats. -- -- Formatting one value with -%: -- -- 
--   > "Hello %s!" -% "World"
--   "Hello World!"
--
-- -- Formatting three values, tuple style, with -%%%: -- -- 
--   > "load average: %1.2f %1.2f %1.2f" -%%% (0.00, 0.066, 0.11)
--   "load average: 0.00 0.07 0.11"
--
-- -- Formatting three values, chain style, with % and -%: -- -- 
--   > "load average: %1.2f %1.2f %1.2f" % 0.00 % 0.066 -% 0.11
--   "load average: 0.00 0.07 0.11"
--
-- -- To produce a string with a percent sign (%), use two percent -- signs (%%): -- -- 
--   > "memory usage: %i%%" -% 13
--   "memory usage: 13%"
--
-- -- Percent signs are duplicated when using the % operator to allow -- chaining (further formats): -- -- 
--   > "percent sign: %s, memory usage: %i%%" % "%" % 87
--   "percent sign: %%, memory usage: 87%%"
--
-- -- Always use the -% operator when formatting the last -- value to remove duplicate % signs: -- -- 
--   > "percent sign: %s, memory usage: %i%%" % "%" -% 87
--   "percent sign: %, memory usage: 87%"
--
-- -- To print, just prefix you format expression with "putStrLn -- $": -- -- 
--   > putStrLn $ "Hello %s!" -% "World"
--   Hello World!
--
-- --

Supported formats

-- -- -- -- -- --

Supported flag charaters

-- -- -- -- -- --

How does it work?

-- -- Text.PercentFormat works on values that are Show -- instances producing results in the expected format. Take for example -- the following number type: -- -- 
--   data Digit = Zero | One | Two | Three
--   instance Show Digit where
--     show Zero   =  "0"
--     show One    =  "1"
--     show Two    =  "2"
--     show Three  =  "3"
--
-- -- Text.PercentFormat works fine on it: -- -- 
--   > "%d %i %f %.2f" Zero One Two Three
--   "0 1 2 3.00"
--
-- -- Because when showed, values of this Digit type are -- represented as Integers. -- --

Error Handling

-- -- This library is designed to avoid raising errors. If conversion cannot -- be performed an exclamation mark (!) is produced. If there -- are missing format strings an interrogation mark (?) is -- produced. For example: -- -- 
--   > "%d %d" -% "Ten"
--   "! ?"
--
-- -- The only two instances where errors are raised are: -- --
    --
  1. the argument values contain errors themselves:
    > "Hello
--   %s!" % error "err" *** Exception err
    > error "err" %
--   "World" *** Exception err
    2. --
  2. the format string is not supported:
    > "%j" % 10 ***
--   Exception: unknown format string `j'
    3. --
-- --

Known bugs

-- -- -- -- module Text.PercentFormat -- | Formats a single value into a string without finalizing: leaving -- duplicate percent signs & remaining format sequences. -- -- 
--   > "Hello %s!" % "World"
--   "Hello World!"
--
-- -- 
--   > "processor usage: %d%%" % 67
--   "processor usage: 67%%"
--
-- -- 
--   > "load avg: %.2f %.2f %.2f" % 0.666
--   "load avg: %0.67 %.2f %.2f"
--
-- -- Please use -% when formatting the last value into a string so -- that duplicate percent signs are removed. (%) :: Show a => String -> a -> String infixl 9 % -- | Formats the last value into a string. This finalizes formatting, -- removing duplicate percent signs and replacing remaining format -- sequences with interrogation marks. -- -- 
--   > "Hello %s!" -% "World"
--   "Hello World!"
--
-- -- 
--   > "processor usage: %d%%" -% 67
--   "processor usage: 67%"
--
-- -- 
--   > "load avg: %.2f %.2f %.2f" % 0.666
--   "load avg: %0.67 ? ?"
--
-- -- Please use % if you intend to further format values (chaining). (-%) :: Show a => String -> a -> String infixl 9 -% -- | Replaces "%%" by "%". Any remaining occurrences of format strings are -- replaced by the given error character. Field width is respected when -- possible. -- -- 
--   > "100%% %i" /% '?'
--   "100% ?"
--
-- -- 
--   > "100%% %03i" /% '?'
--   "100% ???"
--
(/%) :: String -> Char -> String -- | Formats two values into a string without finalizing: leaving duplicate -- percent signs & remaining format sequences. -- -- 
--   > "%s %s!" %% ("Hello","World")
--   "Hello World!"
--
-- -- 
--   > "load avg: %.2f %.2f %.2f" %% (0.666,0.333)
--   "load avg: %0.67 %0.33 %.2f"
--
-- -- In general: -- -- 
--   s %% (x,y) == s % x % y
--
-- -- Please use -%% if you don't intend to format values into a -- string any further. (%%) :: (Show a, Show b) => String -> (a, b) -> String -- | Formats three values into a string without finalizing. -- -- 
--   > "load avg: %.2f %.2f %.2f" %%% (0.666,0.333,0.1)
--   "load avg: %0.67 %0.33 %0.10"
--
(%%%) :: (Show a, Show b, Show c) => String -> (a, b, c) -> String -- | Formats four values into a string without finalizing. (%%%%) :: (Show a, Show b, Show c, Show d) => String -> (a, b, c, d) -> String -- | Formats five values into a string without finalizing. (%%%%%) :: (Show a, Show b, Show c, Show d, Show e) => String -> (a, b, c, d, e) -> String -- | Formats six values into a string without finalizing. (%%%%%%) :: (Show a, Show b, Show c, Show d, Show e, Show f) => String -> (a, b, c, d, e, f) -> String -- | Formats two values into a string and finalizes it: removing duplicate -- percent signs & replacing remaining format sequences with -- interrogation marks. -- -- 
--   > "%s %s!" -%% ("Hello","World")
--   "Hello World!"
--
-- -- 
--   > "load avg: %.2f %.2f %.2f" -%% (0.666,0.333)
--   "load avg: %0.67 %0.33 ?"
--
-- -- In general: -- -- 
--   s -%% (x,y) == s % x -% y
--
-- -- Please use %% if you intend to further format values. (-%%) :: (Show a, Show b) => String -> (a, b) -> String -- | Formats three values into a string and finalizes it. -- -- 
--   > "load avg: %.2f %.2f %.2f" -%%% (0.666,0.333,0.1)
--   "load avg: %0.67 %0.33 %0.10"
--
(-%%%) :: (Show a, Show b, Show c) => String -> (a, b, c) -> String -- | Formats four values into a string and finalizes it. (-%%%%) :: (Show a, Show b, Show c, Show d) => String -> (a, b, c, d) -> String -- | Formats five values into a string and finalizes it. (-%%%%%) :: (Show a, Show b, Show c, Show d, Show e) => String -> (a, b, c, d, e) -> String -- | Formats six values into a stirng and finalizes it. (-%%%%%%) :: (Show a, Show b, Show c, Show d, Show e, Show f) => String -> (a, b, c, d, e, f) -> String -- | Just an alias to % for use whenever Data.Ratio is in -- scope. -- -- 
--   import Data.Ratio
--   import Text.PercentFormat hiding ((%))
--   "..." +% 1 -% 2
--
(+%) :: Show a => String -> a -> String