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


-- | The Wadler/Leijen Pretty Printer, with annotation support
--   
--   This is a modified version of wl-pprint, which was based on Wadler's
--   paper "A Prettier Printer". See the haddocks for full info. This
--   version allows the library user to annotate the text with semantic
--   information, which can later be rendered in a variety of ways.
@package annotated-wl-pprint
@version 0.7.0

module Text.PrettyPrint.Annotated.Leijen

-- | The abstract data type <tt>Doc a</tt> represents pretty documents.
--   
--   <tt>Doc a</tt> is an instance of the <a>Show</a> class. <tt>(show
--   doc)</tt> pretty prints document <tt>doc</tt> with a page width of 100
--   characters and a ribbon width of 40 characters.
--   
--   <pre>
--   show (text "hello" &lt;$&gt; text "world")
--   </pre>
--   
--   Which would return the string "hello\nworld", i.e.
--   
--   <pre>
--   hello
--   world
--   </pre>
data Doc a

-- | The action <tt>(putDoc doc)</tt> pretty prints document <tt>doc</tt>
--   to the standard output, with a page width of 100 characters and a
--   ribbon width of 40 characters.
--   
--   <pre>
--   main :: IO ()
--   main = do{ putDoc (text "hello" &lt;+&gt; text "world") }
--   </pre>
--   
--   Which would output
--   
--   <pre>
--   hello world
--   </pre>
putDoc :: Doc a -> IO ()

-- | <tt>(hPutDoc handle doc)</tt> pretty prints document <tt>doc</tt> to
--   the file handle <tt>handle</tt> with a page width of 100 characters
--   and a ribbon width of 40 characters.
--   
--   <pre>
--   main = do{ handle &lt;- openFile "MyFile" WriteMode
--            ; hPutDoc handle (vcat (map text
--                              ["vertical","text"]))
--            ; hClose handle
--            }
--   </pre>
hPutDoc :: Handle -> Doc a -> IO ()

-- | The empty document is, indeed, empty. Although <tt>empty</tt> has no
--   content, it does have a 'height' of 1 and behaves exactly like
--   <tt>(text "")</tt> (and is therefore not a unit of
--   <tt>&lt;$&gt;</tt>).
empty :: Doc a

-- | The document <tt>(char c)</tt> contains the literal character
--   <tt>c</tt>. The character shouldn't be a newline (<tt>'\n'</tt>), the
--   function <a>line</a> should be used for line breaks.
char :: Char -> Doc a

-- | The document <tt>(text s)</tt> contains the literal string <tt>s</tt>.
--   The string shouldn't contain any newline (<tt>'\n'</tt>) characters.
--   If the string contains newline characters, the function <a>string</a>
--   should be used.
text :: String -> Doc a

-- | The document <tt>(x &lt;&gt; y)</tt> concatenates document <tt>x</tt>
--   and document <tt>y</tt>. It is an associative operation having
--   <a>empty</a> as a left and right unit. (infixr 6)
(<>) :: Doc a -> Doc a -> Doc a
infixr 6 <>

-- | The document <tt>(nest i x)</tt> renders document <tt>x</tt> with the
--   current indentation level increased by i (See also <a>hang</a>,
--   <a>align</a> and <a>indent</a>).
--   
--   <pre>
--   nest 2 (text "hello" &lt;$&gt; text "world") &lt;$&gt; text "!"
--   </pre>
--   
--   outputs as:
--   
--   <pre>
--   hello
--     world
--   !
--   </pre>
nest :: Int -> Doc a -> Doc a

-- | The <tt>line</tt> document advances to the next line and indents to
--   the current nesting level. Doc aument <tt>line</tt> behaves like
--   <tt>(text " ")</tt> if the line break is undone by <a>group</a>.
line :: Doc a

-- | The <tt>linebreak</tt> document advances to the next line and indents
--   to the current nesting level. Document <tt>linebreak</tt> behaves like
--   <a>empty</a> if the line break is undone by <a>group</a>.
linebreak :: Doc a

-- | The <tt>group</tt> combinator is used to specify alternative layouts.
--   The document <tt>(group x)</tt> undoes all line breaks in document
--   <tt>x</tt>. The resulting line is added to the current line if that
--   fits the page. Otherwise, the document <tt>x</tt> is rendered without
--   any changes.
group :: Doc a -> Doc a

-- | The document <tt>softline</tt> behaves like <a>space</a> if the
--   resulting output fits the page, otherwise it behaves like <a>line</a>.
--   
--   <pre>
--   softline = group line
--   </pre>
softline :: Doc a

-- | The document <tt>softbreak</tt> behaves like <a>empty</a> if the
--   resulting output fits the page, otherwise it behaves like <a>line</a>.
--   
--   <pre>
--   softbreak  = group linebreak
--   </pre>
softbreak :: Doc a

-- | The document <tt>(align x)</tt> renders document <tt>x</tt> with the
--   nesting level set to the current column. It is used for example to
--   implement <a>hang</a>.
--   
--   As an example, we will put a document right above another one,
--   regardless of the current nesting level:
--   
--   <pre>
--   x $$ y  = align (x &lt;$&gt; y)
--   </pre>
--   
--   <pre>
--   test    = text "hi" &lt;+&gt; (text "nice" $$ text "world")
--   </pre>
--   
--   which will be layed out as:
--   
--   <pre>
--   hi nice
--      world
--   </pre>
align :: Doc a -> Doc a

-- | The hang combinator implements hanging indentation. The document
--   <tt>(hang i x)</tt> renders document <tt>x</tt> with a nesting level
--   set to the current column plus <tt>i</tt>. The following example uses
--   hanging indentation for some text:
--   
--   <pre>
--   test  = hang 4 (fillSep (map text
--           (words "the hang combinator indents these words !")))
--   </pre>
--   
--   Which lays out on a page with a width of 20 characters as:
--   
--   <pre>
--   the hang combinator
--       indents these
--       words !
--   </pre>
--   
--   The <tt>hang</tt> combinator is implemented as:
--   
--   <pre>
--   hang i x  = align (nest i x)
--   </pre>
hang :: Int -> Doc a -> Doc a

-- | The document <tt>(indent i x)</tt> indents document <tt>x</tt> with
--   <tt>i</tt> spaces.
--   
--   <pre>
--   test  = indent 4 (fillSep (map text
--           (words "the indent combinator indents these words !")))
--   </pre>
--   
--   Which lays out with a page width of 20 as:
--   
--   <pre>
--   the indent
--   combinator
--   indents these
--   words !
--   </pre>
indent :: Int -> Doc a -> Doc a

-- | The document <tt>(encloseSep l r sep xs)</tt> concatenates the
--   documents <tt>xs</tt> separated by <tt>sep</tt> and encloses the
--   resulting document by <tt>l</tt> and <tt>r</tt>. The documents are
--   rendered horizontally if that fits the page. Otherwise they are
--   aligned vertically. All separators are put in front of the elements.
--   For example, the combinator <a>list</a> can be defined with
--   <tt>encloseSep</tt>:
--   
--   <pre>
--   list xs = encloseSep lbracket rbracket comma xs
--   test    = text "list" &lt;+&gt; (list (map int [10,200,3000]))
--   </pre>
--   
--   Which is layed out with a page width of 20 as:
--   
--   <pre>
--   list [10,200,3000]
--   </pre>
--   
--   But when the page width is 15, it is layed out as:
--   
--   <pre>
--   list [10
--        ,200
--        ,3000]
--   </pre>
encloseSep :: Doc a -> Doc a -> Doc a -> [Doc a] -> Doc a

-- | The document <tt>(list xs)</tt> comma separates the documents
--   <tt>xs</tt> and encloses them in square brackets. The documents are
--   rendered horizontally if that fits the page. Otherwise they are
--   aligned vertically. All comma separators are put in front of the
--   elements.
list :: [Doc a] -> Doc a

-- | The document <tt>(tupled xs)</tt> comma separates the documents
--   <tt>xs</tt> and encloses them in parenthesis. The documents are
--   rendered horizontally if that fits the page. Otherwise they are
--   aligned vertically. All comma separators are put in front of the
--   elements.
tupled :: [Doc a] -> Doc a

-- | The document <tt>(semiBraces xs)</tt> separates the documents
--   <tt>xs</tt> with semi colons and encloses them in braces. The
--   documents are rendered horizontally if that fits the page. Otherwise
--   they are aligned vertically. All semi colons are put in front of the
--   elements.
semiBraces :: [Doc a] -> Doc a

-- | The document <tt>(x &lt;+&gt; y)</tt> concatenates document <tt>x</tt>
--   and <tt>y</tt> with a <tt>space</tt> in between. (infixr 6)
(<+>) :: Doc a -> Doc a -> Doc a
infixr 6 <+>

-- | The document <tt>(x &lt;$&gt; y)</tt> concatenates document <tt>x</tt>
--   and <tt>y</tt> with a <a>line</a> in between. (infixr 5)
(<$>) :: Doc a -> Doc a -> Doc a
infixr 5 <$>

-- | The document <tt>(x &lt;/&gt; y)</tt> concatenates document <tt>x</tt>
--   and <tt>y</tt> with a <a>softline</a> in between. This effectively
--   puts <tt>x</tt> and <tt>y</tt> either next to each other (with a
--   <tt>space</tt> in between) or underneath each other. (infixr 5)
(</>) :: Doc a -> Doc a -> Doc a
infixr 5 </>

-- | The document <tt>(x &lt;$$&gt; y)</tt> concatenates document
--   <tt>x</tt> and <tt>y</tt> with a <tt>linebreak</tt> in between.
--   (infixr 5)
(<$$>) :: Doc a -> Doc a -> Doc a
infixr 5 <$$>

-- | The document <tt>(x &lt;//&gt; y)</tt> concatenates document
--   <tt>x</tt> and <tt>y</tt> with a <a>softbreak</a> in between. This
--   effectively puts <tt>x</tt> and <tt>y</tt> either right next to each
--   other or underneath each other. (infixr 5)
(<//>) :: Doc a -> Doc a -> Doc a
infixr 5 <//>

-- | The document <tt>(hsep xs)</tt> concatenates all documents <tt>xs</tt>
--   horizontally with (<a>&lt;+&gt;</a>).
hsep :: [Doc a] -> Doc a

-- | The document <tt>(vsep xs)</tt> concatenates all documents <tt>xs</tt>
--   vertically with <tt>(&lt;$&gt;)</tt>. If a <a>group</a> undoes the
--   line breaks inserted by <tt>vsep</tt>, all documents are separated
--   with a space.
--   
--   <pre>
--   someText = map text (words ("text to lay out"))
--   
--   test     = text "some" &lt;+&gt; vsep someText
--   </pre>
--   
--   This is layed out as:
--   
--   <pre>
--   some text
--   to
--   lay
--   out
--   </pre>
--   
--   The <a>align</a> combinator can be used to align the documents under
--   their first element
--   
--   <pre>
--   test     = text "some" &lt;+&gt; align (vsep someText)
--   </pre>
--   
--   Which is printed as:
--   
--   <pre>
--   some text
--        to
--        lay
--        out
--   </pre>
vsep :: [Doc a] -> Doc a

-- | The document <tt>(fillSep xs)</tt> concatenates documents <tt>xs</tt>
--   horizontally with <tt>(&lt;+&gt;)</tt> as long as its fits the page,
--   than inserts a <tt>line</tt> and continues doing that for all
--   documents in <tt>xs</tt>.
--   
--   <pre>
--   fillSep xs  = foldr (&lt;/&gt;) empty xs
--   </pre>
fillSep :: [Doc a] -> Doc a

-- | The document <tt>(sep xs)</tt> concatenates all documents <tt>xs</tt>
--   either horizontally with <tt>(&lt;+&gt;)</tt>, if it fits the page, or
--   vertically with <tt>(&lt;$&gt;)</tt>.
--   
--   <pre>
--   sep xs  = group (vsep xs)
--   </pre>
sep :: [Doc a] -> Doc a

-- | The document <tt>(hcat xs)</tt> concatenates all documents <tt>xs</tt>
--   horizontally with <tt>(&lt;&gt;)</tt>.
hcat :: [Doc a] -> Doc a

-- | The document <tt>(vcat xs)</tt> concatenates all documents <tt>xs</tt>
--   vertically with <tt>(&lt;$$&gt;)</tt>. If a <a>group</a> undoes the
--   line breaks inserted by <tt>vcat</tt>, all documents are directly
--   concatenated.
vcat :: [Doc a] -> Doc a

-- | The document <tt>(fillCat xs)</tt> concatenates documents <tt>xs</tt>
--   horizontally with <tt>(&lt;&gt;)</tt> as long as its fits the page,
--   than inserts a <tt>linebreak</tt> and continues doing that for all
--   documents in <tt>xs</tt>.
--   
--   <pre>
--   fillCat xs  = foldr (\&lt;\/\/\&gt;) empty xs
--   </pre>
fillCat :: [Doc a] -> Doc a

-- | The document <tt>(cat xs)</tt> concatenates all documents <tt>xs</tt>
--   either horizontally with <tt>(&lt;&gt;)</tt>, if it fits the page, or
--   vertically with <tt>(&lt;$$&gt;)</tt>.
--   
--   <pre>
--   cat xs  = group (vcat xs)
--   </pre>
cat :: [Doc a] -> Doc a

-- | <tt>(punctuate p xs)</tt> concatenates all documents in <tt>xs</tt>
--   with document <tt>p</tt> except for the last document.
--   
--   <pre>
--   someText = map text ["words","in","a","tuple"]
--   test     = parens (align (cat (punctuate comma someText)))
--   </pre>
--   
--   This is layed out on a page width of 20 as:
--   
--   <pre>
--   (words,in,a,tuple)
--   </pre>
--   
--   But when the page width is 15, it is layed out as:
--   
--   <pre>
--   (words,
--    in,
--    a,
--    tuple)
--   </pre>
--   
--   (If you want put the commas in front of their elements instead of at
--   the end, you should use <a>tupled</a> or, in general,
--   <a>encloseSep</a>.)
punctuate :: Doc a -> [Doc a] -> [Doc a]

-- | The document <tt>(fill i x)</tt> renders document <tt>x</tt>. It than
--   appends <tt>space</tt>s until the width is equal to <tt>i</tt>. If the
--   width of <tt>x</tt> is already larger, nothing is appended. This
--   combinator is quite useful in practice to output a list of bindings.
--   The following example demonstrates this.
--   
--   <pre>
--   types  = [("empty","Doc a")
--            ,("nest","Int -&gt; Doc a -&gt; Doc a")
--            ,("linebreak","Doc a")]
--   
--   ptype (name,tp)
--          = fill 6 (text name) &lt;+&gt; text "::" &lt;+&gt; text tp
--   
--   test   = text "let" &lt;+&gt; align (vcat (map ptype types))
--   </pre>
--   
--   Which is layed out as:
--   
--   <pre>
--   let empty  :: Doc a
--       nest   :: Int -&gt; Doc a -&gt; Doc a
--       linebreak :: Doc a
--   </pre>
fill :: Int -> Doc a -> Doc a

-- | The document <tt>(fillBreak i x)</tt> first renders document
--   <tt>x</tt>. It than appends <tt>space</tt>s until the width is equal
--   to <tt>i</tt>. If the width of <tt>x</tt> is already larger than
--   <tt>i</tt>, the nesting level is increased by <tt>i</tt> and a
--   <tt>line</tt> is appended. When we redefine <tt>ptype</tt> in the
--   previous example to use <tt>fillBreak</tt>, we get a useful variation
--   of the previous output:
--   
--   <pre>
--   ptype (name,tp)
--          = fillBreak 6 (text name) &lt;+&gt; text "::" &lt;+&gt; text tp
--   </pre>
--   
--   The output will now be:
--   
--   <pre>
--   let empty  :: Doc a
--       nest   :: Int -&gt; Doc a -&gt; Doc a
--       linebreak
--              :: Doc a
--   </pre>
fillBreak :: Int -> Doc a -> Doc a

-- | The document <tt>(enclose l r x)</tt> encloses document <tt>x</tt>
--   between documents <tt>l</tt> and <tt>r</tt> using <tt>(&lt;&gt;)</tt>.
--   
--   <pre>
--   enclose l r x   = l &lt;&gt; x &lt;&gt; r
--   </pre>
enclose :: Doc a -> Doc a -> Doc a -> Doc a

-- | Document <tt>(squotes x)</tt> encloses document <tt>x</tt> with single
--   quotes "'".
squotes :: Doc a -> Doc a

-- | Document <tt>(dquotes x)</tt> encloses document <tt>x</tt> with double
--   quotes '"'.
dquotes :: Doc a -> Doc a

-- | Document <tt>(parens x)</tt> encloses document <tt>x</tt> in
--   parenthesis, "(" and ")".
parens :: Doc a -> Doc a

-- | Document <tt>(angles x)</tt> encloses document <tt>x</tt> in angles,
--   "&lt;" and "&gt;".
angles :: Doc a -> Doc a

-- | Document <tt>(braces x)</tt> encloses document <tt>x</tt> in braces,
--   "{" and "}".
braces :: Doc a -> Doc a

-- | Document <tt>(brackets x)</tt> encloses document <tt>x</tt> in square
--   brackets, "[" and "]".
brackets :: Doc a -> Doc a

-- | The document <tt>lparen</tt> contains a left parenthesis, "(".
lparen :: Doc a

-- | The document <tt>rparen</tt> contains a right parenthesis, ")".
rparen :: Doc a

-- | The document <tt>langle</tt> contains a left angle, "&lt;".
langle :: Doc a

-- | The document <tt>rangle</tt> contains a right angle, "&gt;".
rangle :: Doc a

-- | The document <tt>lbrace</tt> contains a left brace, "{".
lbrace :: Doc a

-- | The document <tt>rbrace</tt> contains a right brace, "}".
rbrace :: Doc a

-- | The document <tt>lbracket</tt> contains a left square bracket, "[".
lbracket :: Doc a

-- | The document <tt>rbracket</tt> contains a right square bracket, "]".
rbracket :: Doc a

-- | The document <tt>squote</tt> contains a single quote, "'".
squote :: Doc a

-- | The document <tt>dquote</tt> contains a double quote, '"'.
dquote :: Doc a

-- | The document <tt>semi</tt> contains a semi colon, ";".
semi :: Doc a

-- | The document <tt>colon</tt> contains a colon, ":".
colon :: Doc a

-- | The document <tt>comma</tt> contains a comma, ",".
comma :: Doc a

-- | The document <tt>space</tt> contains a single space, " ".
--   
--   <pre>
--   x &lt;+&gt; y   = x &lt;&gt; space &lt;&gt; y
--   </pre>
space :: Doc a

-- | The document <tt>dot</tt> contains a single dot, ".".
dot :: Doc a

-- | The document <tt>backslash</tt> contains a back slash, "\".
backslash :: Doc a

-- | The document <tt>equals</tt> contains an equal sign, "=".
equals :: Doc a

-- | The document <tt>pipe</tt> contains a pipe character, "|".
pipe :: Doc a

-- | The document <tt>(string s)</tt> concatenates all characters in
--   <tt>s</tt> using <tt>line</tt> for newline characters and
--   <tt>char</tt> for all other characters. It is used instead of
--   <a>text</a> whenever the text contains newline characters.
string :: String -> Doc a

-- | The document <tt>(int i)</tt> shows the literal integer <tt>i</tt>
--   using <a>text</a>.
int :: Int -> Doc a

-- | The document <tt>(integer i)</tt> shows the literal integer <tt>i</tt>
--   using <a>text</a>.
integer :: Integer -> Doc a

-- | The document <tt>(float f)</tt> shows the literal float <tt>f</tt>
--   using <a>text</a>.
float :: Float -> Doc a

-- | The document <tt>(double d)</tt> shows the literal double <tt>d</tt>
--   using <a>text</a>.
double :: Double -> Doc a

-- | The document <tt>(rational r)</tt> shows the literal rational
--   <tt>r</tt> using <a>text</a>.
rational :: Rational -> Doc a

-- | The document <tt>(bool b)</tt> is <tt>text <a>True</a></tt> when
--   <tt>b</tt> is true, and <tt>text <a>False</a></tt> otherwise.
bool :: Bool -> Doc a
annotate :: a -> Doc a -> Doc a

-- | Strip annotations from a document. This is useful for re-using the
--   textual formatting of some sub-document, but applying a different
--   high-level annotation.
noAnnotate :: Doc a -> Doc a

-- | The data type <tt>SimpleDoc a</tt> represents rendered documents and
--   is used by the display functions.
--   
--   The <tt>Int</tt> in <tt>SText</tt> contains the length of the string.
--   The <tt>Int</tt> in <tt>SLine</tt> contains the indentation for that
--   line. The library provides two default display functions
--   <a>displayS</a> and <a>displayIO</a>. You can provide your own display
--   function by writing a function from a <tt>SimpleDoc a</tt> to your own
--   output format.
data SimpleDoc a
SEmpty :: SimpleDoc a
SChar :: Char -> (SimpleDoc a) -> SimpleDoc a
SText :: !Int -> String -> (SimpleDoc a) -> SimpleDoc a
SLine :: !Int -> (SimpleDoc a) -> SimpleDoc a
SAnnotStart :: a -> (SimpleDoc a) -> SimpleDoc a
SAnnotStop :: (SimpleDoc a) -> SimpleDoc a

-- | This is the default pretty printer which is used by <a>show</a>,
--   <a>putDoc</a> and <a>hPutDoc</a>. <tt>(renderPretty ribbonfrac width
--   x)</tt> renders document <tt>x</tt> with a page width of
--   <tt>width</tt> and a ribbon width of <tt>(ribbonfrac * width)</tt>
--   characters. The ribbon width is the maximal amount of non-indentation
--   characters on a line. The parameter <tt>ribbonfrac</tt> should be
--   between <tt>0.0</tt> and <tt>1.0</tt>. If it is lower or higher, the
--   ribbon width will be 0 or <tt>width</tt> respectively.
renderPretty :: Float -> Int -> Doc a -> SimpleDoc a

-- | <tt>(renderCompact x)</tt> renders document <tt>x</tt> without adding
--   any indentation. Since no 'pretty' printing is involved, this renderer
--   is very fast. The resulting output contains fewer characters than a
--   pretty printed version and can be used for output that is read by
--   other programs.
renderCompact :: Doc a -> SimpleDoc a

-- | Render a string, where annotated regions are decorated by a
--   user-provided function.
displayDecorated :: (a -> String -> String) -> SimpleDoc a -> String
displayDecoratedA :: (Applicative f, Monoid b) => (String -> f b) -> (a -> f b) -> (a -> f b) -> SimpleDoc a -> f b

-- | <tt>(display simpleDoc)</tt> transforms the <tt>simpleDoc</tt> to a
--   <a>String</a>.
display :: SimpleDoc a -> String

-- | <tt>(displayS simpleDoc a)</tt> takes the output <tt>simpleDoc a</tt>
--   from a rendering function and transforms it to a <a>ShowS</a> type
--   (for use in the <a>Show</a> class).
--   
--   <pre>
--   showWidth :: Int -&gt; Doc a -&gt; String
--   showWidth w x   = displayS (renderPretty 0.4 w x) ""
--   </pre>
displayS :: SimpleDoc a -> ShowS

-- | <tt>(displayIO handle simpleDoc a)</tt> writes <tt>simpleDoc a</tt> to
--   the file handle <tt>handle</tt>. This function is used for example by
--   'hPutDoc a':
--   
--   <pre>
--   hPutDoc a handle doc  = displayIO handle (renderPretty 0.4 100 doc)
--   </pre>
displayIO :: Handle -> SimpleDoc a -> IO ()
type SpanList a = [(Int, Int, a)]

-- | Generate a pair of a string and a list of source span/annotation pairs
displaySpans :: SimpleDoc a -> (String, SpanList a)
column :: (Int -> Doc a) -> Doc a
nesting :: (Int -> Doc a) -> Doc a
width :: Doc a -> (Int -> Doc a) -> Doc a
instance GHC.Base.Functor Text.PrettyPrint.Annotated.Leijen.SimpleDoc
instance GHC.Base.Functor Text.PrettyPrint.Annotated.Leijen.Doc
instance Data.String.IsString (Text.PrettyPrint.Annotated.Leijen.Doc a)
instance GHC.Show.Show (Text.PrettyPrint.Annotated.Leijen.Doc a)
