-- 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.
--   
--   See the README at
--   <a>https://github.com/AJChapman/formatting#readme</a> for more info.
@package formatting
@version 7.2.0


-- | Types that can be rendered to a <a>Builder</a>.
module Formatting.Buildable

-- | The class of types that can be rendered to a <a>Builder</a>.
class Buildable p
build :: Buildable p => p -> Builder
instance Formatting.Buildable.Buildable Data.Text.Internal.Builder.Builder
instance Formatting.Buildable.Buildable GHC.Base.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.Num.Integer.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 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.Maybe.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
instance Formatting.Buildable.Buildable a => Formatting.Buildable.Buildable [a]


-- | Internal format starters.
module Formatting.Internal

-- | A formatter. When you construct formatters the first type parameter,
--   <tt>r</tt>, will remain polymorphic. The second type parameter,
--   <tt>a</tt>, will change to reflect the types of the data that will be
--   formatted. For example, in
--   
--   <pre>
--   myFormat :: Format r (Text -&gt; Int -&gt; r)
--   myFormat = "Person's name is " % text % ", age is " % hex
--   </pre>
--   
--   the first type parameter remains polymorphic, and the second type
--   parameter is <tt>Text -&gt; Int -&gt; r</tt>, which indicates that it
--   formats a <a>Text</a> and an <a>Int</a>.
--   
--   When you run the <a>Format</a>, for example with <a>format</a>, you
--   provide the arguments and they will be formatted into a string.
--   
--   <pre>
--   &gt; format ("Person's name is " % text % ", age is " % hex) "Dave" 54
--   "Person's name is Dave, age is 36"
--   </pre>
newtype Format r a
Format :: ((Builder -> r) -> a) -> Format r a
[runFormat] :: Format r a -> (Builder -> r) -> a

-- | Concatenate two formatters.
--   
--   <tt>formatter1 % formatter2</tt> is a formatter that accepts arguments
--   for <tt>formatter1</tt> and <tt>formatter2</tt> and concatenates their
--   results. For example
--   
--   <pre>
--   format1 :: Format r (Text -&gt; r)
--   format1 = "Person's name is " % text
--   </pre>
--   
--   <pre>
--   format2 :: Format r r
--   format2 = ", "
--   </pre>
--   
--   <pre>
--   format3 :: Format r (Int -&gt; r)
--   format3 = "age is " % hex
--   </pre>
--   
--   <pre>
--   myFormat :: Format r (Text -&gt; Int -&gt; r)
--   myFormat = format1 % format2 % format3
--   </pre>
--   
--   Notice how the argument types of <tt>format1</tt> and <tt>format3</tt>
--   are gathered into the type of <tt>myFormat</tt>.
--   
--   (This is actually the composition operator for <a>Format</a>s
--   <a>Category</a> instance, but that is (at present) inconvenient to use
--   with regular <a>Prelude</a>. So this function is provided as a
--   convenience.)
(%) :: Format r a -> Format r' r -> Format r' a
infixr 9 %

-- | Concatenate two formatters with a space in between.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; format (int %+ "+" %+ int %+ "=" %+ int) 2 3 5
--   "2 + 3 = 5"
--   </pre>
(%+) :: 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 %.

-- | Like <tt>(&lt;&gt;)</tt> except put a space between the two
--   formatters. For example: <tt>format (year <a>%+</a> month <a>%+</a>
--   dayOfMonth) now</tt> will yield <tt>"2022 06 06"</tt>
(<%+>) :: Format r (a -> r) -> Format r (a -> r) -> Format r (a -> r)

-- | Don't format any data, just output a constant <a>Builder</a>.
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: <tt>format (mapf
--   (drop 1) string) "hello"</tt>
mapf :: (a -> b) -> Format r (b -> t) -> Format r (a -> t)

-- | Format a value of type <tt>a</tt> using a function of type <tt>a -&gt;
--   <a>Builder</a></tt>. For example, <tt>later (f :: Int -&gt;
--   Builder)</tt> produces <tt>Format r (Int -&gt; r)</tt>.
later :: (a -> Builder) -> Format r (a -> r)

-- | Run the formatter and return a lazy <a>Text</a> value.
format :: Format Text a -> a

-- | Run the formatter and return a strict <a>Text</a> value.
sformat :: Format Text a -> a

-- | Run the formatter and return a <a>Builder</a> value.
bprint :: Format Builder a -> a

-- | Run the formatter and return a <a>Builder</a> value.
--   
--   This is a newer synonym for <a>bprint</a>, following the naming
--   convention set by <a>format</a> and <a>sformat</a>.
bformat :: Format Builder a -> a

-- | Run the formatter and print out the text to stdout.
fprint :: MonadIO m => Format (m ()) a -> a

-- | Run the formatter and print out the text to stdout, followed by a
--   newline.
fprintLn :: MonadIO m => Format (m ()) a -> a

-- | Run the formatter and put the output onto the given <a>Handle</a>.
hprint :: MonadIO m => Handle -> Format (m ()) a -> a

-- | Run the formatter and put the output and a newline onto the given
--   <a>Handle</a>.
hprintLn :: MonadIO m => Handle -> Format (m ()) a -> a

-- | Run the formatter and return a list of characters.
formatToString :: Format String a -> a
instance GHC.Base.Functor (Formatting.Internal.Format r)
instance GHC.Base.Semigroup (Formatting.Internal.Format r (a -> r))
instance GHC.Base.Monoid (Formatting.Internal.Format r (a -> r))
instance (a GHC.Types.~ r) => Data.String.IsString (Formatting.Internal.Format r a)
instance Control.Category.Category Formatting.Internal.Format

module Formatting.FromBuilder

-- | Anything that can be created from a <a>Builder</a>. This class makes
--   it easier to add formatting to other API's. See <a>formatted</a> for
--   some examples of this class in action.
class FromBuilder a
fromBuilder :: FromBuilder a => Builder -> a

-- | Makes it easy to add formatting to any api that is expecting a
--   builder, a strict or lazy text, or a string. It is essentially (flip
--   runFormat), but with a more generous type due to the typeclass.
--   
--   For example: &gt;&gt;&gt; formatted TL.putStr ("x is: " % int % "n") 7
--   x is: 7 &gt;&gt;&gt; formatted T.putStr ("x is: " % int % "n") 7 x is:
--   7 &gt;&gt;&gt; formatted (id <tt>TL.Text) ("x is: " % int % "n") 7 "x
--   is: 7n" &gt;&gt;&gt; formatted (id </tt>T.Text) ("x is: " % int % "n")
--   7 "x is: 7n"
formatted :: FromBuilder t => (t -> o) -> Format o a -> a
instance Formatting.FromBuilder.FromBuilder Data.Text.Internal.Builder.Builder
instance Formatting.FromBuilder.FromBuilder Data.Text.Internal.Lazy.Text
instance Formatting.FromBuilder.FromBuilder Data.Text.Internal.Text
instance Formatting.FromBuilder.FromBuilder [GHC.Types.Char]


-- | 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 <a>Show</a>) by turning it into
--   <a>Text</a>:
--   
--   <pre>
--   &gt;&gt;&gt; format ("Value number " % shown % " is " % shown % ".") 42 False
--   "Value number 42 is False."
--   </pre>
shown :: Show a => Format r (a -> r)

-- | Output a character.
char :: Format r (Char -> r)

-- | Build a builder.
builder :: Format r (Builder -> r)

-- | Like <a>const</a> but for formatters.
fconst :: Builder -> Format r (a -> r)

-- | Render an integral e.g. 123 -&gt; "123", 0 -&gt; "0".
int :: Integral a => Format r (a -> r)

-- | Render some floating point with the usual notation, e.g. 123.32 =&gt;
--   "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. Note that in the case of whole numbers it
--   will still add one decimal place, e.g. "1.0".
shortest :: Real a => Format r (a -> r)

-- | Group integral numbers, e.g. groupInt 2 <a>.</a> on 123456 -&gt;
--   "12.34.56".
groupInt :: (Buildable n, Integral n) => Int -> Char -> Format r (n -> r)

-- | Add commas to an integral, e.g 12000 -&gt; "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.
--   
--   For example:
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; formatPeople = format (int % " " &lt;&gt; plural "person" "people" % ".") :: Int -&gt; Data.Text.Lazy.Text
--   
--   &gt;&gt;&gt; formatPeople 1
--   "1 person."
--   
--   &gt;&gt;&gt; formatPeople 3
--   "3 people."
--   </pre>
plural :: (Num a, Eq a) => Text -> Text -> Format r (a -> r)

-- | Shows the Int value of Enum instances using <a>fromEnum</a>.
--   
--   <pre>
--   &gt;&gt;&gt; format ("Got: " % char % " (" % asInt % ")") 'a' 'a'
--   "Got: a (97)"
--   </pre>
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 &amp; 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 <tt>bin = <a>base</a> 2</tt>.
bin :: Integral a => Format r (a -> r)

-- | Render an integer using octal notation. (No leading 0o is added.)
--   Defined as <tt>oct = <a>base</a> 8</tt>.
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.
--   
--   See also <a>binPrefix</a> for fixed-width formatting.
prefixBin :: Integral a => Format r (a -> r)

-- | Render an integer using octal notation with a leading 0o.
--   
--   See also <a>octPrefix</a> for fixed-width formatting.
prefixOct :: Integral a => Format r (a -> r)

-- | Render an integer using hexadecimal notation with a leading 0x.
--   
--   See also <a>hexPrefix</a> for fixed-width formatting.
prefixHex :: Integral a => Format r (a -> r)

-- | Renders a given byte count using an appropiate decimal binary suffix:
--   
--   <pre>
--   &gt;&gt;&gt; format (bytes shortest) 1024
--   "1KB"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (bytes (fixed 2 % " ")) (1024*1024*5)
--   "5.00 MB"
--   </pre>
bytes :: (Ord f, Integral a, Fractional f) => Format Builder (f -> Builder) -> Format r (a -> r)

-- | Build anything that implements the <a>Buildable</a> class.
build :: Buildable a => Format r (a -> r)

-- | The class of types that can be rendered to a <a>Builder</a>.
class Buildable p


-- | A formatting combinator takes a Format and returns another Format.
--   Generally we want to change what the original format takes as its
--   *input*, leaving the output polymorphic. Many of these combinators can
--   be chained together to form a single <a>Format</a>.
--   
--   Implementation detail: in order to be able to chain multiple
--   combinators to make a single <a>Format</a> we need them all to use the
--   same intermediate string type, and we have chosen <a>Builder</a>. This
--   does not tie you to using <a>Builder</a>s, because the final output
--   string type <tt>r</tt> is still polymorphic.
module Formatting.Combinators

-- | Render a Maybe value either as a default (if Nothing) or using the
--   given formatter:
--   
--   <pre>
--   &gt;&gt;&gt; format (maybed "Goodbye" text) Nothing
--   "Goodbye"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (maybed "Goodbye" text) (Just "Hello")
--   "Hello"
--   </pre>
maybed :: Builder -> Format Builder (a -> Builder) -> Format r (Maybe a -> r)

-- | Render the value in a Maybe using the given formatter, or produce an
--   empty string:
--   
--   <pre>
--   &gt;&gt;&gt; format (optioned text) Nothing
--   ""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (optioned text) (Just "Hello")
--   "Hello"
--   </pre>
optioned :: Format Builder (a -> Builder) -> Format r (Maybe a -> r)

-- | Render the value in an Either:
--   
--   <pre>
--   &gt;&gt;&gt; format (eithered text int) (Left "Error!")
--   "Error!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (eithered text int) (Right 69)
--   "69"
--   </pre>
eithered :: Format Builder (a -> Builder) -> Format Builder (b -> Builder) -> Format r (Either a b -> r)

-- | Render the value in a Left with the given formatter, rendering a Right
--   as an empty string:
--   
--   <pre>
--   &gt;&gt;&gt; format (lefted text) (Left "bingo")
--   "bingo"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (lefted text) (Right 16)
--   ""
--   </pre>
lefted :: Format Builder (a -> Builder) -> Format r (Either a x -> r)

-- | Render the value in a Right with the given formatter, rendering a Left
--   as an empty string:
--   
--   <pre>
--   &gt;&gt;&gt; format (righted text) (Left 16)
--   ""
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (righted text) (Right "bingo")
--   "bingo"
--   </pre>
righted :: Format Builder (a -> Builder) -> Format r (Either x a -> r)

-- | Format each value in a list and concatenate them all:
--   
--   <pre>
--   &gt;&gt;&gt; format (concatenated text) ["one", "two", "three"]
--   "onetwothree"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (took 15 (concatenated bin)) [1..]
--   "1101110010111011110001001101010111100110111101111"
--   </pre>
concatenated :: Foldable t => Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Use the given text-joining function to join together the individually
--   rendered items of a list.
--   
--   <pre>
--   &gt;&gt;&gt; format (joinedWith (mconcat . reverse) int) [123, 456, 789]
--   "789456123"
--   </pre>
joinedWith :: Foldable t => ([Text] -> Text) -> Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Format each value in a list and place the given string between each:
--   
--   <pre>
--   &gt;&gt;&gt; fprintLn (intercalated "||" int) [1, 2, 3]
--   1||2||3
--   </pre>
intercalated :: Foldable t => Text -> Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Format each value in a list with spaces in between:
--   
--   <pre>
--   &gt;&gt;&gt; format (unworded int) [1, 2, 3]
--   "1 2 3"
--   </pre>
unworded :: Foldable t => Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Format each value in a list, placing each on its own line:
--   
--   <pre>
--   &gt;&gt;&gt; fprint (unlined char) ['a'..'c']
--   a
--   b
--   c
--   </pre>
unlined :: Foldable t => Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Separate the formatted items of the Foldable (e.g. list) with spaces:
--   
--   <pre>
--   &gt;&gt;&gt; format (spaced int) [1, 2, 3]
--   "1 2 3"
--   </pre>
--   
--   Note that this behaviour is identical to <a>unworded</a>, it's just a
--   different way of thinking about it.
spaced :: Foldable t => Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Separate the formatted items of the Foldable (e.g. list) with commas:
--   
--   <pre>
--   &gt;&gt;&gt; format (commaSep stext) ["one", "two", "three", "four", "five"]
--   "one,two,three,four,five"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (took 5 (commaSep int)) [1..]
--   "1,2,3,4,5"
--   </pre>
commaSep :: Foldable t => Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Separate the formatted items of the Foldable (e.g. list) with commas
--   and spaces:
--   
--   <pre>
--   &gt;&gt;&gt; format (took 3 (commaSpaceSep ords)) [1..]
--   "1st, 2nd, 3rd"
--   </pre>
commaSpaceSep :: Foldable t => Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Add square brackets around the Foldable (e.g. a list), and separate
--   each formatted item with a comma and space.
--   
--   <pre>
--   &gt;&gt;&gt; format (list stext) ["one", "two", "three"]
--   "[one, two, three]"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (list shown) ["one", "two", "three"]
--   "[\"one\", \"two\", \"three\"]"
--   </pre>
list :: Foldable t => Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Like <a>list</a>, but also put double quotes around each rendered
--   item:
--   
--   <pre>
--   &gt;&gt;&gt; fprintLn (qlist stext) ["one", "two", "three"]
--   ["one", "two", "three"]
--   </pre>
qlist :: Foldable t => Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Take only the first n items from the list of items.
--   
--   <pre>
--   &gt;&gt;&gt; format (took 7 (list bin)) [1..]
--   "[1, 10, 11, 100, 101, 110, 111]"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (list bin) (take 7 [1..])
--   "[1, 10, 11, 100, 101, 110, 111]"
--   </pre>
took :: Int -> Format r ([a] -> r) -> Format r ([a] -> r)

-- | Drop the first n items from the list of items.
--   
--   <pre>
--   &gt;&gt;&gt; format (dropped 3 (list int)) [1..6]
--   "[4, 5, 6]"
--   </pre>
dropped :: Int -> Format r ([a] -> r) -> Format r ([a] -> r)

-- | Split the formatted item in places the given predicated matches, and
--   use the given list combinator to render the resultant list of strings
--   (this function was sent to us from a parallel universe in which splat
--   is the past participle of split, e.g. "whoops, I splat my pants").
--   
--   <pre>
--   &gt;&gt;&gt; format (splat Data.Char.isSpace commaSpaceSep stext) "This\t  is\n\t\t  poorly formatted   "
--   "This, , , is, , , , , poorly, formatted, , , "
--   </pre>
splat :: (Char -> Bool) -> (Format r' (Builder -> r') -> Format Builder ([Builder] -> Builder)) -> Format r a -> Format r a

-- | Utility for taking a text-splitting function and turning it into a
--   formatting combinator.
--   
--   <pre>
--   &gt;&gt;&gt; format (splatWith (TL.chunksOf 3) list int) 1234567890
--   "[123, 456, 789, 0]"
--   </pre>
splatWith :: (Text -> [Text]) -> (Format r' (Builder -> r') -> Format Builder ([Builder] -> Builder)) -> Format r a -> Format r a

-- | Split the formatted item at instances of the given string, and use the
--   given list combinator to render the resultant list of strings.
--   
--   <pre>
--   &gt;&gt;&gt; fprint (splatOn "," unlined text) "one,two,three"
--   one
--   two
--   three
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fprint (splatOn "," (indentedLines 4) text) "one,two,three"
--       one
--       two
--       three
--   </pre>
splatOn :: Text -> (Format r' (Builder -> r') -> Format Builder ([Builder] -> Builder)) -> Format r a -> Format r a

-- | Split the formatted item into words and use the given list combinator
--   to render the resultant list of strings.
--   
--   <pre>
--   &gt;&gt;&gt; format (worded list text) "one  two three  "
--   "[one, two, three]"
--   </pre>
worded :: (Format r' (Builder -> r') -> Format Builder ([Builder] -> Builder)) -> Format r a -> Format r a

-- | Split the formatted item into lines and use the given list combinator
--   to render the resultant list of strings.
--   
--   <pre>
--   &gt;&gt;&gt; fprintLn (lined qlist text) "one two three\n\nfour five six\nseven eight nine\n\n"
--   ["one two three", "", "four five six", "seven eight nine", ""]
--   </pre>
lined :: (Format Builder (Builder -> Builder) -> Format Builder ([Builder] -> Builder)) -> Format r a -> Format r a

-- | Alter the formatted string with the given function.
--   
--   <pre>
--   &gt;&gt;&gt; format (alteredWith Data.Text.Lazy.reverse int) 123456
--   "654321"
--   </pre>
alteredWith :: (Text -> Text) -> Format r a -> Format r a

-- | Filter the formatted string to contain only characters which pass the
--   given predicate:
--   
--   <pre>
--   &gt;&gt;&gt; format (charsKeptIf Data.Char.isUpper text) "Data.Char.isUpper"
--   "DCU"
--   </pre>
charsKeptIf :: (Char -> Bool) -> Format r a -> Format r a

-- | Filter the formatted string to not contain characters which pass the
--   given predicate:
--   
--   <pre>
--   &gt;&gt;&gt; format (charsRemovedIf Data.Char.isUpper text) "Data.Char.isUpper"
--   "ata.har.ispper"
--   </pre>
charsRemovedIf :: (Char -> Bool) -> Format r a -> Format r a

-- | Take a formatter and replace the given needle with the given
--   replacement in its output.
--   
--   <pre>
--   &gt;&gt;&gt; format (replaced "Bruce" "&lt;redacted&gt;" stext) "Bruce replied that Bruce's name was, in fact, '&lt;redacted&gt;'."
--   "&lt;redacted&gt; replied that &lt;redacted&gt;'s name was, in fact, '&lt;redacted&gt;'."
--   </pre>
replaced :: Text -> Text -> Format r a -> Format r a

-- | Convert any letters in the output of the given formatter to
--   upper-case.
--   
--   <pre>
--   &gt;&gt;&gt; format (uppercased text) "I'm not shouting, you're shouting."
--   "I'M NOT SHOUTING, YOU'RE SHOUTING."
--   </pre>
uppercased :: Format r a -> Format r a

-- | Convert any letters in the output of the given formatter to
--   lower-case.
--   
--   <pre>
--   &gt;&gt;&gt; format (lowercased text) "Cd SrC/; Rm -Rf *"
--   "cd src/; rm -rf *"
--   </pre>
lowercased :: Format r a -> Format r a

-- | Convert the formatted string to title case, or something like it:
--   
--   <pre>
--   &gt;&gt;&gt; format (titlecased string) "the life of brian"
--   "The Life Of Brian"
--   </pre>
titlecased :: Format r a -> Format r a

-- | Truncate the formatted string at the end so that it is no more than
--   the given number of characters in length, placing an ellipsis at the
--   end such that it does not exceed this length.
--   
--   <pre>
--   &gt;&gt;&gt; format (ltruncated 5 text) "hello"
--   "hello"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (ltruncated 5 text) "hellos"
--   "he..."
--   </pre>
ltruncated :: Int64 -> Format r a -> Format r a

-- | Truncate the formatted string in the center, leaving the given number
--   of characters at the start and end, and placing an ellipsis in
--   between. The length will be no longer than `start + end + 3`
--   characters long.
--   
--   <pre>
--   &gt;&gt;&gt; format (ctruncated 15 4 text) "The quick brown fox jumps over the lazy dog."
--   "The quick brown...dog."
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (ctruncated 15 4 text) "The quick brown fox"
--   "The quick brown fox"
--   </pre>
ctruncated :: Int64 -> Int64 -> Format r a -> Format r a

-- | Truncate the formatted string at the start so that it is no more than
--   the given number of characters in length, placing an ellipsis at the
--   start such that it does not exceed this length.
--   
--   <pre>
--   &gt;&gt;&gt; format (rtruncated 5 text) "hello"
--   "hello"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (rtruncated 5 text) "hellos"
--   "...os"
--   </pre>
rtruncated :: Int64 -> Format r a -> Format r a

-- | Pad the formatted string on the left with the given character to give
--   it the given minimum width:
--   
--   <pre>
--   &gt;&gt;&gt; format (lpadded 7 ' ' int) 1
--   "      1"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (lpadded 7 ' ' int) 123456789
--   "123456789"
--   </pre>
lpadded :: Int64 -> Char -> Format r (a -> r) -> Format r (a -> r)

-- | Pad the formatted string on the right with the given character to give
--   it the given minimum width:
--   
--   <pre>
--   &gt;&gt;&gt; format (rpadded 7 ' ' int) 1
--   "1      "
--   </pre>
rpadded :: Int64 -> Char -> Format r (a -> r) -> Format r (a -> r)

-- | Pad the formatted string on the left and right with the given
--   character to center it, giving it the given minimum width:
--   
--   <pre>
--   &gt;&gt;&gt; format (cpadded 7 ' ' int) 1
--   "   1   "
--   </pre>
cpadded :: Int64 -> Char -> Format r (a -> r) -> Format r (a -> r)

-- | Format the item with a fixed width, padding with the given character
--   on the left to extend, adding an ellipsis on the right to shorten:
--   
--   <pre>
--   &gt;&gt;&gt; format (lfixed 10 ' ' int) 123
--   "123       "
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (lfixed 10 ' ' int) 1234567890
--   "1234567890"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (lfixed 10 ' ' int) 123456789012345
--   "1234567..."
--   </pre>
lfixed :: Int64 -> Char -> Format r (a -> r) -> Format r (a -> r)

-- | Format the item with a fixed width, padding with the given character
--   on the right to extend, adding an ellipsis on the right to shorten:
--   
--   <pre>
--   &gt;&gt;&gt; format (rfixed 10 ' ' int) 123
--   "       123"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (rfixed 10 ' ' int) 1234567890
--   "1234567890"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (rfixed 10 ' ' int) 123456789012345
--   "...9012345"
--   </pre>
rfixed :: Int64 -> Char -> Format r (a -> r) -> Format r (a -> r)

-- | Format the item with a fixed width, padding with the given character
--   on either side to extend, adding an ellipsis in the center to shorten.
--   
--   The total length will be `l + r + 3` characters.
--   
--   <pre>
--   &gt;&gt;&gt; format (cfixed 4 3 ' ' int) 123
--   "    123   "
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (cfixed 4 3 ' ' int) 1234567890
--   "1234567890"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (cfixed 4 3 ' ' int) 123456789012345
--   "1234...345"
--   </pre>
cfixed :: Int64 -> Int64 -> Char -> Format r (a -> r) -> Format r (a -> r)

-- | Add the given prefix to the formatted item:
--   
--   <pre>
--   &gt;&gt;&gt; format ("The answer is: " % prefixed "wait for it... " int) 42
--   "The answer is: wait for it... 42"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fprint (unlined (indented 4 (prefixed "- " int))) [1, 2, 3]
--       - 1
--       - 2
--       - 3
--   </pre>
prefixed :: Builder -> Format r a -> Format r a

-- | Add the given suffix to the formatted item.
suffixed :: Builder -> Format r a -> Format r a

-- | Surround the output string with the given string:
--   
--   <pre>
--   &gt;&gt;&gt; format (surrounded "***" string) "glue"
--   "***glue***"
--   </pre>
surrounded :: Builder -> Format r a -> Format r a

-- | Enclose the output string with the given strings:
--   
--   <pre>
--   &gt;&gt;&gt; format (enclosed "&lt;!--" "--&gt;" text) "an html comment"
--   "&lt;!--an html comment--&gt;"
--   </pre>
enclosed :: Builder -> Builder -> Format r a -> Format r a

-- | Add single quotes around the formatted item:
--   
--   <pre>
--   &gt;&gt;&gt; let obj = Just Nothing in format ("The object is: " % squoted shown % ".") obj
--   "The object is: 'Just Nothing'."
--   </pre>
squoted :: Format r a -> Format r a

-- | Add double quotes around the formatted item:
--   
--   <pre>
--   &gt;&gt;&gt; fprintLn ("He said it was based on " % dquoted stext % ".") "science"
--   He said it was based on "science".
--   </pre>
dquoted :: Format r a -> Format r a

-- | Add parentheses around the formatted item:
--   
--   <pre>
--   &gt;&gt;&gt; format ("We found " % parenthesised int % " discrepancies.") 17
--   "We found (17) discrepancies."
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fprintLn (took 5 (list (parenthesised int))) [1..]
--   [(1), (2), (3), (4), (5)]
--   </pre>
parenthesised :: Format r a -> Format r a

-- | Add square brackets around the formatted item:
--   
--   <pre>
--   &gt;&gt;&gt; format (squared int) 7
--   "[7]"
--   </pre>
squared :: Format r a -> Format r a

-- | Add curly brackets around the formatted item:
--   
--   <pre>
--   &gt;&gt;&gt; format ("\\begin" % braced text) "section"
--   "\\begin{section}"
--   </pre>
braced :: Format r a -> Format r a

-- | Add angle brackets around the formatted item:
--   
--   <pre>
--   &gt;&gt;&gt; format (angled int) 7
--   "&lt;7&gt;"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (list (angled text)) ["html", "head", "title", "body", "div", "span"]
--   "[&lt;html&gt;, &lt;head&gt;, &lt;title&gt;, &lt;body&gt;, &lt;div&gt;, &lt;span&gt;]"
--   </pre>
angled :: Format r a -> Format r a

-- | Add backticks around the formatted item:
--   
--   <pre>
--   &gt;&gt;&gt; format ("Be sure to run " % backticked builder % " as root.") ":(){:|:&amp;};:"
--   "Be sure to run `:(){:|:&amp;};:` as root."
--   </pre>
backticked :: Format r a -> Format r a

-- | Insert the given number of spaces at the start of the rendered text:
--   
--   <pre>
--   &gt;&gt;&gt; format (indented 4 int) 7
--   "    7"
--   </pre>
--   
--   Note that this only indents the first line of a multi-line string. To
--   indent all lines see <a>reindented</a>.
indented :: Int -> Format r a -> Format r a

-- | Format a list of items, placing one per line, indented by the given
--   number of spaces.
--   
--   <pre>
--   &gt;&gt;&gt; fprint ("The lucky numbers are:\n" % indentedLines 4 int) [7, 13, 1, 42]
--   The lucky numbers are:
--       7
--       13
--       1
--       42
--   </pre>
indentedLines :: Foldable t => Int -> Format Builder (a -> Builder) -> Format r (t a -> r)

-- | Indent each line of the formatted string by the given number of
--   spaces:
--   
--   <pre>
--   &gt;&gt;&gt; fprint (reindented 2 text) "one\ntwo\nthree"
--     one
--     two
--     three
--   </pre>
reindented :: Int -> Format r a -> Format r a

-- | Take a fractional number and round it before formatting it as the
--   given Format:
--   
--   <pre>
--   &gt;&gt;&gt; format (roundedTo int) 6.66
--   "7"
--   
--   &gt;&gt;&gt; format (list (roundedTo int)) [10.66, 6.66, 1.0, 3.4]
--   "[11, 7, 1, 3]"
--   </pre>
--   
--   Note: the type variable <tt>f</tt> will almost always be 'Format r',
--   so the type of this function can be thought of as:
--   
--   <pre>
--   roundedTo :: (Integral i, RealFrac d) =&gt; Format r (i -&gt; r) -&gt; Format r (d -&gt; r)
--   </pre>
roundedTo :: (Integral i, RealFrac d, Functor f) => f (i -> r) -> f (d -> r)

-- | Take a fractional number and truncate it before formatting it as the
--   given Format:
--   
--   <pre>
--   &gt;&gt;&gt; format (truncatedTo int) 6.66
--   "6"
--   
--   &gt;&gt;&gt; format (list (truncatedTo int)) [10.66, 6.66, 1.0, 3.4]
--   "[10, 6, 1, 3]"
--   </pre>
--   
--   Note: the type variable <tt>f</tt> will almost always be 'Format r',
--   so the type of this function can be thought of as:
--   
--   <pre>
--   truncatedTo :: (Integral i, RealFrac d) =&gt; Format r (i -&gt; r) -&gt; Format r (d -&gt; r)
--   </pre>
truncatedTo :: (Integral i, RealFrac d, Functor f) => f (i -> r) -> f (d -> r)

-- | Take a fractional number and ceiling it before formatting it as the
--   given Format:
--   
--   <pre>
--   &gt;&gt;&gt; format (ceilingedTo int) 6.66
--   "7"
--   
--   &gt;&gt;&gt; format (list (ceilingedTo int)) [10.66, 6.66, 1.0, 3.4]
--   "[11, 7, 1, 4]"
--   </pre>
--   
--   Note: the type variable <tt>f</tt> will almost always be 'Format r',
--   so the type of this function can be thought of as:
--   
--   <pre>
--   ceilingedTo :: (Integral i, RealFrac d) =&gt; Format r (i -&gt; r) -&gt; Format r (d -&gt; r)
--   </pre>
ceilingedTo :: (Integral i, RealFrac d, Functor f) => f (i -> r) -> f (d -> r)

-- | Take a fractional number and floor it before formatting it as the
--   given Format:
--   
--   <pre>
--   &gt;&gt;&gt; format (flooredTo int) 6.66
--   "6"
--   
--   &gt;&gt;&gt; format (list (flooredTo int)) [10.66, 6.66, 1.0, 3.4]
--   "[10, 6, 1, 3]"
--   </pre>
--   
--   Note: the type variable <tt>f</tt> will almost always be 'Format r',
--   so the type of this function can be thought of as:
--   
--   <pre>
--   flooredTo :: (Integral i, RealFrac d) =&gt; Format r (i -&gt; r) -&gt; Format r (d -&gt; r)
--   </pre>
flooredTo :: (Integral i, RealFrac d, Functor f) => f (i -> r) -> f (d -> r)

-- | Use the given lens to view an item, formatting it with the given
--   formatter.
--   
--   You can think of this as having the type:
--   
--   <pre>
--   <a>viewed</a> :: <tt>Lens'</tt> s a -&gt; Format r (a -&gt; r) -&gt; Format r (s -&gt; r)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; format (viewed _1 int) (1, "hello")
--   "1"
--   </pre>
--   
--   This is useful when combined with the Monoid instance for Format,
--   because it allows us to give a data structure as an argument only
--   once, and deconstruct it with the formatters:
--   
--   <pre>
--   data Person = Person
--     { _personName :: Text
--     , _personAge :: Int
--     }
--   makeLenses ''Person
--   
--   me :: Person
--   me = Person <a>Alex</a> 38
--   
--   format ("The person's name is " % squoted (viewed personName text) % ", and their age is " &lt;&gt; viewed personAge int) me
--   "The person's name is <tt>Alex</tt>, and their age is 38"
--   </pre>
viewed :: ((a -> Const a b) -> s -> Const a t) -> Format r (a -> r) -> Format r (s -> r)

-- | Access an element of the structure and format it with the given
--   formatter.
--   
--   <pre>
--   &gt;&gt;&gt; format (accessed fst int) (1, "hello")
--   "1"
--   </pre>
--   
--   Repeating the example from <a>viewed</a>:
--   
--   format ("The person's name is " % squoted (accessed _personName text)
--   % ", and their age is " &lt;&gt; accessed _personAge int) me "The
--   person's name is <tt>Alex</tt>, and their age is 38"
accessed :: (s -> a) -> Format r (a -> r) -> Format r (s -> r)

-- | Render an integer using binary notation with a leading 0b, padding
--   with zeroes to the given width:
--   
--   <pre>
--   &gt;&gt;&gt; format (binPrefix 16) 4097
--   "0b0001000000000001"
--   </pre>
binPrefix :: Integral a => Int64 -> Format r (a -> r)

-- | Render an integer using octal notation with a leading 0o, padding with
--   zeroes to the given width:
--   
--   <pre>
--   &gt;&gt;&gt; format (octPrefix 16) 4097
--   "0o0000000000010001"
--   </pre>
octPrefix :: Integral a => Int64 -> Format r (a -> r)

-- | Render an integer using octal notation with a leading 0x, padding with
--   zeroes to the given width:
--   
--   <pre>
--   &gt;&gt;&gt; format (hexPrefix 16) 4097
--   "0x0000000000001001"
--   </pre>
hexPrefix :: Integral a => Int64 -> Format r (a -> r)


-- | Combinator-based type-safe formatting (like printf() or FORMAT) for
--   Text.
--   
--   Example:
--   
--   <pre>
--   &gt;&gt;&gt; format ("Person's name is " % text % ", age is " % hex) "Dave" 54
--   "Person's name is Dave, age is 36"
--   </pre>
--   
--   See <a>Formatting.Formatters</a> for a list of formatters. See
--   <a>Formatting.Combinators</a> for a list of formatting combinators,
--   for combining and altering formatters.
module Formatting

-- | A formatter. When you construct formatters the first type parameter,
--   <tt>r</tt>, will remain polymorphic. The second type parameter,
--   <tt>a</tt>, will change to reflect the types of the data that will be
--   formatted. For example, in
--   
--   <pre>
--   myFormat :: Format r (Text -&gt; Int -&gt; r)
--   myFormat = "Person's name is " % text % ", age is " % hex
--   </pre>
--   
--   the first type parameter remains polymorphic, and the second type
--   parameter is <tt>Text -&gt; Int -&gt; r</tt>, which indicates that it
--   formats a <a>Text</a> and an <a>Int</a>.
--   
--   When you run the <a>Format</a>, for example with <a>format</a>, you
--   provide the arguments and they will be formatted into a string.
--   
--   <pre>
--   &gt; format ("Person's name is " % text % ", age is " % hex) "Dave" 54
--   "Person's name is Dave, age is 36"
--   </pre>
data Format r a

-- | Concatenate two formatters.
--   
--   <tt>formatter1 % formatter2</tt> is a formatter that accepts arguments
--   for <tt>formatter1</tt> and <tt>formatter2</tt> and concatenates their
--   results. For example
--   
--   <pre>
--   format1 :: Format r (Text -&gt; r)
--   format1 = "Person's name is " % text
--   </pre>
--   
--   <pre>
--   format2 :: Format r r
--   format2 = ", "
--   </pre>
--   
--   <pre>
--   format3 :: Format r (Int -&gt; r)
--   format3 = "age is " % hex
--   </pre>
--   
--   <pre>
--   myFormat :: Format r (Text -&gt; Int -&gt; r)
--   myFormat = format1 % format2 % format3
--   </pre>
--   
--   Notice how the argument types of <tt>format1</tt> and <tt>format3</tt>
--   are gathered into the type of <tt>myFormat</tt>.
--   
--   (This is actually the composition operator for <a>Format</a>s
--   <a>Category</a> instance, but that is (at present) inconvenient to use
--   with regular <a>Prelude</a>. So this function is provided as a
--   convenience.)
(%) :: Format r a -> Format r' r -> Format r' a
infixr 9 %

-- | Concatenate two formatters with a space in between.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; format (int %+ "+" %+ int %+ "=" %+ int) 2 3 5
--   "2 + 3 = 5"
--   </pre>
(%+) :: 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 %.

-- | Like <tt>(&lt;&gt;)</tt> except put a space between the two
--   formatters. For example: <tt>format (year <a>%+</a> month <a>%+</a>
--   dayOfMonth) now</tt> will yield <tt>"2022 06 06"</tt>
(<%+>) :: Format r (a -> r) -> Format r (a -> r) -> Format r (a -> r)

-- | Don't format any data, just output a constant <a>Builder</a>.
now :: Builder -> Format r r

-- | Format a value of type <tt>a</tt> using a function of type <tt>a -&gt;
--   <a>Builder</a></tt>. For example, <tt>later (f :: Int -&gt;
--   Builder)</tt> produces <tt>Format r (Int -&gt; r)</tt>.
later :: (a -> Builder) -> Format r (a -> r)

-- | Functorial map over a formatter's input. Example: <tt>format (mapf
--   (drop 1) string) "hello"</tt>
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 <a>Text</a> value.
format :: Format Text a -> a

-- | Run the formatter and return a strict <a>Text</a> value.
sformat :: Format Text a -> a

-- | Run the formatter and return a <a>Builder</a> value.
bprint :: Format Builder a -> a

-- | Run the formatter and return a <a>Builder</a> value.
--   
--   This is a newer synonym for <a>bprint</a>, following the naming
--   convention set by <a>format</a> and <a>sformat</a>.
bformat :: Format Builder a -> a

-- | Run the formatter and print out the text to stdout.
fprint :: MonadIO m => Format (m ()) a -> a

-- | Run the formatter and print out the text to stdout, followed by a
--   newline.
fprintLn :: MonadIO m => Format (m ()) a -> a

-- | Run the formatter and put the output onto the given <a>Handle</a>.
hprint :: MonadIO m => Handle -> Format (m ()) a -> a

-- | Run the formatter and put the output and a newline onto the given
--   <a>Handle</a>.
hprintLn :: MonadIO m => Handle -> Format (m ()) a -> a

-- | Run the formatter and return a list of characters.
formatToString :: Format String a -> a

-- | Makes it easy to add formatting to any api that is expecting a
--   builder, a strict or lazy text, or a string. It is essentially (flip
--   runFormat), but with a more generous type due to the typeclass.
--   
--   For example: &gt;&gt;&gt; formatted TL.putStr ("x is: " % int % "n") 7
--   x is: 7 &gt;&gt;&gt; formatted T.putStr ("x is: " % int % "n") 7 x is:
--   7 &gt;&gt;&gt; formatted (id <tt>TL.Text) ("x is: " % int % "n") 7 "x
--   is: 7n" &gt;&gt;&gt; formatted (id </tt>T.Text) ("x is: " % int % "n")
--   7 "x is: 7n"
formatted :: FromBuilder t => (t -> o) -> Format o 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
--   <a>System.Clock</a>.
module Formatting.Clock

-- | Same as <tt>durationNS</tt> but works on <a>TimeSpec</a> from the
--   clock package.
timeSpecs :: Format r (TimeSpec -> TimeSpec -> r)


-- | Reexports of things that were previously in the <tt>text-format</tt>
--   package.
module Formatting.Internal.Raw

-- | Pad the left hand side of a string until it reaches <tt>k</tt>
--   characters wide, if necessary filling with character <tt>c</tt>.
left :: Buildable a => Int -> Char -> a -> Builder

-- | Pad the right hand side of a string until it reaches <tt>k</tt>
--   characters wide, if necessary filling with character <tt>c</tt>.
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 <a>mappend</a> function with right associativity instead of
--   left.
(<>) :: Builder -> Builder -> Builder
infixr 4 <>

-- | Unsafe conversion for decimal digits.
i2d :: Int -> Char

-- | Render a value using its <a>Show</a> 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 -&gt; "123", 0 -&gt; "0".
d :: Integral 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 <a>Show</a>) by turning it into
--   <a>Text</a>.
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 <tt>k</tt>
--   characters wide, if necessary filling with character <tt>ch</tt>.
l :: Buildable a => Int -> Char -> Format r (a -> r)

-- | Pad the right hand side of a string until it reaches <tt>k</tt>
--   characters wide, if necessary filling with character <tt>ch</tt>.
r :: Buildable a => Int -> Char -> Format r (a -> r)


-- | Formatters for time.
module Formatting.Time

-- | Timezone offset on the format <tt>-HHMM</tt>.
tz :: FormatTime a => Format r (a -> r)

-- | Timezone name.
tzName :: FormatTime a => Format r (a -> r)

-- | As <tt>dateTimeFmt</tt> <tt>locale</tt> (e.g. <tt>%a %b %e %H:%M:%S %Z
--   %Y</tt>).
datetime :: FormatTime a => Format r (a -> r)

-- | Same as <tt>%H:%M</tt>.
hm :: FormatTime a => Format r (a -> r)

-- | Same as <tt>%H:%M:%S</tt>.
hms :: FormatTime a => Format r (a -> r)

-- | As <tt>timeFmt</tt> <tt>locale</tt> (e.g. <tt>%H:%M:%S</tt>).
hmsL :: FormatTime a => Format r (a -> r)

-- | As <tt>time12Fmt</tt> <tt>locale</tt> (e.g. <tt>%I:%M:%S %p</tt>).
hmsPL :: FormatTime a => Format r (a -> r)

-- | Day half from (<tt>amPm</tt> <tt>locale</tt>), converted to lowercase,
--   <tt>am</tt>, <tt>pm</tt>.
dayHalf :: FormatTime a => Format r (a -> r)

-- | Day half from (<tt>amPm</tt> <tt>locale</tt>), <tt>AM</tt>,
--   <tt>PM</tt>.
dayHalfU :: FormatTime a => Format r (a -> r)

-- | Hour, 24-hour, leading 0 as needed, <tt>00</tt> - <tt>23</tt>.
hour24 :: FormatTime a => Format r (a -> r)

-- | Hour, 12-hour, leading 0 as needed, <tt>01</tt> - <tt>12</tt>.
hour12 :: FormatTime a => Format r (a -> r)

-- | Hour, 24-hour, leading space as needed, <tt> 0</tt> - <tt>23</tt>.
hour24S :: FormatTime a => Format r (a -> r)

-- | Hour, 12-hour, leading space as needed, <tt> 1</tt> - <tt>12</tt>.
hour12S :: FormatTime a => Format r (a -> r)

-- | Minute, <tt>00</tt> - <tt>59</tt>.
minute :: FormatTime a => Format r (a -> r)

-- | Second, without decimal part, <tt>00</tt> - <tt>60</tt>.
second :: FormatTime a => Format r (a -> r)

-- | Picosecond, including trailing zeros, <tt>000000000000</tt> -
--   <tt>999999999999</tt>.
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 <tt>%m/%d/%y</tt>.
dateSlash :: FormatTime a => Format r (a -> r)

-- | Same as <tt>%Y-%m-%d</tt>.
dateDash :: FormatTime a => Format r (a -> r)

-- | As <tt>dateFmt</tt> <tt>locale</tt> (e.g. <tt>%m/%d/%y</tt>).
dateSlashL :: FormatTime a => Format r (a -> r)

-- | Year.
year :: FormatTime a => Format r (a -> r)

-- | Last two digits of year, <tt>00</tt> - <tt>99</tt>.
yy :: FormatTime a => Format r (a -> r)

-- | Century (being the first two digits of the year), <tt>00</tt> -
--   <tt>99</tt>.
century :: FormatTime a => Format r (a -> r)

-- | Month name, long form (<a>fst</a> from <tt>months</tt>
--   <tt>locale</tt>), <tt>January</tt> - <tt>December</tt>.
monthName :: FormatTime a => Format r (a -> r)

-- | <tt> %H] month name, short form (<a>snd</a> from <tt>months</tt>
--   </tt>locale<tt>), </tt>Jan<tt> - </tt>Dec@.
monthNameShort :: FormatTime a => Format r (a -> r)

-- | Month of year, leading 0 as needed, <tt>01</tt> - <tt>12</tt>.
month :: FormatTime a => Format r (a -> r)

-- | Day of month, leading 0 as needed, <tt>01</tt> - <tt>31</tt>.
dayOfMonth :: FormatTime a => Format r (a -> r)

-- | Day of month, <tt>1st</tt>, <tt>2nd</tt>, <tt>25th</tt>, etc.
dayOfMonthOrd :: FormatTime a => Format r (a -> r)

-- | Day of month, leading space as needed, <tt> 1</tt> - <tt>31</tt>.
dayOfMonthS :: FormatTime a => Format r (a -> r)

-- | Day of year for Ordinal Date format, <tt>001</tt> - <tt>366</tt>.
day :: FormatTime a => Format r (a -> r)

-- | Year for Week Date format e.g. <tt>2013</tt>.
weekYear :: FormatTime a => Format r (a -> r)

-- | Last two digits of year for Week Date format, <tt>00</tt> -
--   <tt>99</tt>.
weekYY :: FormatTime a => Format r (a -> r)

-- | Century (first two digits of year) for Week Date format, <tt>00</tt> -
--   <tt>99</tt>.
weekCentury :: FormatTime a => Format r (a -> r)

-- | Week for Week Date format, <tt>01</tt> - <tt>53</tt>.
week :: FormatTime a => Format r (a -> r)

-- | Day for Week Date format, <tt>1</tt> - <tt>7</tt>.
dayOfWeek :: FormatTime a => Format r (a -> r)

-- | Day of week, short form (<a>snd</a> from <tt>wDays</tt>
--   <tt>locale</tt>), <tt>Sun</tt> - <tt>Sat</tt>.
dayNameShort :: FormatTime a => Format r (a -> r)

-- | Day of week, long form (<a>fst</a> from <tt>wDays</tt>
--   <tt>locale</tt>), <tt>Sunday</tt> - <tt>Saturday</tt>.
dayName :: FormatTime a => Format r (a -> r)

-- | Week number of year, where weeks start on Sunday (as
--   <tt>sundayStartWeek</tt>), <tt>00</tt> - <tt>53</tt>.
weekFromZero :: FormatTime a => Format r (a -> r)

-- | Day of week number, <tt>0</tt> (= Sunday) - <tt>6</tt> (= Saturday).
dayOfWeekFromZero :: FormatTime a => Format r (a -> r)

-- | Week number of year, where weeks start on Monday (as
--   <tt>mondayStartWeek</tt>), <tt>00</tt> - <tt>53</tt>.
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 <tt>NominalDiffTime</tt> and
--   <tt>DiffTime</tt>.
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)

-- | Display seconds in the following pattern: <tt>00:00:00:00</tt>, which
--   ranges from days to seconds.
diffComponents :: RealFrac n => Format r (n -> r)

-- | Variation of <a>diffComponents</a>, which lets you explicitly specify
--   how to render each component.
customDiffComponents :: RealFrac n => (forall r'. Format r' (Integer -> Integer -> Integer -> Integer -> r')) -> 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)
