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


-- | Render overloaded expressions to their textual representation.
--   
--   This library allows you to render overloaded expressions to their
--   textual representation. For example:
--   
--   <pre>
--   *Repr&gt; let rd = 1.5 + 2 + (3 + (-4) * (5 - pi / sqrt 6)) :: Repr Double
--   *Repr&gt; show rd
--   "fromRational (3 % 2) + fromInteger 2 + (fromInteger 3 + negate (fromInteger 4) * (fromInteger 5 - pi / sqrt (fromInteger 6)))"
--   </pre>
@package repr
@version 0.3

module Text.Repr

-- | <tt>Repr a</tt> is a value of type <tt>a</tt> paired with a way to
--   render that value to its textual representation.
--   
--   Note that <tt>Repr a</tt> has an instance for most classes in base
--   provided that <tt>a</tt> has instances for the respected classes. This
--   allows you to write a numeric expression of type <tt>Repr a</tt>. For
--   example:
--   
--   <pre>
--   *Repr&gt; let r = 1.5 + 2 + (3 + (-4) * (5 - pi / sqrt 6)) :: Repr Double
--   </pre>
--   
--   You can extract the value of <tt>r</tt>:
--   
--   <pre>
--   *Repr&gt; extract r
--   17.281195923884734
--   </pre>
--   
--   And you can render <tt>r</tt> to its textual representation using
--   <a>show</a>:
--   
--   <pre>
--   *Repr&gt; show r
--   "fromRational (3 % 2) + fromInteger 2 + (fromInteger 3 + negate (fromInteger 4) * (fromInteger 5 - pi / sqrt (fromInteger 6)))"
--   </pre>
data Repr a

-- | Extract the value of the <tt>Repr</tt>.
extract :: Repr a -> a

-- | Extract the renderer of the <tt>Repr</tt>.
renderer :: Repr a -> Renderer

-- | To render you need to supply the precedence and fixity of the
--   enclosing context.
--   
--   For more documentation about precedence and fixity see:
--   
--   <a>http://haskell.org/onlinereport/decls.html#sect4.4.2</a>
--   
--   The reason the renderer returns a <a>DString</a>, instead of for
--   example a <a>String</a>, is that the rendering of numeric expression
--   involves lots of left-factored appends i.e.: <tt>((a ++ b) ++ c) ++
--   d</tt>. A <a>DString</a> has a O(1) append operation while a
--   <a>String</a> just has a O(n) append. So choosing a <a>DString</a> is
--   more efficient.
type Renderer = Precedence -> Fixity -> DString

-- | The precedence of operators and function application.
--   
--   <ul>
--   <li>Operators usually have a precedence in the range of 0 to 9.</li>
--   <li>Function application always has precedence 10.</li>
--   </ul>
type Precedence = Int

-- | Fixity of operators.
data Fixity

-- | No fixity information.
Non :: Fixity

-- | Left associative operator.
L :: Fixity

-- | Right associative operator.
R :: Fixity

-- | <tt>x &lt;?&gt; s</tt> annotates the rendering with the given string.
--   
--   The rendering wil look like: <tt>"({- s -} ...)"</tt> where
--   <tt>...</tt> is the rendering of <tt>x</tt>.
--   
--   This combinator is handy when you want to render the ouput of a
--   function and you want to see how the parameters of the function
--   contribute to the result. For example, suppose you defined the
--   following function <tt>f</tt>:
--   
--   <pre>
--   f p0 p1 p2 = p0 ^ 2 + sqrt p1 * ([p2..] !! 10)
--   </pre>
--   
--   You can then apply <tt>f</tt> to some parameters annotated with some
--   descriptive strings (the name of the parameter is usally a good idea):
--   
--   <pre>
--   f (1 &lt;?&gt; "p0") (2 &lt;?&gt; "p1") (3 &lt;?&gt; "p2")
--   </pre>
--   
--   The rendering will then look like:
--   
--   <pre>
--   "({- p0 -} fromInteger 1) * ({- p0 -} fromInteger 1) + sqrt ({- p1 -} (fromInteger 2)) * enumFrom ({- p2 -} (fromInteger 3)) !! 10"
--   </pre>
(<?>) :: Repr a -> DString -> Repr a

-- | <tt>pure x</tt> constructs a <a>Repr</a> which has <tt>x</tt> as value
--   and the showed <tt>x</tt> as rendering. For example:
--   
--   <pre>
--   *Repr&gt; let r = pure [1,2,3]
--   *Repr&gt; extract r
--   [1,2,3]
--   *Repr&gt; show r
--   "[1,2,3]"
--   </pre>
pure :: (Show a) => a -> Repr a
instance Eq Fixity
instance (Random a, Show a) => Random (Repr a)
instance (Ix a) => Ix (Repr a)
instance (HasResolution a) => HasResolution (Repr a)
instance (Bits a) => Bits (Repr a)
instance (Monoid a) => Monoid (Repr a)
instance (Bounded a) => Bounded (Repr a)
instance (Eq a) => Eq (Repr a)
instance (Ord a) => Ord (Repr a)
instance (Enum a) => Enum (Repr a)
instance (RealFloat a) => RealFloat (Repr a)
instance (RealFrac a) => RealFrac (Repr a)
instance (Floating a) => Floating (Repr a)
instance (Fractional a) => Fractional (Repr a)
instance (Integral a) => Integral (Repr a)
instance (Real a) => Real (Repr a)
instance (Num a) => Num (Repr a)
instance (ToString a) => ToString (Repr a)
instance (IsString a) => IsString (Repr a)
instance (Read a) => Read (Repr a)
instance Show (Repr a)