-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Combinator-based type-safe formatting (like printf() or FORMAT)
--   
@package formatting
@version 6.2.2


-- | Internal format starters.
module Formatting.Internal

-- | A formatter. The <tt>r</tt> type means the returned value at the end.
--   The more formatters you compose, the more this wil build up arguments
--   from <tt>r</tt> to <tt>Int -&gt; r</tt> to <tt>Char -&gt; (Int -&gt;
--   r)</tt>, etc.
newtype Format r a
Format :: ((Builder -> r) -> a) -> Format r a
runFormat :: Format r a -> (Builder -> r) -> a

-- | Useful instance for applying two formatters to the same input
--   argument. For example: <tt>format (year &lt;&gt; "/" % month) now</tt>
--   will yield <tt>"2015/01"</tt>.

-- | Useful instance for writing format string. With this you can write
--   <tt><a>Foo</a></tt> instead of <tt>now "Foo!"</tt>.

-- | The same as (%). At present using <a>Category</a> has an import
--   overhead, but one day it might be imported as standard.

-- | Composition operator. <a>Format</a> is an instance of <a>Category</a>,
--   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

-- | Function compose two formatters. Will feed the result of one formatter
--   into another.
(%.) :: Format r (Builder -> r') -> Format r' a -> Format r a

-- | Insert a constant monoidal value.
now :: Builder -> Format r r

-- | Monadic indexed bind for holey monoids.
bind :: Format r a -> (Builder -> Format r' r) -> Format r' a

-- | Insert a function which accepts some argument and produces a
--   <a>Builder</a> which is appended to the output at the end.
--   
--   <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 print out the text to stdout.
fprint :: Format (IO ()) a -> a

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

-- | Run the formatter and return a list of characters.
formatToString :: Format [Char] a -> a
instance Category Format
instance a ~ r => IsString (Format r a)
instance Monoid (Format r (a -> r))


-- | 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 scientific/engineering notation
--   (e.g. 2.3e123), with the given number of decimal places.
expt :: Real a => Int -> 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 floating point number, with the given number of digits of
--   precision. Uses decimal notation for values between 0.1 and 9,999,999,
--   and scientific notation otherwise.
prec :: 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 <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.
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.
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:
--   
--   <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


-- | 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 scientific/engineering notation
--   (e.g. 2.3e123), with the given number of decimal places.
ef :: Real a => Int -> Format r (a -> 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, with the given number of digits of
--   precision. Uses decimal notation for values between 0.1 and 9,999,999,
--   and scientific notation otherwise.
pf :: 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 <a>dateTimeFmt</a> <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 <a>timeFmt</a> <tt>locale</tt> (e.g. <tt>%H:%M:%S</tt>).
hmsL :: FormatTime a => Format r (a -> r)

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

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

-- | Day half from (<a>amPm</a> <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 <a>dateFmt</a> <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 <a>months</a> <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 <a>months</a>
--   </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 <a>wDays</a>
--   <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 <a>wDays</a> <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 <a>NominalDiffTime</a> and
--   <a>DiffTime</a>.
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


-- | 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
--   </pre>
--   
--   See <a>Formatting.Formatters</a> for a complete list of formatting
--   combinators.
module Formatting

-- | A formatter. The <tt>r</tt> type means the returned value at the end.
--   The more formatters you compose, the more this wil build up arguments
--   from <tt>r</tt> to <tt>Int -&gt; r</tt> to <tt>Char -&gt; (Int -&gt;
--   r)</tt>, etc.
data Format r a

-- | Composition operator. <a>Format</a> is an instance of <a>Category</a>,
--   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

-- | Function compose two formatters. Will feed the result of one formatter
--   into another.
(%.) :: Format r (Builder -> r') -> Format r' a -> Format r a

-- | Insert a constant monoidal value.
now :: Builder -> Format r r

-- | Insert a function which accepts some argument and produces a
--   <a>Builder</a> which is appended to the output at the end.
--   
--   <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 print out the text to stdout.
fprint :: Format (IO ()) a -> a

-- | Run the formatter and put the output onto the given <a>Handle</a>.
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
--   <a>System.Clock</a>.
module Formatting.Clock

-- | Format the duration from start to end (args passed in that order).
--   
--   Examples:
--   
--   <pre>
--   4.00 s
--   500.69 ms
--   1.20 ms
--   19.38 µs
--   </pre>
timeSpecs :: Format r (TimeSpec -> TimeSpec -> r)