-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Nice formatting library
--
-- Nice formatting library
@package fmt
@version 0.0.0.4
-- | A module providing access to internals (in case you really need them).
-- Can change at any time, though probably won't.
module Fmt.Internal
class FromBuilder a
fromBuilder :: FromBuilder a => Builder -> a
class FormatAsHex a
-- | Format a number or bytestring as hex:
--
--
-- >>> hexF 3635
-- "e33"
--
hexF :: FormatAsHex a => a -> Builder
class FormatAsBase64 a
-- | Convert a bytestring to base64:
--
--
-- >>> base64F ("\0\50\63\80" :: BS.ByteString)
-- "ADI/UA=="
--
base64F :: FormatAsBase64 a => a -> Builder
-- | Convert a bytestring to base64url (a variant of base64 which omits
-- / and thus can be used in URLs):
--
--
-- >>> base64UrlF ("\0\50\63\80" :: BS.ByteString)
-- "ADI_UA=="
--
base64UrlF :: FormatAsBase64 a => a -> Builder
groupInt :: (Buildable a, Integral a) => Int -> Char -> a -> Builder
atBase :: Integral a => Int -> a -> String
showSigned' :: Real a => (a -> ShowS) -> a -> ShowS
intToDigit' :: Int -> Char
indent' :: Int -> Text -> Builder -> Builder
instance Fmt.Internal.FromBuilder Data.Text.Internal.Builder.Builder
instance a ~ GHC.Types.Char => Fmt.Internal.FromBuilder [a]
instance Fmt.Internal.FromBuilder Data.Text.Internal.Text
instance Fmt.Internal.FromBuilder Data.Text.Internal.Lazy.Text
instance a ~ () => Fmt.Internal.FromBuilder (GHC.Types.IO a)
instance Fmt.Internal.FormatAsHex Data.ByteString.Internal.ByteString
instance Fmt.Internal.FormatAsHex Data.ByteString.Lazy.Internal.ByteString
instance GHC.Real.Integral a => Fmt.Internal.FormatAsHex a
instance Fmt.Internal.FormatAsBase64 Data.ByteString.Internal.ByteString
instance Fmt.Internal.FormatAsBase64 Data.ByteString.Lazy.Internal.ByteString
module Fmt
(%<) :: (FromBuilder b) => Builder -> Builder -> b
infixr 1 %<
(>%) :: (Buildable a, FromBuilder b) => a -> Builder -> b
infixr 1 >%
(%<<) :: (FromBuilder b) => Builder -> Builder -> b
infixr 1 %<<
(>>%) :: (Show a, FromBuilder b) => a -> Builder -> b
infixr 1 >>%
(>%%<) :: (Buildable a, FromBuilder b) => a -> Builder -> b
infixr 1 >%%<
(>>%%<<) :: (Show a, FromBuilder b) => a -> Builder -> b
infixr 1 >>%%<<
(>%%<<) :: (Show a, FromBuilder b) => a -> Builder -> b
infixr 1 >%%<<
(>>%%<) :: (Buildable a, FromBuilder b) => a -> Builder -> b
infixr 1 >>%%<
format :: (FromBuilder b, Params ps) => Format -> ps -> b
formatLn :: (FromBuilder b, Params ps) => Format -> ps -> b
-- | A format string. This is intentionally incompatible with other string
-- types, to make it difficult to construct a format string by
-- concatenating string fragments (a very common way to accidentally make
-- code vulnerable to malicious data).
--
-- This type is an instance of IsString, so the easiest way to
-- construct a query is to enable the OverloadedStrings language
-- extension and then simply write the query in double quotes.
--
--
-- {-# LANGUAGE OverloadedStrings #-}
--
-- import Data.Text.Format
--
-- f :: Format
-- f = "hello {}"
--
--
-- The underlying type is Text, so literal Haskell strings that
-- contain Unicode characters will be correctly handled.
data Format :: *
-- | fmt converts things to String, Text or
-- Builder.
--
-- Most of the time you won't need it, as strings produced with
-- (%<) and (>%) can already be used as
-- String, Text, etc. However, combinators like
-- listF can only produce Builder (for better type
-- inference), and you need to use fmt on them.
--
-- Also, fmt can do printing:
--
--
-- >>> fmt "Hello world!\n"
-- Hello world!
--
fmt :: FromBuilder b => Builder -> b
-- | Like fmt, but appends a newline.
fmtLn :: FromBuilder b => Builder -> b
-- | A Builder is an efficient way to build lazy Text
-- values. There are several functions for constructing builders, but
-- only one to inspect them: to extract any data, you have to turn them
-- into lazy Text values using toLazyText.
--
-- Internally, a builder constructs a lazy Text by filling
-- arrays piece by piece. As each buffer is filled, it is 'popped' off,
-- to become a new chunk of the resulting lazy Text. All this is
-- hidden from the user of the Builder.
data Builder :: *
-- | The class of types that can be rendered to a Builder.
class Buildable p
build :: Buildable p => p -> Builder
-- | Indent already formatted text.
--
--
-- >>> fmt $ "This is a list:\n" <> indent 4 (blockListF [1,2,3])
-- This is a list:
-- - 1
-- - 2
-- - 3
--
--
-- The output will always end with a newline, even when the input
-- doesn't.
indent :: Int -> Builder -> Builder
indent' :: Int -> Text -> Builder -> Builder
-- | Attach a name to anything:
--
--
-- >>> fmt $ nameF "clients" $ blockListF ["Alice", "Bob", "Zalgo"]
-- clients:
-- - Alice
-- - Bob
-- - Zalgo
--
nameF :: Builder -> Builder -> Builder
-- | A simple comma-separated list formatter.
--
--
-- >>> listF ["hello", "world"]
-- "[hello, world]"
--
--
-- For multiline output, use jsonListF.
listF :: (Foldable f, Buildable a) => f a -> Builder
-- | A version of listF that lets you supply your own building
-- function for list elements.
--
-- For instance, to format a list of lists you'd have to do this (since
-- there's no Buildable instance for lists):
--
--
-- >>> listF' listF [[1,2,3],[4,5,6]]
-- "[[1, 2, 3], [4, 5, 6]]"
--
listF' :: (Foldable f) => (a -> Builder) -> f a -> Builder
-- | A multiline formatter for lists.
--
--
-- >>> fmt $ blockListF [1,2,3]
-- - 1
-- - 2
-- - 3
--
--
-- It automatically handles multiline list elements:
--
--
-- >>> fmt $ blockListF ["hellonworld", "foonbarnquix"]
-- - hello
-- world
--
-- - foo
-- bar
-- quix
--
blockListF :: forall f a. (Foldable f, Buildable a) => f a -> Builder
-- | A version of blockListF that lets you supply your own building
-- function for list elements.
blockListF' :: forall f a. (Foldable f) => (a -> Builder) -> f a -> Builder
-- | A JSON-style formatter for lists.
--
--
-- >>> fmt $ jsonListF [1,2,3]
-- [
-- 1
-- , 2
-- , 3
-- ]
--
--
-- Like blockListF, it handles multiline elements well:
--
--
-- >>> fmt $ jsonListF ["hello\nworld", "foo\nbar\nquix"]
-- [
-- hello
-- world
-- , foo
-- bar
-- quix
-- ]
--
--
-- (Note that, unlike blockListF, it doesn't add blank lines in
-- such cases.)
jsonListF :: forall f a. (Foldable f, Buildable a) => f a -> Builder
-- | A version of jsonListF that lets you supply your own building
-- function for list elements.
jsonListF' :: forall f a. (Foldable f) => (a -> Builder) -> f a -> Builder
-- | A simple JSON-like map formatter; works for Map, HashMap, etc, as well
-- as ordinary lists of pairs.
--
--
-- >>> mapF [("a", 1), ("b", 4)]
-- "{a: 1, b: 4}"
--
--
-- For multiline output, use jsonMapF.
mapF :: (IsList t, Item t ~ (k, v), Buildable k, Buildable v) => t -> Builder
-- | A version of mapF that lets you supply your own building
-- function for keys and values.
mapF' :: (IsList t, Item t ~ (k, v)) => (k -> Builder) -> (v -> Builder) -> t -> Builder
-- | A YAML-like map formatter:
--
--
-- >>> fmt $ blockMapF [("Odds", blockListF [1,3]), ("Evens", blockListF [2,4])]
-- Odds:
-- - 1
-- - 3
-- Evens:
-- - 2
-- - 4
--
blockMapF :: (IsList t, Item t ~ (k, v), Buildable k, Buildable v) => t -> Builder
-- | A version of blockMapF that lets you supply your own building
-- function for keys and values.
blockMapF' :: (IsList t, Item t ~ (k, v)) => (k -> Builder) -> (v -> Builder) -> t -> Builder
-- | A JSON-like map formatter (unlike mapF, always multiline):
--
--
-- >>> fmt $ jsonMapF [("Odds", jsonListF [1,3]), ("Evens", jsonListF [2,4])]
-- {
-- Odds:
-- [
-- 1
-- , 3
-- ]
-- , Evens:
-- [
-- 2
-- , 4
-- ]
-- }
--
jsonMapF :: (IsList t, Item t ~ (k, v), Buildable k, Buildable v) => t -> Builder
-- | A version of jsonMapF that lets you supply your own building
-- function for keys and values.
jsonMapF' :: forall t k v. (IsList t, Item t ~ (k, v)) => (k -> Builder) -> (v -> Builder) -> t -> Builder
-- | Format a tuple (of up to 8 elements):
--
--
-- >>> tupleF (1,2,"hi")
-- "(1, 2, hi)"
--
--
-- If any of the elements takes several lines, an alternate format is
-- used:
--
--
-- >>> fmt $ tupleF ("test","foonbar","more test")
-- ( test
-- ,
-- foo
-- bar
-- ,
-- more test )
--
tupleF :: TupleF a => a -> Builder
-- | Format a list like a tuple. (This function is used to define
-- tupleF.)
tupleLikeF :: [Builder] -> Builder
-- | Like build for Maybe, but displays Nothing as
-- Nothing instead of an empty string.
--
-- build:
--
--
-- >>> build (Nothing :: Maybe Int)
-- ""
--
-- >>> build (Just 1 :: Maybe Int)
-- "1"
--
--
-- maybeF:
--
--
-- >>> maybeF (Nothing :: Maybe Int)
-- "<Nothing>"
--
-- >>> maybeF (Just 1 :: Maybe Int)
-- "1"
--
maybeF :: Buildable a => Maybe a -> Builder
-- | Format an Either:
--
--
-- >>> eitherF (Right 1)
-- "<Right>: 1"
--
eitherF :: (Buildable a, Buildable b) => Either a b -> Builder
-- | Take the first N characters:
--
--
-- >>> prefixF 3 "hello"
-- "hel"
--
prefixF :: Buildable a => Int -> a -> Builder
-- | Take the last N characters:
--
--
-- >>> suffixF 3 "hello"
-- "llo"
--
suffixF :: Buildable a => Int -> a -> Builder
-- | padLeftF n c pads the string with character c from
-- the left side until it becomes n characters wide (and does
-- nothing if the string is already that long, or longer):
--
--
-- >>> padLeftF 5 '0' 12
-- "00012"
--
-- >>> padLeftF 5 '0' 123456
-- "123456"
--
padLeftF :: Buildable a => Int -> Char -> a -> Builder
-- | padRightF n c pads the string with character c from
-- the right side until it becomes n characters wide (and does
-- nothing if the string is already that long, or longer):
--
--
-- >>> padRightF 5 ' ' "foo"
-- "foo "
--
-- >>> padRightF 5 ' ' "foobar"
-- "foobar"
--
padRightF :: Buildable a => Int -> Char -> a -> Builder
-- | padBothF n c pads the string with character c from
-- both sides until it becomes n characters wide (and does
-- nothing if the string is already that long, or longer):
--
--
-- >>> padBothF 5 '=' "foo"
-- "=foo="
--
-- >>> padBothF 5 '=' "foobar"
-- "foobar"
--
--
-- When padding can't be distributed equally, the left side is preferred:
--
--
-- >>> padBoth 8 '=' "foo"
-- "===foo=="
--
padBothF :: Buildable a => Int -> Char -> a -> Builder
-- | Format a number or bytestring as hex:
--
--
-- >>> hexF 3635
-- "e33"
--
hexF :: FormatAsHex a => a -> Builder
-- | Convert a bytestring to base64:
--
--
-- >>> base64F ("\0\50\63\80" :: BS.ByteString)
-- "ADI/UA=="
--
base64F :: FormatAsBase64 a => a -> Builder
-- | Convert a bytestring to base64url (a variant of base64 which omits
-- / and thus can be used in URLs):
--
--
-- >>> base64UrlF ("\0\50\63\80" :: BS.ByteString)
-- "ADI_UA=="
--
base64UrlF :: FormatAsBase64 a => a -> Builder
-- | Add an ordinal suffix to a number:
--
--
-- >>> ordinalF 15
-- "15th"
--
-- >>> ordinalF 22
-- "22nd"
--
ordinalF :: (Buildable a, Integral a) => a -> Builder
-- | Break digits in a number:
--
--
-- >>> commaizeF 15830000
-- "15,830,000"
--
commaizeF :: (Buildable a, Integral a) => a -> Builder
-- | Format a number as octal:
--
--
-- >>> listF' octF [7,8,9,10]
-- "[7, 10, 11, 12]"
--
octF :: Integral a => a -> Builder
-- | Format a number as binary:
--
--
-- >>> listF' binF [7,8,9,10]
-- "[111, 1000, 1001, 1010]"
--
binF :: Integral a => a -> Builder
-- | Format a number in arbitrary base (up to 36):
--
--
-- >>> baseF 3 10000
-- "111201101"
--
-- >>> baseF 7 10000
-- "41104"
--
-- >>> baseF 36 10000
-- "7ps"
--
baseF :: Integral a => Int -> a -> Builder
-- | Format a floating-point number:
--
--
-- >>> floatF 3.1415
-- "3.1415"
--
--
-- Numbers bigger than 1e21 or smaller than 1e-6 will be displayed using
-- scientific notation:
--
--
-- >>> listF' floatF [1e-6,9e-7]
-- "[0.000001, 9e-7]"
--
-- >>> listF' floatF [9e20,1e21]
-- "[900000000000000000000, 1e21]"
--
floatF :: Real a => a -> Builder
-- | Format a floating-point number using scientific notation, with given
-- amount of precision:
--
--
-- >>> listF' (exptF 5) [pi,0.1,10]
-- "[3.14159e0, 1.00000e-1, 1.00000e1]"
--
exptF :: Real a => Int -> a -> Builder
-- | Format a floating-point number with given amount of precision.
--
-- For small numbers, it uses scientific notation for everything smaller
-- than 1e-6:
--
--
-- listF' (precF 3) [1e-5,1e-6,1e-7]
--
--
-- "[0.0000100, 0.00000100, 1.00e-7]"
--
-- For large numbers, it uses scientific notation for everything larger
-- than 1eN, where N is the precision:
--
--
-- listF' (precF 4) [1e3,5e3,1e4]
--
--
-- "[1000, 5000, 1.000e4]"
precF :: Real a => Int -> a -> Builder
-- | Format a floating-point number without scientific notation:
--
--
-- >>> listF' (fixedF 5) [pi,0.1,10]
-- "[3.14159, 0.10000, 10.00000]"
--
fixedF :: Real a => Int -> a -> Builder
-- | Display something only if the condition is True (empty string
-- otherwise).
--
--
-- >>> "Hello!" <> whenF showDetails (", details: "%foobar%"")
--
--
-- Note that it can only take a Builder (because otherwise it
-- would be unusable with (%<)-formatted strings which can
-- resolve to any FromBuilder). Thus, use fmt if you need
-- just one value:
--
--
-- >>> "Maybe here's a number: "%cond (fmt n)%""
--
whenF :: Bool -> Builder -> Builder
-- | Display something only if the condition is False (empty string
-- otherwise).
unlessF :: Bool -> Builder -> Builder
instance (Data.Text.Buildable.Buildable a1, Data.Text.Buildable.Buildable a2) => Fmt.TupleF (a1, a2)
instance (Data.Text.Buildable.Buildable a1, Data.Text.Buildable.Buildable a2, Data.Text.Buildable.Buildable a3) => Fmt.TupleF (a1, a2, a3)
instance (Data.Text.Buildable.Buildable a1, Data.Text.Buildable.Buildable a2, Data.Text.Buildable.Buildable a3, Data.Text.Buildable.Buildable a4) => Fmt.TupleF (a1, a2, a3, a4)
instance (Data.Text.Buildable.Buildable a1, Data.Text.Buildable.Buildable a2, Data.Text.Buildable.Buildable a3, Data.Text.Buildable.Buildable a4, Data.Text.Buildable.Buildable a5) => Fmt.TupleF (a1, a2, a3, a4, a5)
instance (Data.Text.Buildable.Buildable a1, Data.Text.Buildable.Buildable a2, Data.Text.Buildable.Buildable a3, Data.Text.Buildable.Buildable a4, Data.Text.Buildable.Buildable a5, Data.Text.Buildable.Buildable a6) => Fmt.TupleF (a1, a2, a3, a4, a5, a6)
instance (Data.Text.Buildable.Buildable a1, Data.Text.Buildable.Buildable a2, Data.Text.Buildable.Buildable a3, Data.Text.Buildable.Buildable a4, Data.Text.Buildable.Buildable a5, Data.Text.Buildable.Buildable a6, Data.Text.Buildable.Buildable a7) => Fmt.TupleF (a1, a2, a3, a4, a5, a6, a7)
instance (Data.Text.Buildable.Buildable a1, Data.Text.Buildable.Buildable a2, Data.Text.Buildable.Buildable a3, Data.Text.Buildable.Buildable a4, Data.Text.Buildable.Buildable a5, Data.Text.Buildable.Buildable a6, Data.Text.Buildable.Buildable a7, Data.Text.Buildable.Buildable a8) => Fmt.TupleF (a1, a2, a3, a4, a5, a6, a7, a8)