pptable-0.3.0.0: test/README.lhs
# README #
Textme.PrettyPrint.Tabulate : Print any list, vector or map of records as a well-formatted readable table. Nested record structures are printed with hierarchically arranged headers, thus clearly showing the nested structures.
### Text.PrettyPrint.Tabulate ###
* This module provides simple functions used to print values in tabular format
* Version 0.3.0.0
* Contributions and Bug Reports welcome. Please use the Github issue tracker.
### Release Notes 0.3.0.0 (*This release has breaking changes*)
* This release has some breaking changes which was required to extend
functionality. The extended functionality improves on previous
release by printing nested records with hierarchical column headers
* All Records types need to update their `Tabulate` instances to provide a flag, namely `ExpandWhenNested` or `DoNotExpandWhenNested`.
* `ppTable` function has been renamed to `printTable` to make the function name more descriptive.
* New function called printTableWithFlds has been added.
### Example ###
``` haskell
{-# LANGUAGE MultiParamTypeClasses#-}
{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE DeriveDataTypeable #-}
import Text.PrettyPrint.Tabulate
import qualified GHC.Generics as G
import Data.Data
import qualified Text.PrettyPrint.Tabulate as T
import qualified Data.Map as Map
import qualified Data.List as List
import qualified Data.Vector as Vector
```
#### Instance Declaration Requirements ####
1. All records definitions should `derive` from `Data` and `Generic`
2. All field types that are record attributes should have an instance of `CellValueFormatter`. Default instances for standard types are already provided.
3. All records that need to be printed as a table need to be an instance of `Tabulate`.
4. Depending on if the nested record's fields have to be expanded, the
Tabulate instance could either be
`instance Tabulate Price ExpandWhenNested` or
`instance Tabulate Price DoNotExpandWhenNested`.
``` haskell
data FxCode = USD | EUR | JPY deriving (Show, Data, G.Generic)
instance T.CellValueFormatter FxCode
-- This record type will be nested inside `Stock`
data Price = Price {price::Double, fx_code::FxCode} deriving (Data, G.Generic, Show)
-- if we do not want the `Price` records to be expanded into their own fields
-- then choose `T.DoNotExpandWhenNested`
instance T.Tabulate Price T.ExpandWhenNested
instance T.CellValueFormatter Price
data Stock = Stock {ticker::String, local_price::Price, marketCap::Double} deriving (
Data, G.Generic, Show)
instance T.Tabulate Stock T.ExpandWhenNested
```
Once we have the records and required instances created, we can see how
the created records can be viewed in the tabular format.
``` haskell
yahoo = Stock {ticker="YHOO", local_price=Price 42.29101010 USD, marketCap=40e9}
google = Stock {ticker="GOOG", local_price=Price 774.210101 EUR, marketCap=532.09e9}
amazon = Stock {ticker="AMZN", local_price=Price 799.161717 JPY, marketCap=378.86e9}
tickers = [yahoo, google, amazon]
tickers_vector = Vector.fromList tickers
tickers_map:: Map.Map Integer Stock
tickers_map = Map.fromList [(10, yahoo), (100, google), (1000, amazon)]
printExamples:: IO ()
printExamples = do
putStrLn "Printing records in a list\n"
T.printTable tickers
putStrLn "\nPrinting records in a map with the index.\nNote the `key(s)` are printed as first columns"
T.printTable tickers_map
putStrLn "\nPrinting records in a vector\n"
T.printTable tickers_vector
-- Sometimes records may have too many fields. In those case, specific fields can
-- be chosen to be printed. Currently, support for this functionality is
-- minimal. The 'headers` are not printed. In the future, a function that
-- can take header labels as a list will be provided.
putStrLn "\nPrinting specific fields. Note, currently field names are not printed"
T.printTableWithFlds [T.DFld (price . local_price), T.DFld ticker] tickers_map
putStrLn "\nPrint nested record in a map, individually"
T.printTable $ fmap local_price tickers_map
```
### Print the examples ###
``` haskell
main:: IO ()
main = do
printExamples
```
### Output ###
``` haskell ignore
Printing records in a list
ticker local_price local_price marketCap
- price fx_code -
YHOO 42.2910101 USD 4.0000000e10
GOOG 774.2101010 EUR 5.3209000e11
AMZN 799.1617170 JPY 3.7886000e11
Printing records in a map with the index (Note the `key` is printed as the first column)
- ticker local_price local_price marketCap
- - price fx_code -
10 YHOO 42.2910101 USD 4.0000000e10
100 GOOG 774.2101010 EUR 5.3209000e11
1000 AMZN 799.1617170 JPY 3.7886000e11
Printing records in a vector
ticker local_price local_price marketCap
- price fx_code -
YHOO 42.2910101 USD 4.0000000e10
GOOG 774.2101010 EUR 5.3209000e11
AMZN 799.1617170 JPY 3.7886000e11
Printing specific fields. Note, currently field names are not printed
10 42.2910101 YHOO
100 774.2101010 GOOG
1000 799.1617170 AMZN
```