-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Combinator-based type-safe formatting (like printf() or FORMAT)
--
-- Combinator-based type-safe formatting (like printf() or FORMAT),
-- modelled from the HoleyMonoids package.
@package formatting
@version 6.3.4
-- | Types that can be rendered to a Builder.
module Formatting.Buildable
-- | The class of types that can be rendered to a Builder.
class Buildable p
build :: Buildable p => p -> Builder
instance Formatting.Buildable.Buildable Data.Text.Internal.Builder.Builder
instance Formatting.Buildable.Buildable Data.Void.Void
instance Formatting.Buildable.Buildable Data.Text.Internal.Lazy.Text
instance Formatting.Buildable.Buildable Data.Text.Internal.Text
instance Formatting.Buildable.Buildable GHC.Types.Char
instance Formatting.Buildable.Buildable [GHC.Types.Char]
instance GHC.Real.Integral a => Formatting.Buildable.Buildable (Data.Text.Format.Types.Hex a)
instance Formatting.Buildable.Buildable GHC.Int.Int8
instance Formatting.Buildable.Buildable GHC.Int.Int16
instance Formatting.Buildable.Buildable GHC.Int.Int32
instance Formatting.Buildable.Buildable GHC.Types.Int
instance Formatting.Buildable.Buildable GHC.Int.Int64
instance Formatting.Buildable.Buildable GHC.Integer.Type.Integer
instance Data.Fixed.HasResolution a => Formatting.Buildable.Buildable (Data.Fixed.Fixed a)
instance Formatting.Buildable.Buildable GHC.Word.Word8
instance Formatting.Buildable.Buildable GHC.Word.Word16
instance Formatting.Buildable.Buildable GHC.Word.Word32
instance Formatting.Buildable.Buildable GHC.Types.Word
instance Formatting.Buildable.Buildable GHC.Word.Word64
instance (GHC.Real.Integral a, Formatting.Buildable.Buildable a) => Formatting.Buildable.Buildable (GHC.Real.Ratio a)
instance Formatting.Buildable.Buildable GHC.Types.Float
instance Formatting.Buildable.Buildable GHC.Types.Double
instance Formatting.Buildable.Buildable Data.Time.Clock.Internal.DiffTime.DiffTime
instance Formatting.Buildable.Buildable Data.Time.Clock.Internal.NominalDiffTime.NominalDiffTime
instance Formatting.Buildable.Buildable Data.Time.Clock.Internal.UTCTime.UTCTime
instance Formatting.Buildable.Buildable Data.Time.Clock.Internal.UniversalTime.UniversalTime
instance Formatting.Buildable.Buildable Data.Time.Calendar.Days.Day
instance GHC.Show.Show a => Formatting.Buildable.Buildable (Data.Text.Format.Types.Shown a)
instance Formatting.Buildable.Buildable a => Formatting.Buildable.Buildable (GHC.Base.Maybe a)
instance Formatting.Buildable.Buildable Data.Time.LocalTime.Internal.TimeOfDay.TimeOfDay
instance Formatting.Buildable.Buildable Data.Time.LocalTime.Internal.TimeZone.TimeZone
instance Formatting.Buildable.Buildable Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Formatting.Buildable.Buildable Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance Formatting.Buildable.Buildable Foreign.Ptr.IntPtr
instance Formatting.Buildable.Buildable Foreign.Ptr.WordPtr
instance Formatting.Buildable.Buildable (GHC.Ptr.Ptr a)
instance Formatting.Buildable.Buildable GHC.Types.Bool
-- | Internal format starters.
module Formatting.Internal
-- | A formatter. When you construct formatters the first type parameter,
-- r, will remain polymorphic. The second type parameter,
-- a, will change to reflect the types of the data that will be
-- formatted. For example, in
--
--
-- myFormat :: Formatter r (Text -> Int -> r)
-- myFormat = "Person's name is " % text % ", age is " % hex
--
--
-- the first type parameter remains polymorphic, and the second type
-- parameter is Text -> Int -> r, which indicates that it
-- formats a Text and an Int.
--
-- When you run the Format, for example with format, you
-- provide the arguments and they will be formatted into a string.
--
--
-- > format ("Person's name is " % text % ", age is " % hex) "Dave" 54
-- "Person's name is Dave, age is 36"
--
newtype Format r a
Format :: ((Builder -> r) -> a) -> Format r a
[runFormat] :: Format r a -> (Builder -> r) -> a
-- | Not particularly useful, but could be.
-- | Useful instance for applying two formatters to the same input
-- argument. For example: format (year <> "/" % month) now
-- will yield "2015/01".
-- | Useful instance for writing format string. With this you can write
-- Foo instead of now "Foo!".
-- | The same as (%). At present using Category has an import
-- overhead, but one day it might be imported as standard.
-- | Concatenate two formatters.
--
-- formatter1 % formatter2 is a formatter that accepts arguments
-- for formatter1 and formatter2 and concatenates their
-- results. For example
--
--
-- format1 :: Format r (Text -> r)
-- format1 = "Person's name is " % text
--
--
--
-- format2 :: Format r r
-- format2 = ", "
--
--
--
-- format3 :: Format r (Int -> r)
-- format3 = "age is " % hex
--
--
--
-- myFormat :: Formatter r (Text -> Int -> r)
-- myFormat = format1 % format2 % format3
--
--
-- Notice how the argument types of format1 and format3
-- are gathered into the type of myFormat.
--
-- (This is actually the composition operator for Format's
-- Category instance, but that is (at present) inconvenient to use
-- with regular Prelude. So this function is provided as a
-- convenience.)
(%) :: Format r a -> Format r' r -> Format r' a
infixr 9 %
-- | Function compose two formatters. Will feed the result of one formatter
-- into another.
(%.) :: Format r (Builder -> r') -> Format r' a -> Format r a
infixr 8 %.
-- | Don't format any data, just output a constant Builder.
now :: Builder -> Format r r
-- | Monadic indexed bind for holey monoids.
bind :: Format r a -> (Builder -> Format r' r) -> Format r' a
-- | Functorial map over a formatter's input. Example: format (mapf
-- (drop 1) string) "hello"
mapf :: (a -> b) -> Format r (b -> t) -> Format r (a -> t)
-- | Format a value of type a using a function of type a ->
-- Builder. For example, later (f :: Int ->
-- Builder) produces Format r (Int -> r).
later :: (a -> Builder) -> Format r (a -> r)
-- | Run the formatter and return a lazy Text value.
format :: Format Text a -> a
-- | Run the formatter and return a strict Text value.
sformat :: Format Text a -> a
-- | Run the formatter and return a Builder value.
bprint :: Format Builder a -> a
-- | Run the formatter and print out the text to stdout.
fprint :: Format (IO ()) a -> a
-- | Run the formatter and put the output onto the given Handle.
hprint :: Handle -> Format (IO ()) a -> a
-- | Run the formatter and return a list of characters.
formatToString :: Format [Char] a -> a
instance GHC.Base.Functor (Formatting.Internal.Format r)
instance GHC.Base.Monoid (Formatting.Internal.Format r (a -> r))
instance Data.Semigroup.Semigroup (Formatting.Internal.Format r (a -> r))
instance a ~ r => Data.String.IsString (Formatting.Internal.Format r a)
instance Control.Category.Category Formatting.Internal.Format
-- | Formatting functions.
module Formatting.Formatters
-- | Output a lazy text.
text :: Format r (Text -> r)
-- | Output a strict text.
stext :: Format r (Text -> r)
-- | Output a string.
string :: Format r (String -> r)
-- | Output a showable value (instance of Show) by turning it into
-- Text:
--
--
-- >>> format ("Value number " % shown % " is " % shown % ".") 42 False
-- "Value number 42 is False."
--
shown :: Show a => Format r (a -> r)
-- | Output a character.
char :: Format r (Char -> r)
-- | Build a builder.
builder :: Format r (Builder -> r)
-- | Like const but for formatters.
fconst :: Builder -> Format r (a -> r)
-- | Render an integral e.g. 123 -> "123", 0 -> "0".
int :: (Buildable a) => Format r (a -> r)
-- | Render some floating point with the usual notation, e.g. 123.32 =>
-- "123.32"
float :: Real a => Format r (a -> r)
-- | Render a floating point number using normal notation, with the given
-- number of decimal places.
fixed :: Real a => Int -> Format r (a -> r)
-- | Render a scientific number.
sci :: Format r (Scientific -> r)
-- | Render a scientific number with options.
scifmt :: FPFormat -> Maybe Int -> Format r (Scientific -> r)
-- | Render a floating point number using the smallest number of digits
-- that correctly represent it.
shortest :: Real a => Format r (a -> r)
-- | Group integral numbers, e.g. groupInt 2 . on 123456 ->
-- "12.34.56".
groupInt :: (Buildable n, Integral n) => Int -> Char -> Format r (n -> r)
-- | Add commas to an integral, e.g 12000 -> "12,000".
commas :: (Buildable n, Integral n) => Format r (n -> r)
-- | Add a suffix to an integral, e.g. 1st, 2nd, 3rd, 21st.
ords :: Integral n => Format r (n -> r)
-- | English plural suffix for an integral.
plural :: (Num a, Eq a) => Text -> Text -> Format r (a -> r)
-- | Shows the Int value of Enum instances using fromEnum.
--
--
-- >>> format ("Got: " % char % " (" % asInt % ")") 'a' 'a'
-- "Got: a (97)"
--
asInt :: Enum a => Format r (a -> r)
-- | Pad the left hand side of a string until it reaches k characters wide,
-- if necessary filling with character c.
left :: Buildable a => Int -> Char -> Format r (a -> r)
-- | Pad the right hand side of a string until it reaches k characters
-- wide, if necessary filling with character c.
right :: Buildable a => Int -> Char -> Format r (a -> r)
-- | Pad the left & right hand side of a string until it reaches k
-- characters wide, if necessary filling with character c.
center :: Buildable a => Int -> Char -> Format r (a -> r)
-- | Fit in the given length, truncating on the left.
fitLeft :: Buildable a => Int -> Format r (a -> r)
-- | Fit in the given length, truncating on the right.
fitRight :: Buildable a => Int -> Format r (a -> r)
-- | Render an integral at base n.
base :: Integral a => Int -> Format r (a -> r)
-- | Render an integer using binary notation. (No leading 0b is added.)
-- Defined as bin = base 2.
bin :: Integral a => Format r (a -> r)
-- | Render an integer using octal notation. (No leading 0o is added.)
-- Defined as oct = base 8.
oct :: Integral a => Format r (a -> r)
-- | Render an integer using hexadecimal notation. (No leading 0x is
-- added.) Has a specialized implementation.
hex :: Integral a => Format r (a -> r)
-- | Render an integer using binary notation with a leading 0b.
prefixBin :: Integral a => Format r (a -> r)
-- | Render an integer using octal notation with a leading 0o.
prefixOct :: Integral a => Format r (a -> r)
-- | Render an integer using hexadecimal notation with a leading 0x.
prefixHex :: Integral a => Format r (a -> r)
-- | Renders a given byte count using an appropiate decimal binary suffix:
--
--
-- >>> format (bytes shortest) 1024
-- "1KB"
--
--
--
-- >>> format (bytes (fixed 2 % " ")) (1024*1024*5)
-- "5.00 MB"
--
bytes :: (Ord f, Integral a, Fractional f) => Format Builder (f -> Builder) -> Format r (a -> r)
-- | Build anything that implements the Buildable class.
build :: Buildable a => Format r (a -> r)
-- | The class of types that can be rendered to a Builder.
class Buildable p
-- | Combinator-based type-safe formatting (like printf() or FORMAT) for
-- Text.
--
-- Example:
--
--
-- >>> format ("Person's name is " % text % ", age is " % hex) "Dave" 54
--
--
-- See Formatting.Formatters for a complete list of formatting
-- combinators.
module Formatting
-- | A formatter. When you construct formatters the first type parameter,
-- r, will remain polymorphic. The second type parameter,
-- a, will change to reflect the types of the data that will be
-- formatted. For example, in
--
--
-- myFormat :: Formatter r (Text -> Int -> r)
-- myFormat = "Person's name is " % text % ", age is " % hex
--
--
-- the first type parameter remains polymorphic, and the second type
-- parameter is Text -> Int -> r, which indicates that it
-- formats a Text and an Int.
--
-- When you run the Format, for example with format, you
-- provide the arguments and they will be formatted into a string.
--
--
-- > format ("Person's name is " % text % ", age is " % hex) "Dave" 54
-- "Person's name is Dave, age is 36"
--
data Format r a
-- | Concatenate two formatters.
--
-- formatter1 % formatter2 is a formatter that accepts arguments
-- for formatter1 and formatter2 and concatenates their
-- results. For example
--
--
-- format1 :: Format r (Text -> r)
-- format1 = "Person's name is " % text
--
--
--
-- format2 :: Format r r
-- format2 = ", "
--
--
--
-- format3 :: Format r (Int -> r)
-- format3 = "age is " % hex
--
--
--
-- myFormat :: Formatter r (Text -> Int -> r)
-- myFormat = format1 % format2 % format3
--
--
-- Notice how the argument types of format1 and format3
-- are gathered into the type of myFormat.
--
-- (This is actually the composition operator for Format's
-- Category instance, but that is (at present) inconvenient to use
-- with regular Prelude. So this function is provided as a
-- convenience.)
(%) :: Format r a -> Format r' r -> Format r' a
infixr 9 %
-- | Function compose two formatters. Will feed the result of one formatter
-- into another.
(%.) :: Format r (Builder -> r') -> Format r' a -> Format r a
infixr 8 %.
-- | Don't format any data, just output a constant Builder.
now :: Builder -> Format r r
-- | Format a value of type a using a function of type a ->
-- Builder. For example, later (f :: Int ->
-- Builder) produces Format r (Int -> r).
later :: (a -> Builder) -> Format r (a -> r)
-- | Functorial map over a formatter's input. Example: format (mapf
-- (drop 1) string) "hello"
mapf :: (a -> b) -> Format r (b -> t) -> Format r (a -> t)
runFormat :: Format r a -> (Builder -> r) -> a
-- | Run the formatter and return a lazy Text value.
format :: Format Text a -> a
-- | Run the formatter and return a strict Text value.
sformat :: Format Text a -> a
-- | Run the formatter and return a Builder value.
bprint :: Format Builder a -> a
-- | Run the formatter and print out the text to stdout.
fprint :: Format (IO ()) a -> a
-- | Run the formatter and put the output onto the given Handle.
hprint :: Handle -> Format (IO ()) a -> a
-- | Run the formatter and return a list of characters.
formatToString :: Format [Char] a -> a
-- | Examples that should always compile. If reading on Haddock, you can
-- view the sources to each of these.
module Formatting.Examples
-- | Simple hello, world!
hello :: Text
-- | Printing strings.
strings :: Text
-- | Printing texts.
texts :: Text
-- | Printing builders.
builders :: Text
-- | Printing integers.
integers :: Text
-- | Printing floating points.
floats :: Text
-- | Printing integrals in hex (base-16).
hexes :: Text
-- | Padding.
padding :: Text
-- | Formatters for high-res, real-time and timer clock values from
-- System.Clock.
module Formatting.Clock
-- | Same as durationNS but works on TimeSpec from the
-- clock package.
timeSpecs :: Format r (TimeSpec -> TimeSpec -> r)
-- | Reexports of things that were previously in the text-format
-- package.
module Formatting.Internal.Raw
-- | Pad the left hand side of a string until it reaches k
-- characters wide, if necessary filling with character c.
left :: Buildable a => Int -> Char -> a -> Builder
-- | Pad the right hand side of a string until it reaches k
-- characters wide, if necessary filling with character c.
right :: Buildable a => Int -> Char -> a -> Builder
-- | Render an integer using hexadecimal notation. (No leading "0x" is
-- added.)
hex :: Integral a => a -> Builder
-- | Render a floating point number using normal notation, with the given
-- number of decimal places.
fixed :: (Real a) => Int -> a -> Builder
-- | Render a floating point number using the smallest number of digits
-- that correctly represent it.
shortest :: (Real a) => a -> Builder
-- | The normal mappend function with right associativity instead of
-- left.
(<>) :: Builder -> Builder -> Builder
infixr 4 <>
-- | Unsafe conversion for decimal digits.
i2d :: Int -> Char
decimal :: (Integral a, Bounded a) => a -> Builder
integer :: Int -> Integer -> Builder
hexadecimal :: Integral a => a -> Builder
minus :: Builder
-- | Render a value using its Show instance.
newtype Shown a
Shown :: a -> Shown a
[shown] :: Shown a -> a
-- | Render an integral type in hexadecimal.
newtype Hex a
Hex :: a -> Hex a
-- | Single letters for short formatting.
module Formatting.ShortFormatters
-- | Output a lazy text.
t :: Format r (Text -> r)
-- | Render an integral e.g. 123 -> "123", 0 -> "0".
d :: (Buildable a) => Format r (a -> r)
-- | Render an integer using binary notation. (No leading 0b is added.)
b :: Integral a => Format r (a -> r)
-- | Render an integer using octal notation. (No leading 0o is added.)
o :: Integral a => Format r (a -> r)
-- | Render an integer using hexadecimal notation. (No leading 0x is
-- added.)
x :: Integral a => Format r (a -> r)
-- | Output a strict text.
st :: Format r (Text -> r)
-- | Output a string.
s :: Format r (String -> r)
-- | Output a showable value (instance of Show) by turning it into
-- Text.
sh :: Show a => Format r (a -> r)
-- | Output a character.
c :: Format r (Char -> r)
-- | Render a floating point number using normal notation, with the given
-- number of decimal places.
f :: Real a => Int -> Format r (a -> r)
-- | Render a floating point number using the smallest number of digits
-- that correctly represent it.
sf :: Real a => Format r (a -> r)
-- | Pad the left hand side of a string until it reaches k
-- characters wide, if necessary filling with character ch.
l :: Buildable a => Int -> Char -> Format r (a -> r)
-- | Pad the right hand side of a string until it reaches k
-- characters wide, if necessary filling with character ch.
r :: Buildable a => Int -> Char -> Format r (a -> r)
-- | Formatters for time.
module Formatting.Time
-- | Timezone offset on the format -HHMM.
tz :: FormatTime a => Format r (a -> r)
-- | Timezone name.
tzName :: FormatTime a => Format r (a -> r)
-- | As dateTimeFmt locale (e.g. %a %b %e %H:%M:%S %Z
-- %Y).
datetime :: FormatTime a => Format r (a -> r)
-- | Same as %H:%M.
hm :: FormatTime a => Format r (a -> r)
-- | Same as %H:%M:%S.
hms :: FormatTime a => Format r (a -> r)
-- | As timeFmt locale (e.g. %H:%M:%S).
hmsL :: FormatTime a => Format r (a -> r)
-- | As time12Fmt locale (e.g. %I:%M:%S %p).
hmsPL :: FormatTime a => Format r (a -> r)
-- | Day half from (amPm locale), converted to lowercase,
-- am, pm.
dayHalf :: FormatTime a => Format r (a -> r)
-- | Day half from (amPm locale), AM, PM.
dayHalfU :: FormatTime a => Format r (a -> r)
-- | Hour, 24-hour, leading 0 as needed, 00 - 23.
hour24 :: FormatTime a => Format r (a -> r)
-- | Hour, 12-hour, leading 0 as needed, 01 - 12.
hour12 :: FormatTime a => Format r (a -> r)
-- | Hour, 24-hour, leading space as needed, 0 - 23.
hour24S :: FormatTime a => Format r (a -> r)
-- | Hour, 12-hour, leading space as needed, 1 - 12.
hour12S :: FormatTime a => Format r (a -> r)
-- | Minute, 00 - 59.
minute :: FormatTime a => Format r (a -> r)
-- | Second, without decimal part, 00 - 60.
second :: FormatTime a => Format r (a -> r)
-- | Picosecond, including trailing zeros, 000000000000 -
-- 999999999999.
pico :: FormatTime a => Format r (a -> r)
-- | Decimal point and up to 12 second decimals, without trailing zeros.
-- For a whole number of seconds, this produces the empty string.
decimals :: FormatTime a => Format r (a -> r)
epoch :: FormatTime a => Format r (a -> r)
-- | Same as %m/%d/%y.
dateSlash :: FormatTime a => Format r (a -> r)
-- | Same as %Y-%m-%d.
dateDash :: FormatTime a => Format r (a -> r)
-- | As dateFmt locale (e.g. %m/%d/%y).
dateSlashL :: FormatTime a => Format r (a -> r)
-- | Year.
year :: FormatTime a => Format r (a -> r)
-- | Last two digits of year, 00 - 99.
yy :: FormatTime a => Format r (a -> r)
-- | Century (being the first two digits of the year), 00 -
-- 99.
century :: FormatTime a => Format r (a -> r)
-- | Month name, long form (fst from months locale),
-- January - December.
monthName :: FormatTime a => Format r (a -> r)
-- | %H] month name, short form (snd from months
-- locale), Jan - Dec@.
monthNameShort :: FormatTime a => Format r (a -> r)
-- | Month of year, leading 0 as needed, 01 - 12.
month :: FormatTime a => Format r (a -> r)
-- | Day of month, leading 0 as needed, 01 - 31.
dayOfMonth :: FormatTime a => Format r (a -> r)
-- | Day of month, 1st, 2nd, 25th, etc.
dayOfMonthOrd :: FormatTime a => Format r (a -> r)
-- | Day of month, leading space as needed, 1 - 31.
dayOfMonthS :: FormatTime a => Format r (a -> r)
-- | Day of year for Ordinal Date format, 001 - 366.
day :: FormatTime a => Format r (a -> r)
-- | Year for Week Date format e.g. 2013.
weekYear :: FormatTime a => Format r (a -> r)
-- | Last two digits of year for Week Date format, 00 -
-- 99.
weekYY :: FormatTime a => Format r (a -> r)
-- | Century (first two digits of year) for Week Date format, 00 -
-- 99.
weekCentury :: FormatTime a => Format r (a -> r)
-- | Week for Week Date format, 01 - 53.
week :: FormatTime a => Format r (a -> r)
-- | Day for Week Date format, 1 - 7.
dayOfWeek :: FormatTime a => Format r (a -> r)
-- | Day of week, short form (snd from wDays
-- locale), Sun - Sat.
dayNameShort :: FormatTime a => Format r (a -> r)
-- | Day of week, long form (fst from wDays locale),
-- Sunday - Saturday.
dayName :: FormatTime a => Format r (a -> r)
-- | Week number of year, where weeks start on Sunday (as
-- sundayStartWeek), 00 - 53.
weekFromZero :: FormatTime a => Format r (a -> r)
-- | Day of week number, 0 (= Sunday) - 6 (= Saturday).
dayOfWeekFromZero :: FormatTime a => Format r (a -> r)
-- | Week number of year, where weeks start on Monday (as
-- mondayStartWeek), 00 - 53.
weekOfYearMon :: FormatTime a => Format r (a -> r)
-- | Display a time span as one time relative to another. Input is assumed
-- to be seconds. Typical inputs are NominalDiffTime and
-- DiffTime.
diff :: (RealFrac n) => Bool -> Format r (n -> r)
-- | Display the absolute value time span in years.
years :: (RealFrac n) => Int -> Format r (n -> r)
-- | Display the absolute value time span in days.
days :: (RealFrac n) => Int -> Format r (n -> r)
-- | Display the absolute value time span in hours.
hours :: (RealFrac n) => Int -> Format r (n -> r)
-- | Display the absolute value time span in minutes.
minutes :: (RealFrac n) => Int -> Format r (n -> r)
-- | Display the absolute value time span in seconds.
seconds :: (RealFrac n) => Int -> Format r (n -> r)
-- | Formatter call. Probably don't want to use this.
fmt :: FormatTime a => Text -> a -> Text
-- | Helper for creating custom time formatters
customTimeFmt :: FormatTime a => Text -> Format r (a -> r)