-- | This module provides tools to layout text as grid or table. Besides basic -- things like specifying column positioning, alignment on the same character -- and length restriction it also provides advanced features like justifying -- text and fancy tables with styling support. -- {-# LANGUAGE RecordWildCards #-} module Text.Layout.Table ( -- * Layout combinators -- | Specify how a column is rendered with the combinators in this -- section. Sensible default values are provided with 'def'. module Data.Default.Class -- ** Columns , ColSpec , column , numCol , fixedCol , fixedLeftCol -- ** Length of columns , LenSpec , expand , fixed , expandUntil , fixedUntil -- ** Positional alignment , Position , H , left , right , center -- ** Alignment of cells at characters , AlignSpec , noAlign , charAlign , predAlign , dotAlign -- ** Cut marks , CutMark , noCutMark , singleCutMark , doubleCutMark -- * Basic grid layout , Row , grid , gridLines , gridString -- * Grid modification functions , altLines , checkeredCells -- * Table layout -- ** Grouping rows , RowGroup , rowsG , rowG , colsG , colsAllG -- ** Headers , HeaderColSpec , headerColumn , Header , fullH , titlesH -- ** Layout , tableLines , tableString -- * Text justification -- $justify , justify , justifyText -- * Vertical column positioning , Col , colsAsRowsAll , colsAsRows , top , bottom , V -- * Table styles , module Text.Layout.Table.Style -- * Column modification functions , pad , trimOrPad , align , alignFixed -- * Column modifaction primitives -- | These functions are provided to be reused. For example if someone -- wants to render their own kind of tables. , ColModInfo , widthCMI , unalignedCMI , ensureWidthCMI , ensureWidthOfCMI , columnModifier , AlignInfo , widthAI , deriveColModInfos , deriveAlignInfo , OccSpec ) where -- TODO AlignSpec: multiple alignment points - useful? -- TODO RowGroup: optional: vertical group labels -- TODO RowGroup: optional: provide extra layout for a RowGroup -- TODO ColModInfo: provide a special version of ensureWidthOfCMI to force header visibility -- TODO ColSpec: add some kind of combinator to construct ColSpec values (e.g. via Monoid, see optparse-applicative) import qualified Control.Arrow as A import Data.List import Data.Maybe import Data.Semigroup import Data.Default.Class import Data.Default.Instances.Base () import Text.Layout.Table.Justify import Text.Layout.Table.Style import Text.Layout.Table.Position.Internal import Text.Layout.Table.Primitives.AlignSpec.Internal import Text.Layout.Table.Primitives.Basic import Text.Layout.Table.Primitives.Column import Text.Layout.Table.Primitives.LenSpec.Internal import Text.Layout.Table.Primitives.Occurence import Text.Layout.Table.Internal import Text.Layout.Table.Vertical ------------------------------------------------------------------------------- -- Layout types and combinators ------------------------------------------------------------------------------- -- | Align all text at the first dot from the left. This is most useful for -- floating point numbers. dotAlign :: AlignSpec dotAlign = charAlign '.' -- | Numbers are positioned on the right and aligned on the floating point dot. numCol :: ColSpec numCol = column def right dotAlign def -- | Fixes the column length and positions according to the given 'Position'. fixedCol :: Int -> Position H -> ColSpec fixedCol l pS = column (fixed l) pS def def -- | Fixes the column length and positions on the left. fixedLeftCol :: Int -> ColSpec fixedLeftCol i = fixedCol i left ------------------------------------------------------------------------------- -- Single-cell layout functions. ------------------------------------------------------------------------------- -- | Assume the given length is greater or equal than the length of the 'String' -- passed. Pads the given 'String' accordingly using the position specification. -- -- >>> pad left 10 "foo" -- "foo " -- pad :: Position o -> Int -> String -> String pad p = case p of Start -> fillRight Center -> fillCenter End -> fillLeft -- | If the given text is too long, the 'String' will be shortened according to -- the position specification. Adds cut marks to indicate that the column has -- been trimmed in length, otherwise it behaves like 'pad'. -- -- >>> trimOrPad left (singleCutMark "..") 10 "A longer text." -- "A longer.." -- trimOrPad :: Position o -> CutMark -> Int -> String -> String trimOrPad p = case p of Start -> fitRightWith Center -> fitCenterWith End -> fitLeftWith -- | Align a 'String' by first locating the position to align with and then -- padding on both sides. If no such position is found, it will align it such -- that it gets aligned before that position. -- -- >>> let { os = predOccSpec (== '.') ; ai = deriveAlignInfo os "iiii.fff" } in align os ai <$> ["1.5", "30", ".25"] -- [" 1.5 "," 30 "," .25 "] -- -- This function assumes that the given 'String' fits the 'AlignInfo'. Thus: -- -- > ai <> deriveAlignInfo s = ai -- align :: OccSpec -> AlignInfo -> String -> String align oS (AlignInfo l r) s = case splitAtOcc oS s of (ls, rs) -> fillLeft l ls ++ case rs of -- No alignment character found. [] -> spaces r _ -> fillRight r rs -- | Aligns a 'String' using a fixed width, fitting it to the width by either -- filling or cutting while respecting the alignment. alignFixed :: Position o -> CutMark -> Int -> OccSpec -> AlignInfo -> String -> String alignFixed _ cms 0 _ _ _ = "" alignFixed _ cms 1 _ _ s@(_ : (_ : _)) = applyMarkLeftWith cms " " alignFixed p cms i oS ai@(AlignInfo l r) s = let n = l + r - i in case splitAtOcc oS s of (ls, rs) -> case p of Start -> let remRight = r - n in if remRight < 0 then fitRight (l + remRight) $ fillLeft l ls else fitRight (l + remRight) $ fillLeft l ls ++ rs End -> let remLeft = l - n in if remLeft < 0 then fitLeft (r + remLeft) $ fillRight r rs else fitLeft (r + remLeft) $ ls ++ fillRight r rs Center -> {- This is really complicated, maybe there can be found something better. First case l > r: l |<----'----->| |<-----------x----->| |--.-->| r c1 = (l + r) div 2 | |<---'--->|<---.--->| . | . c2 = c1 + (l + r) mod 2 . . d2 = d1 + i mod 2 . | |<-.->|<-'-->| | d1 = i div 2 |<----.----->| i needed length on the left side: l - c1 + d1 needed length on the right side: d2 - (l - c1) Second case l < r: l |<--'-->| |<------x---------->| |<----.---->| r c1 = (l + r) div 2 | |<---'--->|<---.--->| . | . c2 = c1 + (l + r) mod 2 . . d2 = d1 + i mod 2 . | |<-.->|<-'-->| | d1 = i div 2 |<----.----->| i needed length on the left side: d1 - (r - c2) needed length on the right side: (c1 - l) + d2 -} let (c, remC) = (l + r) `divMod` 2 (d, remD) = i `divMod` 2 d2 = d + remD c2 = c + remC -- Note: widthL and widthR can be negative if there is no -- width left and we need to further trim into the other -- side. (widthL, widthR) = if l > c then (l - c2 + d, d2 - (l - c2)) else (d - (r - c), (c2 - l) + d2) lenL = length ls lenR = length rs toCutLfromR = negate $ min 0 widthL toCutRfromL = max 0 $ negate widthR (markL, funL) = if lenL > widthL then ( applyMarkLeft , take (widthL - toCutRfromL) . drop (lenL - widthL) ) else ( id , fillLeft (widthL - toCutRfromL) . take (lenL - toCutRfromL) ) (markR, funR) = if lenR > widthR then (applyMarkRight, take widthR) else (id , fillRight widthR) in markL $ markR $ funL ls ++ drop toCutLfromR (funR rs) where fitRight = fitRightWith cms fitLeft = fitLeftWith cms applyMarkRight = applyMarkRightWith cms applyMarkLeft = applyMarkLeftWith cms -- | Specifies how a column should be modified. Values of this type are derived -- in a traversal over the input columns by using 'deriveColModInfos'. Finally, -- 'columnModifier' will interpret them and apply the appropriate modification -- function to the cells of the column. data ColModInfo = FillAligned OccSpec AlignInfo | FillTo Int | FitTo Int (Maybe (OccSpec, AlignInfo)) -- | Private show function. showCMI :: ColModInfo -> String showCMI cmi = case cmi of FillAligned oS ai -> "FillAligned .. " ++ showAI ai FillTo i -> "FillTo " ++ show i FitTo i _ -> "FitTo " ++ show i ++ ".." -- | Get the exact width of a 'ColModInfo' after applying it with -- 'columnModifier'. widthCMI :: ColModInfo -> Int widthCMI cmi = case cmi of FillAligned _ ai -> widthAI ai FillTo maxLen -> maxLen FitTo lim _ -> lim -- | Remove alignment from a 'ColModInfo'. This is used to change alignment of -- headers while using the combined width information. unalignedCMI :: ColModInfo -> ColModInfo unalignedCMI cmi = case cmi of FillAligned _ ai -> FillTo $ widthAI ai FitTo i _ -> FitTo i Nothing _ -> cmi -- | Ensures that the modification provides a minimum width but only if it is -- not limited. ensureWidthCMI :: Int -> Position H -> ColModInfo -> ColModInfo ensureWidthCMI w pos cmi = case cmi of FillAligned oS ai@(AlignInfo lw rw) -> let neededW = w - widthAI ai in if neededW <= 0 then cmi else FillAligned oS $ case pos of Start -> AlignInfo lw (rw + neededW) End -> AlignInfo (lw + neededW) rw Center -> let (q, r) = neededW `divMod` 2 in AlignInfo (q + lw) (q + rw + r) FillTo maxLen -> FillTo (max maxLen w) _ -> cmi -- | Ensures that the given 'String' will fit into the modified columns. ensureWidthOfCMI :: String -> Position H -> ColModInfo -> ColModInfo ensureWidthOfCMI = ensureWidthCMI . length -- | Generates a function which modifies a given cell according to -- 'Text.Layout.Table.Position.Position', 'CutMark' and 'ColModInfo'. This is -- used to modify a single cell of column to bring all cells of column to the -- same width. columnModifier :: Position H -> CutMark -> ColModInfo -> (String -> String) columnModifier pos cms lenInfo = case lenInfo of FillAligned oS ai -> align oS ai FillTo maxLen -> pad pos maxLen FitTo lim mT -> maybe (trimOrPad pos cms lim) (uncurry $ alignFixed pos cms lim) mT -- TODO factor out -- | Specifies the length before and after an alignment position (including the -- alignment character). data AlignInfo = AlignInfo Int Int -- | Private show function. showAI :: AlignInfo -> String showAI (AlignInfo l r) = "AlignInfo " ++ show l ++ " " ++ show r -- | The column width when using the 'AlignInfo'. widthAI :: AlignInfo -> Int widthAI (AlignInfo l r) = l + r -- | Produce an 'AlignInfo' that is wide enough to hold inputs of both given -- 'AlignInfo's. instance Semigroup AlignInfo where AlignInfo ll lr <> AlignInfo rl rr = AlignInfo (max ll rl) (max lr rr) instance Monoid AlignInfo where mempty = AlignInfo 0 0 -- | Derive the 'ColModInfo' by using layout specifications and the actual cells -- of a column. deriveColModInfos :: [(LenSpec, AlignSpec)] -> [Row String] -> [ColModInfo] deriveColModInfos specs = zipWith ($) (fmap fSel specs) . transpose where fSel (lenSpec, alignSpec) = case alignSpec of NoAlign -> let fitTo i = const $ FitTo i Nothing expandUntil f i max = if f (max <= i) then FillTo max else fitTo i max fun = case lenSpec of Expand -> FillTo Fixed i -> fitTo i ExpandUntil i -> expandUntil id i FixedUntil i -> expandUntil not i in fun . maximum . map length AlignOcc oS -> let fitToAligned i = FitTo i . Just . (,) oS fillAligned = FillAligned oS expandUntil f i ai = if f (widthAI ai <= i) then fillAligned ai else fitToAligned i ai fun = case lenSpec of Expand -> fillAligned Fixed i -> fitToAligned i ExpandUntil i -> expandUntil id i FixedUntil i -> expandUntil not i in fun . foldMap (deriveAlignInfo oS) -- | Generate the 'AlignInfo' of a cell by using the 'OccSpec'. deriveAlignInfo :: OccSpec -> String -> AlignInfo deriveAlignInfo occSpec s = AlignInfo <$> length . fst <*> length . snd $ splitAtOcc occSpec s ------------------------------------------------------------------------------- -- Basic layout ------------------------------------------------------------------------------- -- | Modifies cells according to the column specification. grid :: [ColSpec] -> [Row String] -> [Row String] grid specs tab = zipWith ($) cmfs <$> tab where -- | The column modification function for each column. cmfs = zipWith (uncurry columnModifier) (map (position A.&&& cutMark) specs) cmis cmis = deriveColModInfos (map (lenSpec A.&&& alignSpec) specs) tab -- | Behaves like 'grid' but produces lines by joining with whitespace. gridLines :: [ColSpec] -> [Row String] -> [String] gridLines specs = fmap unwords . grid specs -- | Behaves like 'gridLines' but produces a string by joining with the newline -- character. gridString :: [ColSpec] -> [Row String] -> String gridString specs = concatLines . gridLines specs ------------------------------------------------------------------------------- -- Grid modification functions ------------------------------------------------------------------------------- -- | Applies functions to given lines in a alternating fashion. This makes it -- easy to color lines to improve readability in a row. altLines :: [a -> b] -> [a] -> [b] altLines = zipWith ($) . cycle -- | Applies functions to cells in a alternating fashion for every line, every -- other line gets shifted by one. This is useful for distinguishability of -- single cells in a grid arrangement. checkeredCells :: (a -> b) -> (a -> b) -> [[a]] -> [[b]] checkeredCells f g = zipWith altLines $ cycle [[f, g], [g, f]] ------------------------------------------------------------------------------- -- Advanced layout ------------------------------------------------------------------------------- -- | Create a 'RowGroup' by aligning the columns vertically. The position is -- specified for each column. colsG :: [Position V] -> [Col String] -> RowGroup colsG ps = rowsG . colsAsRows ps -- | Create a 'RowGroup' by aligning the columns vertically. Each column uses -- the same vertical positioning. colsAllG :: Position V -> [Col String] -> RowGroup colsAllG p = rowsG . colsAsRowsAll p -- | Specifies a header. data Header = Header [HeaderColSpec] [String] | NoHeader -- | By the default the header is not shown. instance Default Header where def = NoHeader -- | Specify a header column for every title. fullH :: [HeaderColSpec] -> [String] -> Header fullH = Header -- | Use titles with the default header column specification. titlesH :: [String] -> Header titlesH = fullH $ repeat def -- | Layouts a pretty table with an optional header. Note that providing fewer -- layout specifications than columns or vice versa will result in not showing -- the redundant ones. tableLines :: [ColSpec] -- ^ Layout specification of columns -> TableStyle -- ^ Visual table style -> Header -- ^ Optional header details -> [RowGroup] -- ^ Rows which form a cell together -> [String] tableLines specs TableStyle { .. } header rGs = topLine : addHeaderLines (rowGroupLines ++ [bottomLine]) where -- Helpers for horizontal lines hLine hS d = hLineDetail hS d d d hLineDetail hS dL d dR cols = intercalate [hS] $ [dL] : intersperse [d] cols ++ [[dR]] -- Spacers consisting of columns of seperator elements. genHSpacers c = map (`replicate` c) colWidths -- Horizontal seperator lines topLine = hLineDetail realTopH realTopL realTopC realTopR $ genHSpacers realTopH bottomLine = hLineDetail groupBottomH groupBottomL groupBottomC groupBottomR $ genHSpacers groupBottomH groupSepLine = hLineDetail groupSepH groupSepLC groupSepC groupSepRC $ genHSpacers groupSepH headerSepLine = hLineDetail headerSepH headerSepLC headerSepC headerSepRC $ genHSpacers headerSepH -- Vertical content lines rowGroupLines = intercalate [groupSepLine] $ map (map (hLine ' ' groupV) . applyRowMods . rows) rGs -- Optional values for the header (addHeaderLines, fitHeaderIntoCMIs, realTopH, realTopL, realTopC, realTopR) = case header of Header headerColSpecs hTitles -> let headerLine = hLine ' ' headerV (zipWith ($) headerRowMods hTitles) headerRowMods = zipWith3 (\(HeaderColSpec pos optCutMark) cutMark -> columnModifier pos $ fromMaybe cutMark optCutMark ) headerColSpecs cMSs (map unalignedCMI cMIs) in ( (headerLine :) . (headerSepLine :) , zipWith ($) $ zipWith ($) (map ensureWidthOfCMI hTitles) posSpecs , headerTopH , headerTopL , headerTopC , headerTopR ) NoHeader -> ( id , id , groupTopH , groupTopL , groupTopC , groupTopR ) cMSs = map cutMark specs posSpecs = map position specs applyRowMods = map (zipWith ($) rowMods) rowMods = zipWith3 columnModifier posSpecs cMSs cMIs cMIs = fitHeaderIntoCMIs $ deriveColModInfos (map (lenSpec A.&&& alignSpec) specs) $ concatMap rows rGs colWidths = map widthCMI cMIs -- | Does the same as 'tableLines', but concatenates lines. tableString :: [ColSpec] -- ^ Layout specification of columns -> TableStyle -- ^ Visual table style -> Header -- ^ Optional header details -> [RowGroup] -- ^ Rows which form a cell together -> String tableString specs style header rGs = concatLines $ tableLines specs style header rGs ------------------------------------------------------------------------------- -- Text justification ------------------------------------------------------------------------------- -- $justify -- Text can easily be justified and distributed over multiple lines. Such -- columns can be combined with other columns.