kvitable: Key/Value Indexed Table container and formatting library

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Allows creation of a table from a set of of Key+Value Indices. This differs from the standard Map structure in that the Map simply indexes by value but the KVI table indexes by a heterogeneous list of keys along with their associated values. This effectively creates an N-dimensional table, where N=Product(Count(Values[key])). The table contents can be sparse.

This library also provides the ability to format multi-dimensional data in a table presentation. The table is automatically formatted and can be output in a number of different styles (ascii, html, etc.)

Multi-dimensional data is more difficult to represent than simple two-dimensional data; this package provides the ability to select which dimensions should be represented as sub-rows and which dimensions should be represented as sub-columns. See the README for examples


[Skip to Readme]

Properties

Versions 1.0.0.0, 1.0.1.0, 1.0.2.0, 1.0.2.1, 1.0.2.1, 1.0.3.0
Change log CHANGELOG.md
Dependencies base (>=4.12 && <4.19), containers, lucid (>=2.9 && <2.12), microlens (>=0.4 && <0.5), prettyprinter (>=1.7 && <1.8), text [details]
License ISC
Copyright Kevin Quick, 2021-2022
Author Kevin Quick
Maintainer kquick@galois.com
Category Text
Home page https://github.com/kquick/kvitable
Uploaded by KevinQuick at 2023-03-22T16:37:29Z

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for kvitable-1.0.2.1

[back to package description]

The KVITable is similar to a Map, but the keys to the map are a list of Key=Val data. Although the KVITable is perfectly useable as a container in this fashion, the main use of the KVITable is in rendering this data in various configurations; because of this focus, there is no particular attention to other container aspects such as: performance, space usage, etc.

An example table can be created via:

{-# LANGUAGE OverloadedStrings #-}
import qualified Data.Text as T
import Data.KVITable

nestedTable = foldl foldlInsert
              (mempty
                & keyVals .~ [ ("millions",  ["0"])
                             , ("thousands", ["0"])
                             , ("hundreds",  ["0"])
                             , ("tens",      ["0"])
                             , ("ones",      ["0"])
                             ]
              )
              [ ([("millions", T.pack $ show m)
                 ,("thousands", T.pack $ show t)
                 ,("hundreds", T.pack $ show h)
                 ,("tens", T.pack $ show d)
                 ,("ones", T.pack $ show o)],
                  if (o `rem` 2) == 1 then "odd" else "even")
              | m <- [0..2 :: Int]
              , t <- [0..2 :: Int]
              , h <- [1..2 :: Int]
              , d <- [2..2 :: Int]
              , o <- [0..1 :: Int]
              ]

This Haskell code generates a table where the keys are the various scale indicators along with a corresponding key value. The table entries themselves are the words odd or even.

Rendering this table in ASCII mode, with blank rows and columns hidden, and enabling column stacking at the "hundreds" key column can be done with the following code:

import Data.KVITable.Render.ASCII

render (defaultRenderConfig { sortKeyVals   = True
                            , rowRepeat     = False
                            , hideBlankCols = True
                            , hideBlankRows = True
                            , equisizedCols = False
                            , colStackAt    = Just "hundreds"
                            }) nestedTable

The output from this rendering will look like:

____ snip vv ____
| millions | thousands | ___ 1 ____ | ___ 2 ____ | <- hundreds
|          |           | ___ 2 ____ | ___ 2 ____ | <- tens
|          |           |    0 |   1 |    0 |   1 | <- ones
+----------+-----------+------+-----+------+-----+
|        0 |         0 | even | odd | even | odd |
|          |         1 | even | odd | even | odd |
|          |         2 | even | odd | even | odd |
|        1 |         0 | even | odd | even | odd |
|          |         1 | even | odd | even | odd |
|          |         2 | even | odd | even | odd |
|        2 |         0 | even | odd | even | odd |
|          |         1 | even | odd | even | odd |
|          |         2 | even | odd | even | odd |
____ snip ^^ ____

When rendered to HTML instead by using the same code but importing Data.KVITable.Render.HTML (and please use a little CSS to make things prettier), the following is obtained:


millions thousands 1 2  ←hundreds
2 2  ←tens
0 1 0 1  ←ones
0 0 even odd even odd
1 even odd even odd
2 even odd even odd
1 0 even odd even odd
1 even odd even odd
2 even odd even odd
2 0 even odd even odd
1 even odd even odd
2 even odd even odd

Different ColStack specification

By changing the colStackAt specification in the rendering configuration from the "hundreds" column to the "thousands" column, the column at which Key Val's are shown as column headers instead of rows is changed and the following ASCII results are obtained:

____ snip vv ____
| millions | __________ 0 __________ | __________ 1 __________ | __________ 2 __________ | <- thousands
|          | ___ 1 ____ | ___ 2 ____ | ___ 1 ____ | ___ 2 ____ | ___ 1 ____ | ___ 2 ____ | <- hundreds
|          | ___ 2 ____ | ___ 2 ____ | ___ 2 ____ | ___ 2 ____ | ___ 2 ____ | ___ 2 ____ | <- tens
|          |    0 |   1 |    0 |   1 |    0 |   1 |    0 |   1 |    0 |   1 |    0 |   1 | <- ones
+----------+------+-----+------+-----+------+-----+------+-----+------+-----+------+-----+
|        0 | even | odd | even | odd | even | odd | even | odd | even | odd | even | odd |
|        1 | even | odd | even | odd | even | odd | even | odd | even | odd | even | odd |
|        2 | even | odd | even | odd | even | odd | even | odd | even | odd | even | odd |
____ snip ^^ ____

or as HTML:


millions 0 1 2  ←thousands
1 2 1 2 1 2  ←hundreds
2 2 2 2 2 2  ←tens
0 1 0 1 0 1 0 1 0 1 0 1  ←ones
0 even odd even odd even odd even odd even odd even odd
1 even odd even odd even odd even odd even odd even odd
2 even odd even odd even odd even odd even odd even odd

No column stacking

Alternatively, the colStackAt rendering configuration parameter may be specified as Nothing, indicating that all Key Val values are to be specified on separate rows, with no stacked columns. The ASCII form of this is:

____ snip vv ____
| millions | thousands | hundreds | tens | ones | Value |
+----------+-----------+----------+------+------+-------+
|        0 |         0 |        1 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |           |        2 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |         1 |        1 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |           |        2 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |         2 |        1 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |           |        2 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|        1 |         0 |        1 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |           |        2 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |         1 |        1 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |           |        2 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |         2 |        1 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |           |        2 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|        2 |         0 |        1 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |           |        2 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |         1 |        1 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |           |        2 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |         2 |        1 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
|          |           |        2 |    2 |    0 |  even |
|          |           |          |      |    1 |   odd |
____ snip ^^ ____

and the HTML form is


millions thousands hundreds tens ones Value
0 0 1 2 0 even
1 odd
2 2 0 even
1 odd
1 1 2 0 even
1 odd
2 2 0 even
1 odd
2 1 2 0 even
1 odd
2 2 0 even
1 odd
1 0 1 2 0 even
1 odd
2 2 0 even
1 odd
1 1 2 0 even
1 odd
2 2 0 even
1 odd
2 1 2 0 even
1 odd
2 2 0 even
1 odd
2 0 1 2 0 even
1 odd
2 2 0 even
1 odd
1 1 2 0 even
1 odd
2 2 0 even
1 odd
2 1 2 0 even
1 odd
2 2 0 even
1 odd

More examples can be found in the examples subdirectory, including: