table-layout- Layout text as grid or table.

Safe HaskellSafe




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.


Layout combinators

Specify how a column is rendered with the combinators in this section. Sensible default values are provided with def.


data ColSpec Source #

Specifies the layout of a column.


column :: LenSpec -> Position H -> AlignSpec -> CutMark -> ColSpec Source #

Smart constructor to specify a column.

numCol :: ColSpec Source #

Numbers are positioned on the right and aligned on the floating point dot.

fixedCol :: Int -> Position H -> ColSpec Source #

Fixes the column length and positions according to the given Position.

fixedLeftCol :: Int -> ColSpec Source #

Fixes the column length and positions on the left.

Length of columns

data LenSpec Source #

Determines how long a column will be.


expand :: LenSpec Source #

Allows columns to use as much space as needed.

fixed :: Int -> LenSpec Source #

Fixes column length to a specific width.

expandUntil :: Int -> LenSpec Source #

The column will expand as long as it is smaller as the given width.

fixedUntil :: Int -> LenSpec Source #

The column will be at least as wide as the given width.

Positional alignment

data Position orientation Source #

Specifies a position relative from a beginning.


Eq (Position orientation) Source # 


(==) :: Position orientation -> Position orientation -> Bool #

(/=) :: Position orientation -> Position orientation -> Bool #

Show (Position orientation) Source # 


showsPrec :: Int -> Position orientation -> ShowS #

show :: Position orientation -> String #

showList :: [Position orientation] -> ShowS #

Default (Position orientation) Source # 


def :: Position orientation #

data H Source #

Horizontal orientation.

center :: Position orientation Source #

Alignment of cells at characters

data AlignSpec Source #

Determines whether a column will align at a specific letter.


Default AlignSpec Source #

No alignment is the default.


def :: AlignSpec #

noAlign :: AlignSpec Source #

Don't align text.

charAlign :: Char -> AlignSpec Source #

Align text at the first occurence of a given Char.

predAlign :: (Char -> Bool) -> AlignSpec Source #

Align at the first match of a predicate.

dotAlign :: AlignSpec Source #

Align all text at the first dot from the left. This is most useful for floating point numbers.

Cut marks

data CutMark Source #

Specifies how the place looks where a String has been cut. Note that the cut mark may be cut itself, to fit into a column.


Default CutMark Source #

A single ellipsis unicode character is used to show cut marks.


def :: CutMark #

noCutMark :: CutMark Source #

Don't show any cut mark when text is cut.

singleCutMark :: String -> CutMark Source #

Use the cut mark on both sides by reversing it on the other.

doubleCutMark :: String -> String -> CutMark Source #

Specify two different cut marks, one for cuts on the left and one for cuts on the right.

ellipsisCutMark :: CutMark Source #

Deprecated: Use def instead.

Basic grid layout

type Row a = [a] Source #

An alias for lists, conceptually for values with a horizontal arrangement.

grid :: [ColSpec] -> [Row String] -> [Row String] Source #

Modifies cells according to the column specification.

gridLines :: [ColSpec] -> [Row String] -> [String] Source #

Behaves like grid but produces lines by joining with whitespace.

gridString :: [ColSpec] -> [Row String] -> String Source #

Behaves like gridLines but produces a string by joining with the newline character.

Grid modification functions

altLines :: [a -> b] -> [a] -> [b] Source #

Applies functions to given lines in a alternating fashion. This makes it easy to color lines to improve readability in a row.

checkeredCells :: (a -> b) -> (a -> b) -> [[a]] -> [[b]] Source #

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.

Table layout

Grouping rows

data RowGroup Source #

Groups rows together, which should not be visually seperated from each other.

rowsG :: [Row String] -> RowGroup Source #

Group the given rows together.

rowG :: Row String -> RowGroup Source #

Make a group of a single row.

colsG :: [Position V] -> [Col String] -> RowGroup Source #

Create a RowGroup by aligning the columns vertically. The position is specified for each column.

colsAllG :: Position V -> [Col String] -> RowGroup Source #

Create a RowGroup by aligning the columns vertically. Each column uses the same vertical positioning.


data HeaderColSpec Source #

Specifies how a header is rendered.


Default HeaderColSpec Source #

Header columns are usually centered.


def :: HeaderColSpec #

headerColumn :: Position H -> Maybe CutMark -> HeaderColSpec Source #

Smart constructor for HeaderColSpec. By omitting the cut mark it will use the one specified in the ColSpec like the other cells in that column.

data Header Source #

Specifies a header.


Default Header Source #

No header is used by default.


def :: Header #

fullH :: [HeaderColSpec] -> [String] -> Header Source #

Specify a header column for every title.

titlesH :: [String] -> Header Source #

Use titles with the default header column specification.


tableLines Source #


:: [ColSpec]

Layout specification of columns

-> TableStyle

Visual table style

-> Header

Optional header details

-> [RowGroup]

Rows which form a cell together

-> [String] 

Layouts a good-looking table with an optional header. Note that specifying fewer layout specifications than columns or vice versa will result in not showing the redundant ones.

tableString Source #


:: [ColSpec]

Layout specification of columns

-> TableStyle

Visual table style

-> Header

Optional header details

-> [RowGroup]

Rows which form a cell together

-> String 

Does the same as tableLines, but concatenates lines.

Text justification

Text can easily be justified and distributed over multiple lines. Such columns can easily be combined with other columns.

justify :: Int -> [String] -> [String] Source #

Fits as many words on a line, depending on the given width. Every line, but the last one, gets equally filled with spaces between the words, as far as possible.

justifyText :: Int -> String -> [String] Source #

Uses words to split the text into words and justifies it with justify.

>>> justifyText 10 "This text will not fit on one line."
["This  text","will   not","fit on one","line."]

Vertical column positioning

type Col a = [a] Source #

An alias for lists, conceptually for values with a vertical arrangement.

colsAsRowsAll :: Position V -> [Col [a]] -> [Row [a]] Source #

Merges multiple columns together and merges them to a valid grid without holes. The following example clarifies this:

>>> colsAsRowsAll top [justifyText 10 "This text will not fit on one line.", ["42", "23"]]
[["This  text","42"],["will   not","23"],["fit on one",""],["line.",""]]

The result is intended to be used with a grid layout function like layoutToCells.

colsAsRows :: [Position V] -> [Col [a]] -> [Row [a]] Source #

Works like colsAsRowsAll, but every position can be specified on its own:

>>> colsAsRows [top, center, bottom] [["a1"], ["b1", "b2", "b3"], ["c3"]]

data V Source #

Vertical orientation

Table styles

Column modification functions

pad :: Position o -> Int -> String -> String Source #

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       "

trimOrPad :: Position o -> CutMark -> Int -> String -> String Source #

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.."

align :: OccSpec -> AlignInfo -> String -> String Source #

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

alignFixed :: Position o -> CutMark -> Int -> OccSpec -> AlignInfo -> String -> String Source #

Aligns a String using a fixed width, fitting it to the width by either filling or cutting while respecting the alignment.

Column modifaction primitives

Render your own kind of tables with the following functions.

data ColModInfo Source #

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.

widthCMI :: ColModInfo -> Int Source #

Get the exact width of a ColModInfo after applying it with columnModifier.

unalignedCMI :: ColModInfo -> ColModInfo Source #

Remove alignment from a ColModInfo. This is used to change alignment of headers while using the combined width information.

ensureWidthCMI :: Int -> Position H -> ColModInfo -> ColModInfo Source #

Ensures that the modification provides a minimum width but only if it is not limited.

ensureWidthOfCMI :: String -> Position H -> ColModInfo -> ColModInfo Source #

Ensures that the given String will fit into the modified columns.

columnModifier :: Position H -> CutMark -> ColModInfo -> String -> String Source #

Generates a function which modifies a given String according to Position, CutMark and ColModInfo.

data AlignInfo Source #

Specifies the length before and after an alignment position (including the alignment character).


Monoid AlignInfo Source #

Produce an AlignInfo that is wide enough to hold inputs of both given AlignInfos.

widthAI :: AlignInfo -> Int Source #

The column width when using the AlignInfo.

deriveColModInfos :: [(LenSpec, AlignSpec)] -> [Row String] -> [ColModInfo] Source #

Derive the ColModInfo by using layout specifications and the actual cells of a column.

deriveAlignInfo :: OccSpec -> String -> AlignInfo Source #

Generate the AlignInfo of a cell by using the OccSpec.

data OccSpec Source #

Specifies an occurence of a letter.