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


-- | Type safe interface for Text.Printf
--   
--   A type-safe interface for Text.Printf that ensures at compile-time
--   that the number and type of arguments passed to printf matches the
--   format specifier.
@package printf-safe
@version 0.1.0.1


-- | A type-safe interface for Text.Printf that ensures at compile-time
--   that the number and type of arguments passed to printf matches the
--   format specifier.
--   
--   Thus, the specifier is lifted to the type-level and can be composed
--   manually using the (%) type-level function, or with the (%) term-level
--   function.
--   
--   Note that while the term-level composition retains type-safety, it
--   does not provide a way to define string literals within the format
--   string, those must be passed on as an argument to printf in that case.
--   
--   Specifiers composed at the type-level can be bound to terms using the
--   Template' proxy (as they are not of kind *), and those terms can then
--   be further composed with each other.
module Text.Printf.Safe

-- | The printf frontend.
--   
--   <tt>a</tt> is of kind [Format]. It is first turned into a list of
--   format specifiers (the literals are kept in place), then the format
--   string is constructed from it.
--   
--   Example:
--   
--   <pre>
--   printf (Template :: Template ("hex: " % 'Hex % " binary: " % 'Binary)) 500 500
--   </pre>
--   
--   generates a format string "hex: %x binary: %b", and calls the internal
--   <a>printf</a> with the format string and the provided arguments.
printf :: (FoldToString (FormatList a), PrintfType (PrintfType a)) => proxy a -> PrintfType a

-- | Type family that produces a proxy (Template') from any compatible
--   template candidate.
--   
--   This way, we can have produce templates from single types, as in
--   
--   <pre>
--   Template :: Template Int
--   </pre>
--   
--   which acts as a `%d' specifier, or
--   
--   <pre>
--   Template :: Template ('Hex % Int)
--   </pre>
--   
--   which is a "%x %d" format string. (see composition below).

-- | Fixed-kinded proxy for storing a list of Formats for printf
data Template' (f :: [Format])
Template :: Template'

-- | Format specifiers that are not directly tied to a type. For example,
--   Hex (%x) belongs here, but Int (%d) doesn't. These constructors are
--   used ticked, promoting FormatSpec to its own kind.
data FormatSpec

-- | %x (requires an Int)
Hex :: FormatSpec

-- | %b (requires an Int)
Binary :: FormatSpec

-- | %o (requires an Int)
Oct :: FormatSpec

-- | %e (requires a Double)
Sci :: FormatSpec

-- | Acts like a <tt>cons</tt> function for <a>Format</a> lists, first
--   turning the the new head element into a Format. (since it can be a
--   string literal (kind Symbol), for example, or a Haskell type (kind
--   *)).
--   
--   Because the <a>Template</a> type family is poly-kinded, it supports
--   both lists and singular format specifiers. Composition produces lists.
--   
--   <pre>
--   format :: Template (Int % "in base 16 is: " % 'Hex)
--   format = Template
--   
--   printf format 50 50
--   </pre>

-- | Composes two templates.
--   
--   Given two terms representing templates, simply appends them to produce
--   a new term representing the composition.
--   
--   <pre>
--   format :: Template (Int % " in base " % Int % " is: ")
--   format = Template
--   
--   hex :: Template 'Hex
--   hex = Template
--   
--   printf (format % hex) 30 16 30
--   </pre>
--   
--   which yields the same result as calling <a>printf</a> as such:
--   
--   <pre>
--   Text.Printf.printf "%d in base %d is: %x" 30 16 30
--   </pre>
(%) :: Template' a -> Template' b -> Template (a :++ b)
infixr 5 %

-- | Same as (%), but inserts a space in between the two formats.
(<%>) :: Template' a -> Template' b -> Template (a :++ (Lit " " : b))

-- | Term-level representation of a 'Hex (hexadecimal) specifier for
--   composition.
--   
--   Example:
--   
--   <pre>
--   printf hex 35
--   </pre>
hex :: Template Hex

-- | Term-level representation of an 'Oct (octal) specifier for
--   composition.
oct :: Template Oct

-- | Term-level representation of a 'Binary specifier for composition.
binary :: Template Binary

-- | Term-level representation of an 'Sci (scientific) specifier for
--   composition.
sci :: Template Sci

-- | Term-level representation of a String specifier for composition.
--   
--   This will not generate string literals in the format string (as that's
--   only possible at the type-level), but insert a `%s' specifier and
--   modify the type of printf accordingly, so it is useful when the string
--   is not known at compile time.
--   
--   Example:
--   
--   <pre>
--   printf string "example"
--   </pre>
--   
--   This means this is the same as calling
--   
--   <pre>
--   Text.Printf.printf "%s" "example"
--   </pre>
string :: Template String
instance Text.Printf.Safe.FoldToString '[]
instance (GHC.TypeLits.KnownSymbol x, Text.Printf.Safe.FoldToString xs) => Text.Printf.Safe.FoldToString ('Text.Printf.Safe.ILit x : xs)
instance (GHC.TypeLits.KnownSymbol x, Text.Printf.Safe.FoldToString xs) => Text.Printf.Safe.FoldToString ('Text.Printf.Safe.ISpecifier x : xs)