@@ -1,3 +1,34 @@
1+{-
2+Copyright (C) 2007 John MacFarlane <jgm at berkeley dot edu>
3+
4+This program is free software; you can redistribute it and/or modify
5+it under the terms of the GNU General Public License as published by
6+the Free Software Foundation; either version 2 of the License, or
7+(at your option) any later version.
8+
9+This program is distributed in the hope that it will be useful,
10+but WITHOUT ANY WARRANTY; without even the implied warranty of
11+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12+GNU General Public License for more details.
13+
14+You should have received a copy of the GNU General Public License
15+along with this program; if not, write to the Free Software
16+Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17+-}
18+
19+{- |
20+ Module : Text.Pandoc.Blocks
21+ Copyright : Copyright (C) 2007 John MacFarlane
22+ License : GNU GPL, version 2 or above
23+
24+ Maintainer : John MacFarlane <jgm@berkeley.edu>
25+ Stability : alpha
26+ Portability : portable
27+
28+Functions for the manipulation of fixed-width blocks of text.
29+These are used in the construction of plain-text tables.
30+-}
31+
132module Text.Pandoc.Blocks
233 (
334 TextBlock (..),
@@ -16,11 +47,16 @@ where
1647import Text.PrettyPrint
1748import Data.List (transpose, intersperse)
1849
19−data TextBlock = TextBlock Int Int [String] -- width height lines
50+-- | A fixed-width block of text. Parameters are width of block,
51+-- height of block, and list of lines.
52+data TextBlock = TextBlock Int Int [String]
2053instance Show TextBlock where
2154 show x = show $ blockToDoc x
2255
23−docToBlock :: Int -> Doc -> TextBlock
56+-- | Convert a @Doc@ element into a @TextBlock@ with a specified width.
57+docToBlock :: Int -- ^ Width of text block.
58+ -> Doc -- ^ @Doc@ to convert.
59+ -> TextBlock
2460docToBlock width doc =
2561 let rendered = renderStyle (style {lineLength = width,
2662 ribbonsPerLine = 1}) doc
@@ -32,26 +68,33 @@ docToBlock width doc =
3268 lns' = chop lns
3369 in TextBlock width (length lns') lns'
3470
71+-- | Convert a @TextBlock@ to a @Doc@ element.
3572blockToDoc :: TextBlock -> Doc
3673blockToDoc (TextBlock _ _ lns) =
3774 if null lns
3875 then empty
3976 else vcat $ map text lns
4077
78+-- | Returns width of a @TextBlock@ (number of columns).
4179widthOfBlock :: TextBlock -> Int
4280widthOfBlock (TextBlock width _ _) = width
4381
82+-- | Returns height of a @TextBlock@ (number of rows).
4483heightOfBlock :: TextBlock -> Int
4584heightOfBlock (TextBlock _ height _) = height
4685
47−-- pad line out to width using spaces
48−hPad :: Int -> String -> String
86+-- | Pads a string out to a given width using spaces.
87+hPad :: Int -- ^ Desired width.
88+ -> String -- ^ String to pad.
89+ -> String
4990hPad width line =
5091 let lineLength = length line
5192 in if lineLength <= width
5293 then line ++ replicate (width - lineLength) ' '
5394 else take width line
5495
96+-- | Concatenates a list of @TextBlock@s into a new @TextBlock@ in
97+-- which they appear side by side.
5598hcatBlocks :: [TextBlock] -> TextBlock
5699hcatBlocks [] = TextBlock 0 0 []
57100hcatBlocks ((TextBlock width1 height1 lns1):xs) =
@@ -63,15 +106,18 @@ hcatBlocks ((TextBlock width1 height1 lns1):xs) =
63106 lns = zipWith (++) lns1' lns2'
64107 in TextBlock width height lns
65108
109+-- | Like @hcatBlocks@, but inserts space between the @TextBlock@s.
66110hsepBlocks = hcatBlocks . (intersperse (TextBlock 1 1 [" "]))
67111
68112isWhitespace x = x `elem` " \t"
69113
114+-- | Left-aligns the contents of a @TextBlock@ within the block.
70115leftAlignBlock :: TextBlock -> TextBlock
71116leftAlignBlock (TextBlock width height lns) =
72117 TextBlock width height $
73118 map (dropWhile isWhitespace) lns
74119
120+-- | Right-aligns the contents of a @TextBlock@ within the block.
75121rightAlignBlock :: TextBlock -> TextBlock
76122rightAlignBlock (TextBlock width height lns) =
77123 let rightAlignLine ln =
@@ -79,6 +125,7 @@ rightAlignBlock (TextBlock width height lns) =
79125 in reverse (rest ++ spaces)
80126 in TextBlock width height $ map rightAlignLine lns
81127
128+-- | Centers the contents of a @TextBlock@ within the block.
82129centerAlignBlock :: TextBlock -> TextBlock
83130centerAlignBlock (TextBlock width height lns) =
84131 let centerAlignLine ln =