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


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

module Repr

-- | <tt>Repr a</tt> is a value of type <tt>a</tt> paired with a way to
--   render that value to a string which will contain a representation of
--   the value.
--   
--   Note that <tt>Repr a</tt> is overloaded for all the numeric classes
--   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; value r
--   17.281195923884734
--   </pre>
--   
--   And you can than render <tt>r</tt> to its textual representation:
--   
--   <pre>
--   *Repr&gt; render 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>.
value :: Repr a -> a

-- | Extrac 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 rendering <i>top-level</i> values see <a>render</a>.)
--   
--   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 a
--   <a>String</a> for example, 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

-- | Render a <i>top-level</i> value to a <a>String</a>. Note that:
--   
--   <pre>
--   render r = <a>toString</a> $ <a>renderer</a> r 0 <a>Non</a>
--   </pre>
render :: Repr a -> String

-- | <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
instance Eq Fixity
instance (IsString a) => IsString (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 Show (Repr a)