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


-- | Type-safe printf from parsing GHC TypeLits Symbol
--   
--   An extensible and type-safe printf from parsing GHC TypeLits Symbol
--   literals, matching the semantics of <a>P.printf</a> from
--   <a>Text.Printf</a> in <i>base</i>. The difference is that the variants
--   here will always fail to compile if given arguments of the wrong type
--   (or too many or too little arguments). Most of the variants also
--   provide useful type feedback, telling you the type of arguments it
--   expects and how many when queried with <tt>:t</tt> or with typed
--   holes.
--   
--   See README and documentation of <a>GHC.TypeLits.Printf</a> for more
--   information
@package typelits-printf
@version 0.2.0.0


-- | Internal workings of the printf mechanisms, exposed for potential
--   debugging purposes.
--   
--   Please do not use this module for anything besides debugging, as is
--   definitely very unstable and might go away or change dramatically
--   between versions.
module GHC.TypeLits.Printf.Internal
type ParseFmtStr str = EvalParser FmtStrParser str
type ParseFmtStr_ str = EvalParser_ FmtStrParser str
type ParseFmt str = EvalParser FFParser str
type ParseFmt_ str = EvalParser_ FFParser str

-- | Whether to left-adjust or zero-pad a field. These are mutually
--   exclusive, with <a>LeftAdjust</a> taking precedence.
data FormatAdjustment
LeftAdjust :: FormatAdjustment
ZeroPad :: FormatAdjustment
type family ShowFormat (x :: k) :: Symbol

-- | How to handle the sign of a numeric field. These are mutually
--   exclusive, with <a>SignPlus</a> taking precedence.
data FormatSign
SignPlus :: FormatSign
SignSpace :: FormatSign
data WidthMod
WMhh :: WidthMod
WMh :: WidthMod
WMl :: WidthMod
WMll :: WidthMod
WML :: WidthMod
data Flags
Flags :: Maybe FormatAdjustment -> Maybe FormatSign -> Bool -> Flags
[fAdjust] :: Flags -> Maybe FormatAdjustment
[fSign] :: Flags -> Maybe FormatSign
[fAlternate] :: Flags -> Bool
type EmptyFlags = 'Flags 'Nothing 'Nothing 'False
data FieldFormat
FF :: Flags -> Maybe Nat -> Maybe Nat -> Maybe WidthMod -> SChar -> FieldFormat
[fmtFlags] :: FieldFormat -> Flags
[fmtWidth] :: FieldFormat -> Maybe Nat
[fmtPrecision] :: FieldFormat -> Maybe Nat
[fmtWidthMod] :: FieldFormat -> Maybe WidthMod
[fmtChar] :: FieldFormat -> SChar

-- | A type synonym for a single-character symbol. Ideally this would just
--   be <a>Char</a>, but we don't have chars at the type level. So, if you
--   see <a>SChar</a> in a type signature, it means that it's expected to
--   be a symbol/string with only one single character.
type SChar = Symbol
type family Demote k = a | a -> k
class Reflect (x :: a)
reflect :: Reflect x => p x -> Demote a

-- | Typeclass associating format types (<tt>d</tt>, <tt>f</tt>, etc.) with
--   the types that can be formatted by them.
--   
--   You can extend the printf methods here for your own types by writing
--   your instances here.
class FormatType (t :: SChar) a
formatArg :: FormatType t a => p t -> a -> FieldFormat -> ShowS
formatArg :: (FormatType t a, PrintfArg a) => p t -> a -> FieldFormat -> ShowS
class Printf (str :: Symbol) fun

-- | A version of <a>printf</a> taking an explicit proxy, which allows
--   usage without <i>TypeApplications</i>
--   
--   <pre>
--   &gt;&gt;&gt; putStrLn $ printf_ (Proxy :: Proxy "You have %.2f dollars, %s") 3.62 "Luigi"
--   You have 3.62 dollars, Luigi
--   </pre>
printf_ :: Printf str fun => p str -> fun

-- | The typeclass supporting polyarity used by <a>printf</a>. It works in
--   mostly the same way as <a>PrintfType</a> from <a>Text.Printf</a>, and
--   similar the same as <a>FormatF</a>. Ideally, you will never have to
--   run into this typeclass or have to deal with it directly.
--   
--   Every item in the first argument of <a>FormatFun</a> is a chunk of the
--   formatting string, split between format holes (<a>Right</a>) and
--   string chunks (<a>Left</a>).
--   
--   If you want to see some useful error messages for feedback,
--   <a>pHelp</a> can be useful:
--   
--   <pre>
--   &gt;&gt;&gt; pHelp $ printf @"You have %.2f dollars, %s" 3.62
--   -- ERROR: Call to printf missing argument fulfilling "%s"
--   -- Either provide an argument or rewrite the format string to not expect
--   -- one.
--   </pre>
class FormatFun (ffs :: [Either Symbol FieldFormat]) fun
formatFun :: FormatFun ffs fun => p ffs -> String -> fun

-- | Utility type powering <a>pfmt</a>. See documentation for <a>pfmt</a>
--   for more information on usage.
--   
--   Using <i>OverloadedLabels</i>, you never need to construct this
--   directly can just write <tt>#f</tt> and a <tt><a>PFmt</a> "f"</tt>
--   will be generated. You can also create this using <a>mkPFmt</a> or
--   <a>mkPFmt_</a>, in the situations where <i>OverloadedLabels</i>
--   doesn't work or is not wanted.
newtype PFmt c
PFmt :: FieldFormat -> PFmt c

-- | Parse and run a <i>single</i> format hole on a single vale. Can be
--   useful for formatting individual items or for testing your own custom
--   instances of <a>FormatType</a>.
--   
--   Usually meant to be used with <i>OverloadedLabels</i>:
--   
--   <pre>
--   &gt;&gt;&gt; pfmt #f 3.62
--   "3.62"
--   </pre>
--   
--   However, current versions of GHC disallow labels that aren't valid
--   identifier names, disallowing things like <tt><a>pfmt</a> #.2f
--   3.62</tt>. While there is an
--   &lt;<a>https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0170-unrestricted-overloadedlabels.rst</a>
--   approved proposal&gt; that allows this, if you are using an earlier
--   GHC version, you can get around this using <a>mkPFmt</a>:
--   
--   <pre>
--   &gt;&gt;&gt; pfmt (mkPFmt @".2f") 3.6234124
--   "3.62"
--   </pre>
--   
--   Ideally we'd want to be able to write
--   
--   <pre>
--   &gt;&gt;&gt; pfmt #.2f 3.6234124
--   "3.62"
--   </pre>
--   
--   (which should be possible in GHC 8.10+)
--   
--   Note that the format string should not include the leading <tt>%</tt>.
pfmt :: forall c a. FormatType c a => PFmt c -> a -> String

-- | Useful for using <a>pfmt</a> without <i>OverloadedLabels</i>, or also
--   when passing format specifiers that aren't currently allowed with
--   <i>OverloadedLabels</i> until GHC 8.10+ (like <tt>#.2f</tt>).
--   
--   <pre>
--   &gt;&gt;&gt; pfmt (mkPFmt @".2f") 3.6234124
--   "3.62"
--   </pre>
mkPFmt :: forall str lst ff f w q m c. (Listify str lst, ff ~ ParseFmt_ lst, Reflect ff, ff ~ 'FF f w q m c) => PFmt c

-- | A version of <a>mkPFmt</a> that takes an explicit proxy input.
--   
--   <pre>
--   &gt;&gt;&gt; pfmt (mkPFmt_ (Proxy :: Proxy ".2f")) 3.6234124
--   "3.62"
--   </pre>
mkPFmt_ :: forall str lst ff f w q m c p. (Listify str lst, ff ~ ParseFmt_ lst, Reflect ff, ff ~ 'FF f w q m c) => p str -> PFmt c

-- | A useful tool for helping the type system give useful errors for
--   <a>printf</a>:
--   
--   <pre>
--   &gt;&gt;&gt; printf @"You have ".2f" dollars, %s" 3.26 :: PHelp
--   -- ERROR: Call to printf missing argument fulfilling "%s"
--   -- Either provide an argument or rewrite the format string to not expect
--   -- one.
--   </pre>
--   
--   Mostly useful if you want to force a useful type error to help see
--   what is going on.
--   
--   See also <a>pHelp</a>
newtype PHelp
PHelp :: String -> PHelp

-- | A useful helper function for helping the type system give useful
--   errors for <tt>printf</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; pHelp $ printf @"You have %.2f dollars, %s" 3.62
--   -- ERROR: Call to printf missing argument fulfilling "%s"
--   -- Either provide an argument or rewrite the format string to not expect
--   -- one.
--   </pre>
--   
--   Mostly useful if you want to force a useful type error to help see
--   what is going on.
[pHelp] :: PHelp -> String
instance (Data.Symbol.Utils.Listify str lst, ff GHC.Types.~ GHC.TypeLits.Printf.Parse.ParseFmt_ lst, GHC.TypeLits.Printf.Parse.Reflect ff, ff GHC.Types.~ 'GHC.TypeLits.Printf.Parse.FF f w p m c) => GHC.OverloadedLabels.IsLabel str (GHC.TypeLits.Printf.Internal.PFmt c)
instance (Data.Symbol.Utils.Listify str lst, ffs GHC.Types.~ GHC.TypeLits.Printf.Parse.ParseFmtStr_ lst, GHC.TypeLits.Printf.Internal.FormatFun ffs fun) => GHC.TypeLits.Printf.Internal.Printf str fun
instance (TypeError ...) => GHC.TypeLits.Printf.Internal.FormatFun ('Data.Either.Right ff : ffs) GHC.Base.String
instance (TypeError ...) => GHC.TypeLits.Printf.Internal.FormatFun ('Data.Either.Right ff : ffs) ()
instance (TypeError ...) => GHC.TypeLits.Printf.Internal.FormatFun ('Data.Either.Right ff : ffs) Data.Text.Internal.Text
instance (TypeError ...) => GHC.TypeLits.Printf.Internal.FormatFun ('Data.Either.Right ff : ffs) Data.Text.Internal.Lazy.Text
instance (TypeError ...) => GHC.TypeLits.Printf.Internal.FormatFun ('Data.Either.Right ff : ffs) GHC.TypeLits.Printf.Internal.PHelp
instance (TypeError ...) => GHC.TypeLits.Printf.Internal.FormatFun ('Data.Either.Right ff : ffs) (GHC.Types.IO a)
instance (a GHC.Types.~ GHC.Types.Char) => GHC.TypeLits.Printf.Internal.FormatFun '[] GHC.TypeLits.Printf.Internal.PHelp
instance (a GHC.Types.~ GHC.Base.String) => GHC.TypeLits.Printf.Internal.FormatFun '[] a
instance (a GHC.Types.~ GHC.Types.Char) => GHC.TypeLits.Printf.Internal.FormatFun '[] Data.Text.Internal.Text
instance (a GHC.Types.~ GHC.Types.Char) => GHC.TypeLits.Printf.Internal.FormatFun '[] Data.Text.Internal.Lazy.Text
instance (a GHC.Types.~ ()) => GHC.TypeLits.Printf.Internal.FormatFun '[] (GHC.Types.IO a)
instance (TypeError ...) => GHC.TypeLits.Printf.Internal.FormatFun '[] ()
instance (TypeError ...) => GHC.TypeLits.Printf.Internal.FormatFun '[] (a -> b)
instance (GHC.TypeLits.KnownSymbol str, GHC.TypeLits.Printf.Internal.FormatFun ffs fun) => GHC.TypeLits.Printf.Internal.FormatFun ('Data.Either.Left str : ffs) fun
instance (afun GHC.Types.~ (arg -> fun), GHC.TypeLits.Printf.Parse.Reflect ff, ff GHC.Types.~ 'GHC.TypeLits.Printf.Parse.FF f w p m c, GHC.TypeLits.Printf.Internal.FormatType c arg, GHC.TypeLits.Printf.Internal.FormatFun ffs fun) => GHC.TypeLits.Printf.Internal.FormatFun ('Data.Either.Right ff : ffs) afun
instance GHC.TypeLits.Printf.Internal.FormatType "c" GHC.Types.Char
instance GHC.TypeLits.Printf.Internal.FormatType "c" GHC.Word.Word8
instance GHC.TypeLits.Printf.Internal.FormatType "c" GHC.Word.Word16
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Types.Char
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Types.Int
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Int.Int8
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Int.Int16
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Int.Int32
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Int.Int64
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Integer.Type.Integer
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Natural.Natural
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Types.Word
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Word.Word8
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Word.Word16
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Word.Word32
instance GHC.TypeLits.Printf.Internal.FormatType "d" GHC.Word.Word64
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Types.Char
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Types.Int
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Int.Int8
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Int.Int16
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Int.Int32
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Int.Int64
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Integer.Type.Integer
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Natural.Natural
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Types.Word
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Word.Word8
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Word.Word16
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Word.Word32
instance GHC.TypeLits.Printf.Internal.FormatType "o" GHC.Word.Word64
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Types.Int
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Int.Int8
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Int.Int16
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Int.Int32
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Int.Int64
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Integer.Type.Integer
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Natural.Natural
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Types.Word
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Word.Word8
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Word.Word16
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Word.Word32
instance GHC.TypeLits.Printf.Internal.FormatType "x" GHC.Word.Word64
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Types.Char
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Types.Int
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Int.Int8
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Int.Int16
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Int.Int32
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Int.Int64
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Integer.Type.Integer
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Natural.Natural
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Types.Word
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Word.Word8
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Word.Word16
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Word.Word32
instance GHC.TypeLits.Printf.Internal.FormatType "X" GHC.Word.Word64
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Types.Char
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Types.Int
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Int.Int8
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Int.Int16
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Int.Int32
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Int.Int64
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Integer.Type.Integer
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Natural.Natural
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Types.Word
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Word.Word8
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Word.Word16
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Word.Word32
instance GHC.TypeLits.Printf.Internal.FormatType "b" GHC.Word.Word64
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Types.Char
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Types.Int
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Int.Int8
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Int.Int16
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Int.Int32
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Int.Int64
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Integer.Type.Integer
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Natural.Natural
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Types.Word
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Word.Word8
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Word.Word16
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Word.Word32
instance GHC.TypeLits.Printf.Internal.FormatType "u" GHC.Word.Word64
instance GHC.TypeLits.Printf.Internal.FormatType "f" GHC.Types.Double
instance GHC.TypeLits.Printf.Internal.FormatType "f" GHC.Types.Float
instance GHC.TypeLits.Printf.Internal.FormatType "F" GHC.Types.Double
instance GHC.TypeLits.Printf.Internal.FormatType "F" GHC.Types.Float
instance GHC.TypeLits.Printf.Internal.FormatType "g" GHC.Types.Double
instance GHC.TypeLits.Printf.Internal.FormatType "g" GHC.Types.Float
instance GHC.TypeLits.Printf.Internal.FormatType "G" GHC.Types.Double
instance GHC.TypeLits.Printf.Internal.FormatType "G" GHC.Types.Float
instance GHC.TypeLits.Printf.Internal.FormatType "e" GHC.Types.Double
instance GHC.TypeLits.Printf.Internal.FormatType "e" GHC.Types.Float
instance GHC.TypeLits.Printf.Internal.FormatType "E" GHC.Types.Double
instance GHC.TypeLits.Printf.Internal.FormatType "E" GHC.Types.Float
instance GHC.TypeLits.Printf.Internal.FormatType "s" GHC.Base.String
instance GHC.TypeLits.Printf.Internal.FormatType "s" Data.Text.Internal.Text
instance GHC.TypeLits.Printf.Internal.FormatType "s" Data.Text.Internal.Lazy.Text
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Types.Char
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Types.Int
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Int.Int8
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Int.Int16
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Int.Int32
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Int.Int64
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Integer.Type.Integer
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Natural.Natural
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Types.Word
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Word.Word8
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Word.Word16
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Word.Word32
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Word.Word64
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Types.Double
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Types.Float
instance GHC.TypeLits.Printf.Internal.FormatType "v" GHC.Base.String
instance GHC.TypeLits.Printf.Internal.FormatType "v" Data.Text.Internal.Text
instance GHC.TypeLits.Printf.Internal.FormatType "v" Data.Text.Internal.Lazy.Text


-- | An extensible and type-safe printf from parsing GHC TypeLits Symbol
--   literals, matching the semantics of <a>printf</a> from
--   <a>Text.Printf</a> in <i>base</i>. The difference is that your
--   <a>printf</a>s will always fail to compile if given arguments of the
--   wrong type (or too many or too little arguments). It also allows you
--   to use types to help your development, by telling you the type of
--   arguments it expects and how many when queried with <tt>:t</tt> or
--   with typed holes. See documentation in <a>Text.Printf</a> for details
--   on how this formats items of various types, and the differences with C
--   <tt>printf(3)</tt>.
--   
--   See <a>printf</a> for the main function.
--   
--   You can extend functionality with formatting for your own types by
--   providing instances of <a>FormatType</a>.
--   
--   Also in this module is <a>pfmt</a>, which allows you to format
--   individual items according to a single format specifier.
module GHC.TypeLits.Printf

-- | "Type-safe printf". Call it like <tt><a>printf</a> @"you have %.02f
--   dollars, %s"</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; putStrLn $ printf @"You have %.2f dollars, %s" 3.62 "Luigi"
--   You have 3.62 dollars, Luigi
--   </pre>
--   
--   Looking at its type:
--   
--   <pre>
--   &gt;&gt;&gt; :t printf @"You have %.2f dollars, %s"
--   (FormatType "f" arg1, FormatType "s" arg2)
--     =&gt; arg1 -&gt; arg2 -&gt; String
--   </pre>
--   
--   It tells you that the result is an <tt>arg1 -&gt; arg2 -&gt;
--   <a>String</a></tt>: take two arguments, and return a <a>String</a>.
--   The first argument must be an instance of <tt><a>FormatType</a>
--   "f"</tt> (things that can be formatted by <tt>%f</tt>) and the second
--   argument must be an instance of <tt><a>FormatType</a> "s"</tt> (things
--   that can be formatted by <tt>%s</tt>).
--   
--   We can see this in action by progressively applying arguments:
--   
--   <pre>
--   &gt;&gt;&gt; :t printf @"You have %.2f dollars, %s" 3.62
--   FormatType "s" arg1 =&gt; arg1 -&gt; String
--   
--   &gt;&gt;&gt; :t printf @"You have %.2f dollars, %s" 3.62 "Luigi"
--   String
--   </pre>
--   
--   The type errors for forgetting to apply an argument (or applying too
--   many arguments) are pretty clear:
--   
--   <pre>
--   &gt;&gt;&gt; putStrLn $ printf @"You have %.2f dollars, %s"
--   -- ERROR: Call to printf missing argument fulfilling "%.2f"
--   -- Either provide an argument or rewrite the format string to not expect
--   -- one.
--   
--   &gt;&gt;&gt; putStrLn $ printf @"You have %.2f dollars, %s" 3.62
--   -- ERROR: Call to printf missing argument fulfilling "%s"
--   -- Either provide an argument or rewrite the format string to not expect
--   -- one.
--   
--   &gt;&gt;&gt; putStrLn $ printf @"You have %.2f dollars, %s" 3.62 "Luigi"
--   You have 3.62 dollars, Luigi
--   
--   &gt;&gt;&gt; putStrLn $ printf @"You have %.2f dollars, %s" 3.62 "Luigi" 72
--   -- ERROR: An extra argument of type Integer was given to a call to printf
--   -- Either remove the argument, or rewrite the format string to include the
--   -- appropriate hole.
--   </pre>
--   
--   If you want to see some useful error messages for feedback,
--   <a>pHelp</a> can be useful:
--   
--   <pre>
--   &gt;&gt;&gt; pHelp $ printf @"You have %.2f dollars, %s" 3.62
--   -- ERROR: Call to printf missing argument fulfilling "%s"
--   -- Either provide an argument or rewrite the format string to not expect
--   -- one.
--   </pre>
--   
--   Note that this also supports the "interpret as an IO action to print
--   out results" functionality that <a>Text.Printf</a> supports. This also
--   supports returning strict <a>Text</a> and lazy <a>Text</a> as well.
printf :: forall str fun. Printf str fun => fun

-- | A version of <a>printf</a> taking an explicit proxy, which allows
--   usage without <i>TypeApplications</i>
--   
--   <pre>
--   &gt;&gt;&gt; putStrLn $ printf_ (Proxy :: Proxy "You have %.2f dollars, %s") 3.62 "Luigi"
--   You have 3.62 dollars, Luigi
--   </pre>
printf_ :: Printf str fun => p str -> fun

-- | A useful tool for helping the type system give useful errors for
--   <a>printf</a>:
--   
--   <pre>
--   &gt;&gt;&gt; printf @"You have ".2f" dollars, %s" 3.26 :: PHelp
--   -- ERROR: Call to printf missing argument fulfilling "%s"
--   -- Either provide an argument or rewrite the format string to not expect
--   -- one.
--   </pre>
--   
--   Mostly useful if you want to force a useful type error to help see
--   what is going on.
--   
--   See also <a>pHelp</a>
data PHelp

-- | A useful helper function for helping the type system give useful
--   errors for <tt>printf</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; pHelp $ printf @"You have %.2f dollars, %s" 3.62
--   -- ERROR: Call to printf missing argument fulfilling "%s"
--   -- Either provide an argument or rewrite the format string to not expect
--   -- one.
--   </pre>
--   
--   Mostly useful if you want to force a useful type error to help see
--   what is going on.
pHelp :: PHelp -> String

-- | The typeclass supporting polyarity used by <a>printf</a>. It works in
--   mostly the same way as <a>PrintfType</a> from <a>Text.Printf</a>, and
--   similar the same as <a>FormatF</a>. Ideally, you will never have to
--   run into this typeclass or have to deal with it directly.
--   
--   Every item in the first argument of <a>FormatFun</a> is a chunk of the
--   formatting string, split between format holes (<a>Right</a>) and
--   string chunks (<a>Left</a>).
--   
--   If you want to see some useful error messages for feedback,
--   <a>pHelp</a> can be useful:
--   
--   <pre>
--   &gt;&gt;&gt; pHelp $ printf @"You have %.2f dollars, %s" 3.62
--   -- ERROR: Call to printf missing argument fulfilling "%s"
--   -- Either provide an argument or rewrite the format string to not expect
--   -- one.
--   </pre>
class FormatFun (ffs :: [Either Symbol FieldFormat]) fun

-- | Typeclass associating format types (<tt>d</tt>, <tt>f</tt>, etc.) with
--   the types that can be formatted by them.
--   
--   You can extend the printf methods here for your own types by writing
--   your instances here.
class FormatType (t :: SChar) a
formatArg :: FormatType t a => p t -> a -> FieldFormat -> ShowS
formatArg :: (FormatType t a, PrintfArg a) => p t -> a -> FieldFormat -> ShowS

-- | A type synonym for a single-character symbol. Ideally this would just
--   be <a>Char</a>, but we don't have chars at the type level. So, if you
--   see <a>SChar</a> in a type signature, it means that it's expected to
--   be a symbol/string with only one single character.
type SChar = Symbol

-- | Parse and run a <i>single</i> format hole on a single vale. Can be
--   useful for formatting individual items or for testing your own custom
--   instances of <a>FormatType</a>.
--   
--   Usually meant to be used with <i>OverloadedLabels</i>:
--   
--   <pre>
--   &gt;&gt;&gt; pfmt #f 3.62
--   "3.62"
--   </pre>
--   
--   However, current versions of GHC disallow labels that aren't valid
--   identifier names, disallowing things like <tt><a>pfmt</a> #.2f
--   3.62</tt>. While there is an
--   &lt;<a>https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0170-unrestricted-overloadedlabels.rst</a>
--   approved proposal&gt; that allows this, if you are using an earlier
--   GHC version, you can get around this using <a>mkPFmt</a>:
--   
--   <pre>
--   &gt;&gt;&gt; pfmt (mkPFmt @".2f") 3.6234124
--   "3.62"
--   </pre>
--   
--   Ideally we'd want to be able to write
--   
--   <pre>
--   &gt;&gt;&gt; pfmt #.2f 3.6234124
--   "3.62"
--   </pre>
--   
--   (which should be possible in GHC 8.10+)
--   
--   Note that the format string should not include the leading <tt>%</tt>.
pfmt :: forall c a. FormatType c a => PFmt c -> a -> String

-- | Utility type powering <a>pfmt</a>. See documentation for <a>pfmt</a>
--   for more information on usage.
--   
--   Using <i>OverloadedLabels</i>, you never need to construct this
--   directly can just write <tt>#f</tt> and a <tt><a>PFmt</a> "f"</tt>
--   will be generated. You can also create this using <a>mkPFmt</a> or
--   <a>mkPFmt_</a>, in the situations where <i>OverloadedLabels</i>
--   doesn't work or is not wanted.
data PFmt c

-- | Useful for using <a>pfmt</a> without <i>OverloadedLabels</i>, or also
--   when passing format specifiers that aren't currently allowed with
--   <i>OverloadedLabels</i> until GHC 8.10+ (like <tt>#.2f</tt>).
--   
--   <pre>
--   &gt;&gt;&gt; pfmt (mkPFmt @".2f") 3.6234124
--   "3.62"
--   </pre>
mkPFmt :: forall str lst ff f w q m c. (Listify str lst, ff ~ ParseFmt_ lst, Reflect ff, ff ~ 'FF f w q m c) => PFmt c

-- | A version of <a>mkPFmt</a> that takes an explicit proxy input.
--   
--   <pre>
--   &gt;&gt;&gt; pfmt (mkPFmt_ (Proxy :: Proxy ".2f")) 3.6234124
--   "3.62"
--   </pre>
mkPFmt_ :: forall str lst ff f w q m c p. (Listify str lst, ff ~ ParseFmt_ lst, Reflect ff, ff ~ 'FF f w q m c) => p str -> PFmt c