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


-- | Extensible, type-safe formatting with scanf- and printf-like functions
--   
--   <i>Warning:</i> This version of the package is very experimental and
--   the interface may change in later versions. I am seeking comments to
--   improve it.
--   
--   This package is composed of two functions for formatted conversion
--   between strings and typed values. Each is defined as a type-indexed
--   function using a type class with multiple parameters and functional
--   dependencies along with format descriptors.
--   
--   <a>Text.XFormat.Read</a> allows one to parse values from a formatted
--   string. Its functionality is similar to the C <tt>scanf</tt> function.
--   Unlike <tt>scanf</tt>, however, the format descriptor is well-typed,
--   ensuring that the output type is statically known.
--   
--   <a>Text.XFormat.Show</a> allows one to print values to a formatted
--   string. Its functionality is similar to the C <tt>printf</tt>
--   function. Unlike <tt>printf</tt>, however, the format descriptor is
--   well-typed, ensuring that the variable number arguments are statically
--   known.
--   
--   These functions can be easily extended to support new formats and new
--   types. Extension is simple: define a format descriptor and an instance
--   of the appropriate class.
@package xformat
@version 0.1


-- | This module defines an extensible, type-indexed function for showing
--   well-typed values with a format descriptor. This may be considered a
--   Haskell variant of the C <tt>printf</tt> function.
--   
--   If you are primarily interested in using this library, you will want
--   to see <a>showsf</a> and <a>showf</a>, the more user-friendly
--   functions.
--   
--   If you are also interested in extending this library with your own
--   format descriptors, you should read about the <a>Format</a> class.
module Text.XFormat.Show

-- | This class provides the signature for an extensible, type-indexed
--   function that uses a format descriptor to print a variable number of
--   well-typed arguments to a string. The type variable <tt>d</tt> is the
--   format descriptor, and the <a>Functor</a> variable <tt>f</tt>
--   determines the type of the value to be shown.
--   
--   An instance of <tt>Format</tt> adds a (type) case to the function.
--   Before defining an instance, you must first define a format descriptor
--   for your specific type and expected input. The descriptor is often
--   very simple. See the descriptors in this module for examples.
--   
--   Here is the instance for types that are instances of <a>Show</a>.
--   
--   <pre>
--   data <a>ShowF</a> a = <a>Show</a> -- Format descriptor
--   </pre>
--   
--   <pre>
--   instance (<a>Show</a> a) =&gt; Format (<a>ShowF</a> a) (<a>Arr</a> a) where
--     <a>showsf'</a> <a>Show</a> = <a>Arr</a> <a>shows</a>
--   </pre>
--   
--   The <a>Arr</a> type is one of several <a>Functor</a> wrappers
--   necessary for defining these instances.
class Functor f => Format d f | d -> f
showsf' :: Format d f => d -> f ShowS
class Functor f => Apply f a b | f a -> b
apply :: Apply f a b => f a -> b

-- | Given a format descriptor <tt>d</tt>, a variable number of arguments
--   represented by <tt>a</tt> (and determined by <tt>d</tt>), and a
--   <a>String</a>, return a <a>String</a> result. This function removes
--   the <a>Functor</a> wrappers from the output of <a>showsf'</a> to get
--   the variable number of arguments.
showsf :: (Format d f, Apply f ShowS a) => d -> a

-- | Given a format descriptor <tt>d</tt> and a variable number of
--   arguments represented by <tt>a</tt> (and determined by <tt>d</tt>),
--   return a <a>String</a> result. This function is the same as
--   <a>showsf</a> but has already been applied to a <a>String</a> input.
showf :: (Format d f, Apply f String a) => d -> a

-- | Print a character argument.
data CharF
Char :: CharF

-- | Print an <a>Int</a> argument.
data IntF
Int :: IntF

-- | Print an <a>Integer</a> argument.
data IntegerF
Integer :: IntegerF

-- | Print a <a>Float</a> argument.
data FloatF
Float :: FloatF

-- | Print a <a>Double</a> argument.
data DoubleF
Double :: DoubleF

-- | Print a string argument.
data StringF
String :: StringF

-- | Print an argument whose type is an instance of the class <a>Show</a>.
data ShowF a
Show :: ShowF a

-- | Print an argument whose type is an instance of the class <a>Num</a>.
data NumF a
Num :: NumF a

-- | Right-associative pair. First print a <tt>a</tt>-type format and then
--   a <tt>b</tt>-type format.
data (:%:) a b
(:%:) :: a -> b -> :%: a b

-- | Right-associative pair. This is a shorter, functional equivalent to
--   the type <tt>(:%:)</tt>.
(%) :: a -> b -> a :%: b

-- | Print a format of one type wrapped by two other formats of a different
--   type.
data WrapF inner outer
Wrap :: outer -> inner -> outer -> WrapF inner outer

-- | Print a format aligned left or right within a column of the given
--   width.
data AlignF a
Align :: Dir -> Int -> a -> AlignF a

-- | Direction (left or right) used for <a>AlignF</a>.
data Dir
L :: Dir
R :: Dir

-- | Print a specified number of spaces.
data SpacesF
Spaces :: Int -> SpacesF

-- | Wrapper for a format constant that does not take any arguments. Used
--   in <tt>instance <a>Format</a> <a>String</a> Id</tt> for example.
newtype Id a
Id :: a -> Id a

-- | Wrapper for a format descriptor that takes an argument. Used in
--   <tt>instance (<a>Show</a> a) =&gt; <a>Format</a> (<a>ShowF</a> a) (Arr
--   a)</tt> for example.
newtype Arr a b
Arr :: (a -> b) -> Arr a b

-- | Wrapper for a format descriptor that composes two descriptors. Used in
--   <tt>instance (<a>Format</a> d1 f1, <a>Format</a> d2 f2) =&gt;
--   <a>Format</a> (d1 :%: d2) (f1 :.: f2)</tt> for example.
newtype (:.:) f g a
Comp :: (f (g a)) -> :.: f g a

-- | Helpful function for defining instances of composed format
--   descriptors.
(<>) :: (Functor f, Functor g) => f (b -> c) -> g (a -> b) -> :.: f g (a -> c)
instance (Eq a, Eq b) => Eq (a :%: b)
instance (Show a, Show b) => Show (a :%: b)
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12, Format d13 f13, Format d14 f14, Format d15 f15) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14, d15) (f1 :.: (f2 :.: (f3 :.: (f4 :.: (f5 :.: (f6 :.: (f7 :.: (f8 :.: (f9 :.: (f10 :.: (f11 :.: (f12 :.: (f13 :.: (f14 :.: f15))))))))))))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12, Format d13 f13, Format d14 f14) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14) (f1 :.: (f2 :.: (f3 :.: (f4 :.: (f5 :.: (f6 :.: (f7 :.: (f8 :.: (f9 :.: (f10 :.: (f11 :.: (f12 :.: (f13 :.: f14)))))))))))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12, Format d13 f13) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13) (f1 :.: (f2 :.: (f3 :.: (f4 :.: (f5 :.: (f6 :.: (f7 :.: (f8 :.: (f9 :.: (f10 :.: (f11 :.: (f12 :.: f13))))))))))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11, Format d12 f12) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12) (f1 :.: (f2 :.: (f3 :.: (f4 :.: (f5 :.: (f6 :.: (f7 :.: (f8 :.: (f9 :.: (f10 :.: (f11 :.: f12)))))))))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10, Format d11 f11) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11) (f1 :.: (f2 :.: (f3 :.: (f4 :.: (f5 :.: (f6 :.: (f7 :.: (f8 :.: (f9 :.: (f10 :.: f11))))))))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9, Format d10 f10) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10) (f1 :.: (f2 :.: (f3 :.: (f4 :.: (f5 :.: (f6 :.: (f7 :.: (f8 :.: (f9 :.: f10)))))))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8, Format d9 f9) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9) (f1 :.: (f2 :.: (f3 :.: (f4 :.: (f5 :.: (f6 :.: (f7 :.: (f8 :.: f9))))))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7, Format d8 f8) => Format (d1, d2, d3, d4, d5, d6, d7, d8) (f1 :.: (f2 :.: (f3 :.: (f4 :.: (f5 :.: (f6 :.: (f7 :.: f8)))))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6, Format d7 f7) => Format (d1, d2, d3, d4, d5, d6, d7) (f1 :.: (f2 :.: (f3 :.: (f4 :.: (f5 :.: (f6 :.: f7))))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5, Format d6 f6) => Format (d1, d2, d3, d4, d5, d6) (f1 :.: (f2 :.: (f3 :.: (f4 :.: (f5 :.: f6)))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4, Format d5 f5) => Format (d1, d2, d3, d4, d5) (f1 :.: (f2 :.: (f3 :.: (f4 :.: f5))))
instance (Format d1 f1, Format d2 f2, Format d3 f3, Format d4 f4) => Format (d1, d2, d3, d4) (f1 :.: (f2 :.: (f3 :.: f4)))
instance (Format d1 f1, Format d2 f2, Format d3 f3) => Format (d1, d2, d3) (f1 :.: (f2 :.: f3))
instance (Format d1 f1, Format d2 f2) => Format (d1, d2) (f1 :.: f2)
instance Format d f => Format (AlignF d) f
instance (Format din fin, Format dout fout) => Format (WrapF din dout) (fout :.: (fin :.: fout))
instance (Format d1 f1, Format d2 f2) => Format (d1 :%: d2) (f1 :.: f2)
instance Format SpacesF Id
instance Num a => Format (NumF a) (Arr a)
instance Show a => Format (ShowF a) (Arr a)
instance Format DoubleF (Arr Double)
instance Format FloatF (Arr Float)
instance Format IntegerF (Arr Integer)
instance Format IntF (Arr Int)
instance Format StringF (Arr String)
instance Format CharF (Arr Char)
instance Format Char Id
instance Format String Id
instance (Apply f b c, Apply g a b) => Apply (f :.: g) a c
instance Apply (Arr a) b (a -> b)
instance Apply Id a a
instance (Functor f, Functor g) => Functor (f :.: g)
instance Functor (Arr a)
instance Functor Id


-- | This module defines an extensible, type-indexed function for reading
--   well-typed values from a string with a format descriptor. This may be
--   considered a Haskell variant of the C <tt>scanf</tt> function.
--   
--   If you are primarily interested in using this library, you will want
--   to see <a>readsf</a> and <a>readf</a>, the more user-friendly
--   functions.
--   
--   If you are also interested in extending this library with your own
--   format descriptors, you should read about the <a>Format</a> class.
module Text.XFormat.Read

-- | This class provides the signature for an extensible, type-indexed
--   function that uses a format descriptor to parse a string input and
--   return a well-typed value. The type variable <tt>d</tt> is the format
--   descriptor, and the variable <tt>a</tt> is the type of the value to be
--   read from the input.
--   
--   An instance of <tt>Format</tt> adds a (type) case to the function.
--   Before defining an instance, you must first define a format descriptor
--   for your specific type and expected input. The descriptor is often
--   very simple. See the descriptors in this module for examples.
--   
--   Here is the instance for types that are instances of <a>Read</a>.
--   
--   <pre>
--   data <a>ReadF</a> a = <a>Read</a> -- Format descriptor
--   </pre>
--   
--   <pre>
--   instance (<a>Read</a> a) =&gt; Format (<a>ReadF</a> a) a where
--     <a>readpf</a> <a>Read</a> = <a>readS_to_P</a> <a>reads</a>
--   </pre>
--   
--   Note that you will need some of the combinators (such as
--   <a>readS_to_P</a>) in <a>Text.ParserCombinators.ReadP</a>.
class Format d a | d -> a
readpf :: Format d a => d -> ReadP a

-- | Given a format descriptor <tt>d</tt> and a <a>String</a>, return a
--   list of successes for the type <tt>a</tt>, i.e. <tt>[(a,
--   <a>String</a>)]</tt>. This function simply transforms the <a>ReadP</a>
--   parser of <a>readpf</a> to a <a>ReadS</a> function.
readsf :: Format d a => d -> ReadS a

-- | Given a format descriptor <tt>d</tt> and a <a>String</a>, return an
--   optional result of the type <tt>a</tt>. This function simply returns
--   the head of the list from <a>readsf</a> if it was successful.
readf :: Format d a => d -> String -> Maybe a

-- | Parse a character.
data CharF
Char :: CharF

-- | Parse an <a>Int</a>.
data IntF
Int :: IntF

-- | Parse an <a>Integer</a>.
data IntegerF
Integer :: IntegerF

-- | Parse a <a>Float</a>.
data FloatF
Float :: FloatF

-- | Parse a <a>Double</a>.
data DoubleF
Double :: DoubleF

-- | Parse a string. Reads until the end of the input.
data StringF
String :: StringF

-- | Parse a value whose type is an instance of the class <a>Read</a>.
data ReadF a
Read :: ReadF a

-- | Parse a value whose type is an instance of the class <a>Num</a>.
data NumF a
Num :: NumF a

-- | Right-associative pair. First parse a <tt>a</tt>-type format and then
--   a <tt>b</tt>-type format.
data (:%:) a b
(:%:) :: a -> b -> :%: a b

-- | Right-associative pair. This is a shorter, functional equivalent to
--   the type <tt>(:%:)</tt>.
(%) :: a -> b -> a :%: b

-- | Parse a format of one type wrapped by two other formats of a different
--   type.
data WrapF inner outer
Wrap :: outer -> inner -> outer -> WrapF inner outer

-- | Parse an optional value.
data MaybeF a
Maybe :: a -> MaybeF a

-- | Parse one of the optional formats in a list.
data ChoiceF a
Choice :: [a] -> ChoiceF a

-- | Parse one of two formats in a fully symmetric choice.
data EitherF a b
Either :: a -> b -> EitherF a b

-- | Parse one of two formats, trying the left one first.
data EitherLF a b
EitherL :: a -> b -> EitherLF a b

-- | Parse zero or more whitespace characters. Stop when a non-whitespace
--   character is reached.
data SpaceF
Space :: SpaceF
instance (Eq a, Eq b) => Eq (a :%: b)
instance (Show a, Show b) => Show (a :%: b)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10, Format d11 a11, Format d12 a12, Format d13 a13, Format d14 a14, Format d15 a15) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14, d15) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10, Format d11 a11, Format d12 a12, Format d13 a13, Format d14 a14) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13, d14) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10, Format d11 a11, Format d12 a12, Format d13 a13) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12, d13) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10, Format d11 a11, Format d12 a12) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11, d12) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10, Format d11 a11) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10, d11) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9, Format d10 a10) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9, d10) (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8, Format d9 a9) => Format (d1, d2, d3, d4, d5, d6, d7, d8, d9) (a1, a2, a3, a4, a5, a6, a7, a8, a9)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7, Format d8 a8) => Format (d1, d2, d3, d4, d5, d6, d7, d8) (a1, a2, a3, a4, a5, a6, a7, a8)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6, Format d7 a7) => Format (d1, d2, d3, d4, d5, d6, d7) (a1, a2, a3, a4, a5, a6, a7)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5, Format d6 a6) => Format (d1, d2, d3, d4, d5, d6) (a1, a2, a3, a4, a5, a6)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4, Format d5 a5) => Format (d1, d2, d3, d4, d5) (a1, a2, a3, a4, a5)
instance (Format d1 a1, Format d2 a2, Format d3 a3, Format d4 a4) => Format (d1, d2, d3, d4) (a1, a2, a3, a4)
instance (Format d1 a1, Format d2 a2, Format d3 a3) => Format (d1, d2, d3) (a1, a2, a3)
instance (Format d1 a1, Format d2 a2) => Format (d1, d2) (a1, a2)
instance (Format d1 a1, Format d2 a2) => Format (EitherLF d1 d2) (Either a1 a2)
instance (Format d1 a1, Format d2 a2) => Format (EitherF d1 d2) (Either a1 a2)
instance Format d a => Format (ChoiceF d) a
instance Format d a => Format (MaybeF d) (Maybe a)
instance (Format din ain, Format dout aout) => Format (WrapF din dout) (aout :%: (ain :%: aout))
instance (Format d1 a1, Format d2 a2) => Format (d1 :%: d2) (a1 :%: a2)
instance Format SpaceF String
instance Format (ReadP a) a
instance (Read a, Num a) => Format (NumF a) a
instance Read a => Format (ReadF a) a
instance Format DoubleF Double
instance Format FloatF Float
instance Format IntegerF Integer
instance Format IntF Int
instance Format StringF String
instance Format CharF Char
instance Format Char Char
instance Format String String