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


-- | Highbrow approach to type-safe printf format specifications.
--   
--   We use the co-Kleisli category for the comonad of functions out of a
--   fixed monoid to implement a generic combinator library for type-safe
--   format specifications. Works with pretty much anything that's a
--   monoid, with specific support for String, Text (strict/lazy), and
--   ByteString (strict/lazy). Credit to Daniel Patterson for introducing
--   me to something that looked just enough like it ought to be the
--   composition for a category, and Ryan Trinkle for the IsString
--   instance. :)
@package category-printf
@version 0.1.0.2

module Control.Category.Printf

-- | Handy type synonym for the things we're working with. You should
--   regard a value of type <tt>Format m a b</tt> as something which
--   explains how to write some element of the monoid <tt>m</tt> (a
--   "string" for our purposes), and which will change the type of printf
--   from <tt>a</tt> to <tt>b</tt>. For instance, something which adds a
--   responsibility to provide an additional argument of type <tt>t</tt>
--   might have type <tt>Format m a (t -&gt; a)</tt>, while a formatter
--   which somehow absolves you of that responsibility would have type
--   <tt>Format m (t -&gt; a) a</tt>.
type Format m = Cokleisli ((->) m)

-- | We can apply this to something like putStrLn to get a function for
--   formatted printing. Typically you'll have <tt>r = IO ()</tt>, but that
--   needn't be the case.
printfWith :: (m -> r) -> Format m r b -> b

-- | If you just want to build a string / element of your monoid, we have
--   <tt>sprintf = printfWith id</tt>
sprintf :: Format m m b -> b

-- | Formatter for a constant string.
c :: (Monoid m) => m -> Format m a a

-- | Inclusion of a string as an argument.
i :: Format m a (m -> a)

-- | Given a way to turn a value of type t into a string, this builds a
--   formatter which demands an additional argument of type t and splices
--   it in.
spliceWith :: (Monoid m) => (t -> m) -> Format m a (t -> a)

-- | Splice in anything showable.
s :: (Monoid s, IsString s, Show t) => Format s a (t -> a)

-- | Generalizes the string type that a formatter uses by applying
--   fromString internally.
generalizeString :: (IsString s, Monoid s) => Format String a b -> Format s a b

-- | Show an integral value using the given base, and using the provided
--   function to determine how to display individual digits.
intAtBase :: (Real t, Integral t, Show t, Monoid s, IsString s) => t -> (Int -> Char) -> Format s a (t -> a)

-- | Show an integral value in hexadecimal.
hex :: (Integral t, Show t, Monoid s, IsString s) => Format s a (t -> a)

-- | Show an integral value in octal.
oct :: (Integral t, Show t, Monoid s, IsString s) => Format s a (t -> a)

-- | Show a floating point value in exponential format. (e.g. 2.45e2,
--   -1.5e-3) If <tt>digs</tt> is Nothing, the value is shown to full
--   precision, if it is Just d then at most d digits after the decimal
--   point are shown.
eFloat :: (RealFloat t, Monoid s, IsString s) => Maybe Int -> Format s a (t -> a)

-- | Show a floating point value in standard decimal format. (e.g. 245000,
--   -0.0015) If <tt>digs</tt> is Nothing, the value is shown to full
--   precision, if it is Just d then at most d digits after the decimal
--   point are shown.
fFloat :: (RealFloat t, Monoid s, IsString s) => Maybe Int -> Format s a (t -> a)

-- | Show a floating point value using standard decimal notation for
--   arguments whose absolute value lies between 0.1 and 9,999,999, and
--   scientific notation otherwise. If <tt>digs</tt> is Nothing, the value
--   is shown to full precision, if it is Just d then at most d digits
--   after the decimal point are shown.
gFloat :: (RealFloat t, Monoid s, IsString s) => Maybe Int -> Format s a (t -> a)

-- | We can use <a>arr</a> from the Arrow instance for Cokleisli w to
--   produce formatters that manipulate the stack without printing. That
--   is, we have
--   
--   <pre>
--   arr :: (Monoid m) =&gt; (s -&gt; s') -&gt; Format m s s'
--   </pre>
--   
--   Push an argument onto the stack to be consumed by subsequent
--   formatters.
push :: Monoid m => t -> Format m (t -> a) a

-- | Duplicate an argument on the stack, making it available twice.
dup :: Monoid m => Format m (t -> t -> a) (t -> a)

-- | Swap the next two arguments on the stack.
swap :: Monoid m => Format m (t -> t' -> a) (t' -> t -> a)

-- | Skip the next argument on the stack.
skip :: Monoid m => Format m a (t -> a)

-- | Apply a function to the argument on the top of the stack.
apply :: Monoid m => (u -> v) -> Format m (v -> a) (u -> a)

-- | Apply a binary function to the top two arguments on the stack.
apply2 :: Monoid m => (u -> v -> w) -> Format m (w -> a) (u -> v -> a)
instance (a ~ b, Data.String.IsString s, GHC.Base.Monoid s) => Data.String.IsString (Control.Comonad.Cokleisli ((->) s) a b)

module Control.Category.Printf.String
printf :: Format String (IO ()) b -> b
printfLn :: Format String (IO ()) b -> b
hPrintf :: Handle -> Format String (IO ()) b -> b
hPrintfLn :: Handle -> Format String (IO ()) b -> b

module Control.Category.Printf.Text.Strict
printf :: Format Text (IO ()) b -> b
printfLn :: Format Text (IO ()) b -> b
hPrintf :: Handle -> Format Text (IO ()) b -> b
hPrintfLn :: Handle -> Format Text (IO ()) b -> b

module Control.Category.Printf.Text.Lazy
printf :: Format Text (IO ()) b -> b
printfLn :: Format Text (IO ()) b -> b
hPrintf :: Handle -> Format Text (IO ()) b -> b
hPrintfLn :: Handle -> Format Text (IO ()) b -> b

module Control.Category.Printf.ByteString.Strict
printf :: Format ByteString (IO ()) b -> b
printfLn :: Format ByteString (IO ()) b -> b
hPrintf :: Handle -> Format ByteString (IO ()) b -> b
hPrintfLn :: Handle -> Format ByteString (IO ()) b -> b

module Control.Category.Printf.ByteString.Lazy
printf :: Format ByteString (IO ()) b -> b
printfLn :: Format ByteString (IO ()) b -> b
hPrintf :: Handle -> Format ByteString (IO ()) b -> b
hPrintfLn :: Handle -> Format ByteString (IO ()) b -> b