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


-- | Efficient simple pretty printing combinators
--   
--   A pretty printer turns a tree structure into indented text, such that
--   the indentation reflects the tree structure. To keep text short,
--   substructures are put into a single line as far as possible. The
--   library provides combinators for building pretty printers. It
--   emphasizes simplicity and efficiency.
@package FPretty
@version 1.1


-- | Fast pretty-printing library
--   
--   A pretty printer turns a tree structure into indented text, such that
--   the indentation reflects the tree structure. To minimise the number of
--   lines, substructures are put on a single line as far as possible
--   within the given line-width limit.
--   
--   An pretty-printed example with 35 characters line-width:
--   
--   <pre>
--   if True
--      then if True then True else True
--      else
--         if False 
--            then False 
--            else False
--   </pre>
--   
--   To obtain the above the user of a library only has to convert their
--   tree structure into a document of type <a>Doc</a>.
--   
--   <pre>
--   data Exp = ETrue | EFalse | If Exp Exp Exp
--   
--   toDoc :: Exp -&gt; Doc
--   toDoc ETrue = text "True"
--   toDoc EFalse = text "False"
--   toDoc (If e1 e2 e3) =
--     group (nest 3 (
--       group (nest 3 (text "if" &lt;&gt; line &lt;&gt; toDoc e1)) &lt;&gt; line &lt;&gt;
--       group (nest 3 (text "then" &lt;&gt; line &lt;&gt; toDoc e2)) &lt;&gt; line &lt;&gt;
--       group (nest 3 (text "else" &lt;&gt; line &lt;&gt; toDoc e3))))
--   </pre>
--   
--   A document represents a set of layouts. The function <a>pretty</a>
--   then takes a desired maximal printing width and a document and selects
--   the layout that fits best.
--   
--   Another example filling lines with elements of a list:
--   
--   <pre>
--   list2Doc :: Show a =&gt; [a] -&gt; Doc
--   list2Doc xs = text "[" &lt;&gt; go xs &lt;&gt; text "]"
--     where
--     go [] = empty
--     go [x] = text (show x)
--     go (x:y:ys) = text (show x) &lt;/&gt; text ", " &lt;&gt; go (y:ys)
--   
--   main = putStrLn (pretty 40 (list2Doc [1..20]))
--   </pre>
--   
--   The output is
--   
--   <pre>
--   [1 , 2 , 3 , 4 , 5 , 6 , 7 , 8 , 9 , 10
--   , 11 , 12 , 13 , 14 , 15 , 16 , 17 , 18
--   , 19 , 20]
--   </pre>
--   
--   FPretty is an implementation of the simple combinators designed by
--   Phil Wadler. The library uses a single associative combinator
--   <a>&lt;&gt;</a> to concatenate documents with <a>empty</a> as
--   identity. There is a primitive document for potential line breaks,
--   i.e., its two layouts are both a line break and a space. The
--   <a>group</a> combinator then enforces that all potential line breaks
--   within a document must be layouted in the same way, i.e. either line
--   breaks or spaces.
--   
--   The time complexity is linear in the output size. In contrast, all
--   other pretty printing libraries (original Phil Wadler, PPrint by
--   Leijen, Hughes / Peyton Jones) use more or less backtracking, and
--   their speed depends unpredictably on the desired output width.
--   
--   Also FPretty provides both relative and absolute indentation via nest
--   and align, whereas HughesPJ provides only relative indentation.
--   
--   FPretty uses far less space than other pretty printing libraries for
--   large documents. It does require space linear in the nesting depth of
--   nest/align combinators; however, having these deeply nested leads to a
--   bad layout anyway.
--   
--   Unlike other libraries, FPretty does not provide several rendering
--   modes, but could be extended to do so.
--   
--   The combinators are a subset of those of PPrint and are similar to
--   HughesPJ to make moving from one library to the other as painless as
--   possible.
--   
--   For more implementation notes see
--   <a>http://www.cs.kent.ac.uk/~oc/pretty.html</a> or Doitse Swierstra
--   and Olaf Chitil: Linear, bounded, functional pretty-printing. Journal
--   of Functional Programming, 19(1):1-16, January 2009.
module Text.PrettyPrint.FPretty

-- | A Document represents a *set* of layouts.
data Doc

-- | Pretty print within given width. Selects from the *set* of layouts
--   that the document represents the widest that fits within the given
--   width. If no such layout exists, then it will choose the narrowest
--   that exceeds the given width.
pretty :: Int -> Doc -> String

-- | The empty document; equal to text "".
empty :: Doc

-- | Atomic document consisting of just the given text. There should be no
--   newline \n in the string.
text :: String -> Doc

-- | Either a space or a new line.
line :: Doc

-- | Either nothing (<a>empty</a>) or a new line.
linebreak :: Doc

-- | A space, if the following still fits on the current line, otherwise
--   newline.
softline :: Doc

-- | Nothing, if the following still fits on the current line, otherwise
--   newline.
softbreak :: Doc

-- | Horizontal composition of two documents. Is associative with identity
--   <a>empty</a>.
(<>) :: Doc -> Doc -> Doc
infixr 6 <>

-- | Combine with a space in between.
(<+>) :: Doc -> Doc -> Doc
infixr 6 <+>

-- | Combine with a <a>line</a> in between.
(<$>) :: Doc -> Doc -> Doc
infixr 5 <$>

-- | Combine with a <a>linebreak</a> in between.
(<$$>) :: Doc -> Doc -> Doc
infixr 5 <$$>

-- | Combine with a <a>softline</a> in between.
(</>) :: Doc -> Doc -> Doc
infixr 5 </>

-- | Combine with a <a>softbreak</a> in between.
(<//>) :: Doc -> Doc -> Doc
infixr 5 <//>

-- | Mark document as group, that is, layout as a single line if possible.
--   Within a group for all basic documents with several layouts the same
--   layout is chosen, that is, they are all horizontal or all new lines.
--   Within a vertical group there can be a horizontal group, but within a
--   horizontal group all groups are also layouted horizontally.
group :: Doc -> Doc

-- | Increases current indentation level (absolute). Assumes argument &gt;=
--   0.
nest :: Int -> Doc -> Doc

-- | Set indentation to current column.
align :: Doc -> Doc

-- | Increase identation relative to the *current* column.
hang :: Int -> Doc -> Doc

-- | Combine non-empty list of documents with <a>&lt;+&gt;</a>, i.e., a
--   space separator.
hsep :: [Doc] -> Doc

-- | Combine non-empty list of documents with <a>&lt;$&gt;</a>, i.e., a
--   <a>line</a> separator.
vsep :: [Doc] -> Doc

-- | Combine non-empty list of documents with <a>&lt;/&gt;</a>, i.e., a
--   <a>softline</a> separator.
fillSep :: [Doc] -> Doc

-- | Combine non-empty list of documents vertically as a group. Seperated
--   by space instead if all fit on one line.
sep :: [Doc] -> Doc

-- | Combine non-empty list of documents with <a>&lt;&gt;</a>.
hcat :: [Doc] -> Doc

-- | Combine non-empty list of documents with <a>&lt;$$&gt;</a>, i.e., a
--   <a>linebreak</a> separator.
vcat :: [Doc] -> Doc

-- | Combine non-empty list of documents with <a>&lt;//&gt;</a>, i.e., a
--   <a>softbreak</a> separator.
fillCat :: [Doc] -> Doc

-- | Combine non-empty list of documents, filling lines as far as possible.
cat :: [Doc] -> Doc
instance GHC.Show.Show Text.PrettyPrint.FPretty.Doc
