-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Key/Value Indexed Table container and formatting library
--
-- 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
@package kvitable
@version 1.0.2.1
-- | The KVITable is similar to a Map, but the keys for a
-- KVITable are made up of sequences of Key=Val values.
-- The primary use of a KVITable is for rendering the information
-- in various configurations and formats, although it may be used like
-- any other container.
module Data.KVITable
-- | The core KeyValue Indexed Table. This table is similar to a Map, but
-- the values are indexed by a list of Key+Value combinations, and the
-- table contents can be sparse.
data KVITable v
KVITable :: KeyVals -> (Key -> KeyVal) -> Map KeySpec v -> Text -> KVITable v
-- | The Key is the first half of a tuple that makes up the list of
-- keys (the KeySpec). The second half is the KeyVal.
type Key = Text
-- | The KeyVal is the first half of a tuple that makes up the list
-- of keys (the KeySpec). The first half is the Key.
type KeyVal = Text
-- | The KeyVals specifies all valid values for a particular
-- Key in the KVITable. The set of KeyVals can be
-- provided at the initialization of the KVITable to ensure
-- specific values are considered (especially if rendering includes blank
-- rows or columns); if entries are added to the table with a
-- KeyVal previously unknown for the Key, the
-- KeyVals for the table is automatically updated to include the
-- new KeyVal.
type KeyVals = [(Key, [KeyVal])]
-- | The KeySpec is the list of tuples and defines the unique key
-- for a value in the KVITable.
type KeySpec = [(Key, KeyVal)]
-- | Converts a list of ([(Key,Val)], Value) tuples to a KVI
-- table.
fromList :: [Item (KVITable v)] -> KVITable v
-- | Converts a KVI table to a list of ([(Key,Val)], Value)
-- tuples.
toList :: KVITable v -> [Item (KVITable v)]
-- | Retrieve an entry from the KVITable given a keyspec. The keyspec may
-- be minimally specified (i.e. it does not need to contain keys whose
-- value is the default key value) and it may present the keys out of
-- order and the lookup will still succeed (if there is a value for the
-- normalized keyspec), but it will be faster to use the normalized key
-- directly.
lookup :: KeySpec -> KVITable v -> Maybe v
-- | Fetch or set the keyvals list via lenses. Note that setting the keyval
-- list will drop any current contents in the table that do not have
-- entries in the keyvals list.
keyVals :: Lens' (KVITable v) KeyVals
-- | Fetch or set the default KeyVal generator for this
-- KVITable
keyValGen :: Lens' (KVITable v) (Key -> KeyVal)
-- | Fetch or set the column name for the actual value cell in the
-- KVITable.
valueColName :: Lens' (KVITable v) Text
-- | Inserts a new cell value into the table at the specified keyspec
-- location. The keyspec may be minimally specified and out-of-order.
--
-- This may be an expensive operation if it has to extend the keyvals for
-- the table. In general, insertion is expected to be less frequent than
-- lookups so computation costs are biased towards the insertion
-- operation.
insert :: KeySpec -> v -> KVITable v -> KVITable v
-- | The foldlInsert is a convenience function that can be specified as the
-- function argument of a foldl operation over the list form of a
-- KVITable to generate the associated KVITable.
foldlInsert :: KVITable v -> (KeySpec, v) -> KVITable v
-- | Filter KVITable to retain only the elements that satisfy some
-- predicate.
filter :: ((KeySpec, v) -> Bool) -> KVITable v -> KVITable v
-- | Adjust a value at the specified keyspec; return the original
-- KVITable if that keyspec is not found in the table.
adjust :: (v -> v) -> KeySpec -> KVITable v -> KVITable v
-- | Adjust a value at the specified keyspec; return the original
-- KVITable if that keyspec is not found in the table.
adjustWithKey :: (KeySpec -> v -> v) -> KeySpec -> KVITable v -> KVITable v
-- | Delete the value at the specified keyspec location in the
-- KVITable. If the keyspec does not exist, the original table is
-- returned.
delete :: KeySpec -> KVITable v -> KVITable v
-- | Update the KVITable to remove or set a new value for the
-- specified entry if the updating function returns Nothing or
-- Just v, respectively. The update function is passed the value
-- for the keyspec to be updated. If the value does not exist in the
-- table, the original table is returned.
update :: (v -> Maybe v) -> KeySpec -> KVITable v -> KVITable v
-- | Update the KVITable to remove or set a new value for the
-- specified entry if the updating function returns Nothing or
-- Just v, respectively. The update function is passed both the
-- keyspec and the current value at that key. If the value does not exist
-- in the table, the original table is returned.
updateWithKey :: (KeySpec -> v -> Maybe v) -> KeySpec -> KVITable v -> KVITable v
-- | The rows function returns a set of rows for the KVITable
-- as a list structure, where each list entry is a different row. A row
-- consists of the values of the keys for that row followed by the
-- value of the entry (to get the names of the keys, use keyVals).
rows :: KVITable v -> [([KeyVal], v)]
instance GHC.Classes.Eq v => GHC.Classes.Eq (Data.KVITable.KVITable v)
instance GHC.Show.Show v => GHC.Show.Show (Data.KVITable.KVITable v)
instance GHC.Base.Semigroup (Data.KVITable.KVITable v)
instance GHC.Base.Monoid (Data.KVITable.KVITable v)
instance GHC.Base.Functor Data.KVITable.KVITable
instance Data.Foldable.Foldable Data.KVITable.KVITable
instance Data.Traversable.Traversable Data.KVITable.KVITable
instance GHC.Exts.IsList (Data.KVITable.KVITable v)
-- | Common definitions (and support functions) for rendering a
-- KVITable.
module Data.KVITable.Render
-- | The RenderConfig specifies the various controls and
-- configurations used when rendering a KVITable in various
-- formats. The RenderConfig is global t oall formats, although
-- some of the fields in the RenderConfig will be ignored as
-- not-applicable by some formats.
data RenderConfig
RenderConfig :: Bool -> Bool -> Bool -> Bool -> Maybe Key -> Bool -> [Key] -> Maybe Text -> RenderConfig
-- | True (default) removes rows for which there are no values
[hideBlankRows] :: RenderConfig -> Bool
-- | True (default) removes columns for which there are no values
[hideBlankCols] :: RenderConfig -> Bool
-- | True (default) to maintain a consistent column width, otherwise
-- the columns are shunk to the minimum size needed to display the title
-- and values. Not applicable for some backends (e.g. HTML) where the
-- backend provides table rendering functionality.
[equisizedCols] :: RenderConfig -> Bool
-- | True (default is False) to sort the KeyVal entries when
-- rendering a table.
[sortKeyVals] :: RenderConfig -> Bool
-- | Column key to begin stacking keys in columns and sub-columns rather
-- than creating additional sub-rows.
[colStackAt] :: RenderConfig -> Maybe Key
-- | True (default) if an identical KeyVal is to be repeated
-- in subsequent applicable rows.
[rowRepeat] :: RenderConfig -> Bool
-- | List of Key names that should by grouped by inserting horizontal row
-- lines between KeyVals
[rowGroup] :: RenderConfig -> [Key]
-- | Caption to render for table for backends which support captions;
-- otherwise ignored.
[caption] :: RenderConfig -> Maybe Text
-- | Returns the default rendering configuration, to be used with a
-- format-specific render call.
defaultRenderConfig :: RenderConfig
-- | Sorting for KeyVals. If the value starts or ends with a digit, then
-- this should do a rough numeric sort on the expectation that the digits
-- represent a version or some other numeric value. As an approximation
-- of a numeric sort, sort by word size and then string value. This will
-- result in [ "1", "2", "10", "50", "400" ], but would fail with [
-- "v1.0", "v2.0", "v3.0", "v2.0.5", "v1.0.0.3" ], but it's a reasonably
-- fast heuristic and probably better than a straight ascii sort.
--
-- This function is used by the KVITable rendering functions.
sortWithNums :: [KeyVal] -> [KeyVal]
-- | This module provides the KVITable render function for
-- rendering the table in a plain ASCII format.
module Data.KVITable.Render.ASCII
-- | Renders the specified table in ASCII format, using the specified
-- RenderConfig controls.
render :: Pretty v => RenderConfig -> KVITable v -> Text
-- | The RenderConfig specifies the various controls and
-- configurations used when rendering a KVITable in various
-- formats. The RenderConfig is global t oall formats, although
-- some of the fields in the RenderConfig will be ignored as
-- not-applicable by some formats.
data RenderConfig
RenderConfig :: Bool -> Bool -> Bool -> Bool -> Maybe Key -> Bool -> [Key] -> Maybe Text -> RenderConfig
-- | True (default) removes rows for which there are no values
[hideBlankRows] :: RenderConfig -> Bool
-- | True (default) removes columns for which there are no values
[hideBlankCols] :: RenderConfig -> Bool
-- | True (default) to maintain a consistent column width, otherwise
-- the columns are shunk to the minimum size needed to display the title
-- and values. Not applicable for some backends (e.g. HTML) where the
-- backend provides table rendering functionality.
[equisizedCols] :: RenderConfig -> Bool
-- | True (default is False) to sort the KeyVal entries when
-- rendering a table.
[sortKeyVals] :: RenderConfig -> Bool
-- | Column key to begin stacking keys in columns and sub-columns rather
-- than creating additional sub-rows.
[colStackAt] :: RenderConfig -> Maybe Key
-- | True (default) if an identical KeyVal is to be repeated
-- in subsequent applicable rows.
[rowRepeat] :: RenderConfig -> Bool
-- | List of Key names that should by grouped by inserting horizontal row
-- lines between KeyVals
[rowGroup] :: RenderConfig -> [Key]
-- | Caption to render for table for backends which support captions;
-- otherwise ignored.
[caption] :: RenderConfig -> Maybe Text
-- | Returns the default rendering configuration, to be used with a
-- format-specific render call.
defaultRenderConfig :: RenderConfig
-- | This module provides the KVITable render function for
-- rendering the table in a HTML table format. The various HTML table
-- entries have class designators that allow the user to provide CSS to
-- adjust the appearance of the table.
module Data.KVITable.Render.HTML
-- | Renders the specified table in HTML format, using the specified
-- RenderConfig controls. The output is only the
-- table definition; it is intended to be embedded in a
-- larger HTML document.
render :: Pretty v => RenderConfig -> KVITable v -> Text
-- | The RenderConfig specifies the various controls and
-- configurations used when rendering a KVITable in various
-- formats. The RenderConfig is global t oall formats, although
-- some of the fields in the RenderConfig will be ignored as
-- not-applicable by some formats.
data RenderConfig
RenderConfig :: Bool -> Bool -> Bool -> Bool -> Maybe Key -> Bool -> [Key] -> Maybe Text -> RenderConfig
-- | True (default) removes rows for which there are no values
[hideBlankRows] :: RenderConfig -> Bool
-- | True (default) removes columns for which there are no values
[hideBlankCols] :: RenderConfig -> Bool
-- | True (default) to maintain a consistent column width, otherwise
-- the columns are shunk to the minimum size needed to display the title
-- and values. Not applicable for some backends (e.g. HTML) where the
-- backend provides table rendering functionality.
[equisizedCols] :: RenderConfig -> Bool
-- | True (default is False) to sort the KeyVal entries when
-- rendering a table.
[sortKeyVals] :: RenderConfig -> Bool
-- | Column key to begin stacking keys in columns and sub-columns rather
-- than creating additional sub-rows.
[colStackAt] :: RenderConfig -> Maybe Key
-- | True (default) if an identical KeyVal is to be repeated
-- in subsequent applicable rows.
[rowRepeat] :: RenderConfig -> Bool
-- | List of Key names that should by grouped by inserting horizontal row
-- lines between KeyVals
[rowGroup] :: RenderConfig -> [Key]
-- | Caption to render for table for backends which support captions;
-- otherwise ignored.
[caption] :: RenderConfig -> Maybe Text
-- | Returns the default rendering configuration, to be used with a
-- format-specific render call.
defaultRenderConfig :: RenderConfig
instance GHC.Show.Show Data.KVITable.Render.HTML.FmtVal
instance GHC.Base.Semigroup Data.KVITable.Render.HTML.HeaderLine
instance GHC.Base.Semigroup Data.KVITable.Render.HTML.FmtLine
instance GHC.Base.Monoid Data.KVITable.Render.HTML.FmtLine