table-layout 0.8.0.3 → 0.8.0.4

raw patch · 8 files changed

+49/−38 lines, 8 filesdep ~QuickCheck

Dependency ranges changed: QuickCheck

Files

• README.md +22/−14
• src/Text/Layout/Table.hs +11/−8
• src/Text/Layout/Table/Internal.hs +1/−1
• src/Text/Layout/Table/Justify.hs +3/−3
• src/Text/Layout/Table/Position/Internal.hs +1/−1
• src/Text/Layout/Table/Primitives/Basic.hs +1/−1
• src/Text/Layout/Table/Vertical.hs +3/−4
• table-layout.cabal +7/−6

@@ -1,23 +1,29 @@-# table-layout+# table-layout [![Hackage version](https://img.shields.io/hackage/v/table-layout.svg?label=Hackage)](https://hackage.haskell.org/package/table-layout)  This package can be used to render character-based table layouts which should be displayed with monospace fonts.  ## Purpose -The focus of this library lies on rendering cells with different styles per column. Columns can be fixed in size or expanding to make content fit. Whenever content has to be cut, it is possible to indicate this with special strings (these are called cut marks). Columns can be positionally aligned as left, right or center and additionally aligned at certain character occurences, e.g. to display floating point numbers. Those specifications are then applied to a list of rows (currently only `String` is supported).+The focus of this library lies on rendering cells with different styles per column:+* Columns can be fixed in size or expanding to make content fit.+* Whenever content has to be cut, it is possible to indicate this with special strings, which are called cut marks.+* Columns can be positionally aligned as `left`, `right` or `center`.+* Columns may also be aligned at certain character occurence with respect to the other cells of that column. One such purpose is to display floating point numbers. -Typically cells are rendered as a grid, but it is also possible to render tables with simulated lines, including styling support. Such tables can use optional headers and multiple lines per cell. Multi-line content can be aligned vertically and text can be rendered justified.+Those specifications are then applied to a list of rows (currently only `String` is supported). +Typically cells are rendered as a grid, but it is also possible to render tables with simulated lines, including styling support. Such tables can use optional headers and multiple lines per cell. Multi-line content can be aligned vertically, with respect to the other horizontally adjacent cells, and text can be rendered justified.+ ## Tutorial  ### Grid layout  Render some text rows as grid: ``` hs-putStrLn $ gridString [column expand left def def, column expand right def def]-                      [ ["top left", "top right"]-                      , ["bottom left", "bottom right"]-                      ]+> putStrLn $ gridString [column expand left def def, column expand right def def]+                        [ ["top left", "top right"]+                        , ["bottom left", "bottom right"]+                        ] ``` `gridString` will join cells with a whitespace and rows with a newline character. The result is not spectacular but does look as expected: ```@@ -30,28 +36,30 @@  Additionally some common types are provided. A particularly useful one is `numCol`: ``` hs-mapM_ putStrLn $ gridLines [numCol] (map ((: []) . show) [1.2, 100.5, 0.037, 5000.00001])+> import Numeric+> let toRow d = [showFFloat Nothing d ""]+> mapM_ putStrLn $ gridLines [numCol] $ toRow <$> [1.2, 100.5, 0.037, 5000.00001] ``` This will display the given numbers as a dot-aligned single column: ```    1.2      100.5    -   3.7e-2 +   0.037 5000.00001 ```  ### Improving readability of grids -Big grids are usually not that readable, so to improve their readability two functions are provided:+Big grids are usually not that readable. To improve their readability, two functions are provided: -- `altLines` will alternate functions applied to lines.-- `checkeredCells` will checker cells with 2 different functions.+* `altLines` will apply the given function in an alternating pattern. E.g., color every second row grey.+* `checkeredCells` will checker cells with 2 different functions.  A good way to use this would be the [ansi-terminal package][], provided you are using a terminal to output your text.  ### Table layout -Grids are fine, but sometimes we want to explicitly display a table, e.g., as output in a database application. This is where ```tableString``` comes in handy:+For more complex data grids do not offer as much visibility. Sometimes we want to explicitly display a table, e.g., as output in a database application. `tableLines` and `tableString` are used to create a table.  ``` hs putStrLn $ tableString [def , numCol]@@ -61,7 +69,7 @@                        , rowG ["Jane", "162.2"]                        ] ```-A row group is a group of rows which form one cell. This means that each line of a group is not visually seperated from the other ones. In addition we specify the style and an optional header (which is not used by default). This will yield the following result:+A row group is a group of rows which form one cell. This means that each line of a group is not visually seperated from the other ones. In addition we specify the style and an optional header. By default the header is not visible. This will yield the following result:  ``` ╭──────┬────────╮

@@ -93,7 +93,8 @@     , alignFixed        -- * Column modifaction primitives-      -- | Render your own kind of tables with the following functions.+      -- | These functions are provided to be reused. For example if someone+      -- wants to render their own kind of tables.     , ColModInfo     , widthCMI     , unalignedCMI@@ -364,8 +365,10 @@ ensureWidthOfCMI :: String -> Position H -> ColModInfo -> ColModInfo ensureWidthOfCMI = ensureWidthCMI . length --- | Generates a function which modifies a given 'String' according to--- 'Text.Layout.Table.Position.Position', 'CutMark' and 'ColModInfo'.+-- | 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@@ -482,7 +485,7 @@     = Header [HeaderColSpec] [String]     | NoHeader --- | No header is used by default.+-- | By the default the header is not shown. instance Default Header where     def = NoHeader @@ -494,9 +497,9 @@ titlesH :: [String] -> Header titlesH = fullH $ repeat def --- | 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.+-- | 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@@ -572,4 +575,4 @@  -- $justify -- Text can easily be justified and distributed over multiple lines. Such--- columns can easily be combined with other columns.+-- columns can be combined with other columns.

@@ -6,7 +6,7 @@ import Text.Layout.Table.Position import Text.Layout.Table.Primitives.Basic --- | Groups rows together, which should not be visually seperated from each other.+-- | Groups rows together which should not be visually seperated from each other. newtype RowGroup     = RowGroup     { rows :: [[String]]

@@ -28,9 +28,9 @@ justifyText :: Int -> String -> [String] justifyText w = justify w . words --- | 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.+-- | 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. justify :: Int -> [String] -> [String] justify width = mapInit pad (\(_, _, line) -> unwords line) . gather 0 0 []   where

@@ -29,7 +29,7 @@ -- | Horizontal orientation. data H --- | Vertical orientation+-- | Vertical orientation. data V  left :: Position H

@@ -41,7 +41,7 @@ import Data.List  -- | 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.+-- cut mark may be cut itself to fit into a column. data CutMark     = CutMark     { leftMark  :: String

@@ -14,18 +14,17 @@ import Text.Layout.Table.Position.Internal import Text.Layout.Table.Primitives.Basic -{- | Merges multiple columns together and merges them to a valid grid without-   holes. The following example clarifies this:+{- | 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 'Text.Layout.Table.layoutToCells'.+The result is intended to be used with a grid layout function like 'Text.Layout.Table.grid'. -} colsAsRowsAll :: Position V -> [Col [a]] -> [Row [a]] colsAsRowsAll ps = transpose . vPadAll [] ps -{- | Works like 'colsAsRowsAll', but every position can be specified on its+{- | Works like 'colsAsRowsAll' but every position can be specified on its    own:  >>> colsAsRows [top, center, bottom] [["a1"], ["b1", "b2", "b3"], ["c3"]]

@@ -6,14 +6,15 @@ -- PVP summary:      +-+------- breaking API changes --                   | | +----- non-breaking API additions --                   | | | +--- code changes with no API change-version:             0.8.0.3+version:             0.8.0.4  synopsis:            Layout text as grid or table.  description:         -    `table-layout` is a library for text-based table layout, it provides several-    functions and types which help in this task from the ground up, although-    using them is not necessary. It provides the following layout features:+    `table-layout` is a library for text-based table layout. It provides several+    functions and types which help in this task from the ground up. Although,+    using all of them is not necessary. It provides the following layout+    features:     .     * Fixed-size and arbitrarily sized columns and limiting versions of those     .@@ -25,7 +26,7 @@     .     * Fancy tables with optional headers and user styles     .-    * Justified text layout over multiple rows+    * Justified text and vertically aligned column layout over multiple rows     .     A small tutorial is provided in the `README.md` file. @@ -112,7 +113,7 @@   hs-source-dirs:      test-suite, src   main-is:             Spec.hs   build-depends:       base >=4.8 && <4.13,-                       QuickCheck >=2.8 && < 2.12,+                       QuickCheck >=2.8 && < 2.13,                        HUnit >=1.3,                        data-default-class >=0.1.1 && < 0.2,                        data-default-instances-base ==0.1.*,