Text.Layout.Table

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.

module Data.Default.Class

Columns

data ColSpec

Specifies the layout of a column.

Instances

Default ColSpec

Defined in Text.Layout.Table.Spec.ColSpec

Methods

def :: ColSpec

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

Smart constructor to specify a column.

numCol :: ColSpec

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

fixedCol :: Int -> Position H -> ColSpec

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

fixedLeftCol :: Int -> ColSpec

Fixes the column length and positions on the left.

Length of columns

data LenSpec

Determines how long a column will be.

Instances

Default LenSpec

Defined in Text.Layout.Table.Spec.LenSpec

Methods

def :: LenSpec

expand :: LenSpec

Allows columns to use as much space as needed.

fixed :: Int -> LenSpec

Fixes column length to a specific width.

expandUntil :: Int -> LenSpec

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

fixedUntil :: Int -> LenSpec

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

Positional alignment

data Position orientation

Specifies a position relative from a beginning.

Instances

Eq (Position orientation)

Defined in Text.Layout.Table.Spec.Position

Methods

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

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

Show (Position V)

Defined in Text.Layout.Table.Spec.Position

Methods

showsPrec :: Int -> Position V -> ShowS

show :: Position V -> String

showList :: [Position V] -> ShowS

Show (Position H)

Defined in Text.Layout.Table.Spec.Position

Methods

showsPrec :: Int -> Position H -> ShowS

show :: Position H -> String

showList :: [Position H] -> ShowS

Default (Position orientation)

Defined in Text.Layout.Table.Spec.Position

Methods

def :: Position orientation

data H

Horizontal orientation.

Instances

Show (Position H)

Defined in Text.Layout.Table.Spec.Position

Methods

showsPrec :: Int -> Position H -> ShowS

show :: Position H -> String

showList :: [Position H] -> ShowS

left :: Position H

right :: Position H

center :: Position orientation

Alignment of cells at characters

data AlignSpec

Determines whether a column will align at a specific letter.

Instances

Default AlignSpec

No alignment is the default.

Defined in Text.Layout.Table.Spec.AlignSpec

Methods

def :: AlignSpec

noAlign :: AlignSpec

Don't align text.

charAlign :: Char -> AlignSpec

Align text at the first occurence of a given Char.

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

Align at the first match of a predicate.

dotAlign :: AlignSpec

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

Cut marks

data CutMark

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.

Instances

Default CutMark

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

Defined in Text.Layout.Table.Spec.CutMark

Methods

def :: CutMark

noCutMark :: CutMark

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

singleCutMark :: String -> CutMark

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

doubleCutMark :: String -> String -> CutMark

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

Basic grid layout

type Row a = [a]

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

grid :: Cell a => [ColSpec] -> [Row a] -> [Row String]

Modifies cells according to the column specification.

gridLines :: Cell a => [ColSpec] -> [Row a] -> [String]

Behaves like grid but produces lines by joining with whitespace.

gridString :: Cell a => [ColSpec] -> [Row a] -> String

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

concatRow :: StringBuilder b => Int -> Row b -> b

Concatenates a row with a given amount of spaces.

concatLines :: StringBuilder b => [b] -> b

concatGrid :: StringBuilder b => Int -> [Row b] -> b

Grid modification functions

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

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]]

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 a

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

rowsG :: [Row a] -> RowGroup a

Group the given rows together.

rowG :: Row a -> RowGroup a

Make a group of a single row.

colsG :: Monoid a => [Position V] -> [Col a] -> RowGroup a

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

colsAllG :: Monoid a => Position V -> [Col a] -> RowGroup a

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

Headers

data HeaderColSpec

Specifies how a header is rendered.

Instances

Default HeaderColSpec

Header columns are usually centered.

Defined in Text.Layout.Table.Spec.HeaderColSpec

Methods

def :: HeaderColSpec

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

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 HeaderSpec

Specifies a header.

Instances

Default HeaderSpec

By the default the header is not shown.

Defined in Text.Layout.Table.Spec.HeaderSpec

Methods

def :: HeaderSpec

fullH :: [HeaderColSpec] -> [String] -> HeaderSpec

Specify a header column for every title.

titlesH :: [String] -> HeaderSpec

Use titles with the default header column specification.

Layout

tableLines

Arguments

:: Cell a

=> [ColSpec]

Layout specification of columns

-> TableStyle

Visual table style

-> HeaderSpec

Optional header details

-> [RowGroup a]

Rows which form a cell together

-> [String]

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.

tableString

Arguments

:: Cell a

=> [ColSpec]

Layout specification of columns

-> TableStyle

Visual table style

-> HeaderSpec

Optional header details

-> [RowGroup a]

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 be combined with other columns.

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

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

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

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]

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

colsAsRowsAll :: Monoid a => Position V -> [Col a] -> [Row a]

Merges multiple columns together to a valid grid without holes. For example:

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

colsAsRows :: Monoid a => [Position V] -> [Col a] -> [Row a]

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

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

top :: Position V

bottom :: Position V

data V

Vertical orientation.

Instances

Show (Position V)

Defined in Text.Layout.Table.Spec.Position

Methods

showsPrec :: Int -> Position V -> ShowS

show :: Position V -> String

showList :: [Position V] -> ShowS

Table styles

module Text.Layout.Table.Style

Column modification functions

pad :: (Cell a, StringBuilder b) => Position o -> Int -> a -> b

Assume the given length is greater or equal than the length of the cell passed. Pads the given cell accordingly using the position specification.

>>> pad left 10 "foo" :: String
"foo       "

trimOrPad :: (Cell a, StringBuilder b) => Position o -> CutMark -> Int -> a -> b

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." :: String
"A longer.."

align :: (Cell a, StringBuilder b) => OccSpec -> AlignInfo -> a -> b

Align a cell 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"] :: [String]
["   1.5  ","  30    ","    .25 "]

This function assumes that the given String fits the AlignInfo. Thus:

ai <> deriveAlignInfo s = ai

alignFixed :: (Cell a, StringBuilder b) => Position o -> CutMark -> Int -> OccSpec -> AlignInfo -> a -> b

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

Column modifaction primitives

These functions are provided to be reused. For example if someone wants to render their own kind of tables.

data ColModInfo

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

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

unalignedCMI :: ColModInfo -> ColModInfo

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

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

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

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

columnModifier :: (Cell a, StringBuilder b) => Position H -> CutMark -> ColModInfo -> a -> b

Generates a function which modifies a given cell according to Position, CutMark and ColModInfo. This is used to modify a single cell of a column to bring all cells of a column to the same width.

data AlignInfo

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

Instances

Semigroup AlignInfo

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

Defined in Text.Layout.Table.Primitives.AlignInfo

Methods

(<>) :: AlignInfo -> AlignInfo -> AlignInfo

sconcat :: NonEmpty AlignInfo -> AlignInfo

stimes :: Integral b => b -> AlignInfo -> AlignInfo

Monoid AlignInfo

Defined in Text.Layout.Table.Primitives.AlignInfo

Methods

mempty :: AlignInfo

mappend :: AlignInfo -> AlignInfo -> AlignInfo

mconcat :: [AlignInfo] -> AlignInfo

widthAI :: AlignInfo -> Int

The column width when using the AlignInfo.

deriveColModInfos :: Cell a => [(LenSpec, AlignSpec)] -> [Row a] -> [ColModInfo]

Derive the ColModInfo by using layout specifications and the actual cells of a column. This function only needs to know about LenSpec and AlignInfo.

deriveAlignInfo :: Cell a => OccSpec -> a -> AlignInfo

Generate the AlignInfo of a cell by using the OccSpec.

data OccSpec

Specifies an occurence of a letter.