-- 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 <a>Map</a> structure in that the <a>Map</a>
--   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
--   <tt>N=Product(Count(Values[key]))</tt>. 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.3.0


-- | The <a>KVITable</a> is similar to a <a>Map</a>, but the keys for a
--   <a>KVITable</a> are made up of sequences of <tt>Key=Val</tt> values.
--   The primary use of a <a>KVITable</a> 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 <a>Key</a> is the first half of a tuple that makes up the list of
--   keys (the <a>KeySpec</a>). The second half is the <a>KeyVal</a>.
type Key = Text

-- | The <a>KeyVal</a> is the first half of a tuple that makes up the list
--   of keys (the <a>KeySpec</a>). The first half is the <a>Key</a>.
type KeyVal = Text

-- | The <a>KeyVals</a> specifies all valid values for a particular
--   <a>Key</a> in the <a>KVITable</a>. The set of <a>KeyVals</a> can be
--   provided at the initialization of the <a>KVITable</a> to ensure
--   specific values are considered (especially if rendering includes blank
--   rows or columns); if entries are added to the table with a
--   <a>KeyVal</a> previously unknown for the <a>Key</a>, the
--   <a>KeyVals</a> for the table is automatically updated to include the
--   new <a>KeyVal</a>.
type KeyVals = [(Key, [KeyVal])]

-- | The <a>KeySpec</a> is the list of tuples and defines the unique key
--   for a value in the <a>KVITable</a>.
type KeySpec = [(Key, KeyVal)]

-- | Converts a list of <tt>([(Key,Val)], Value)</tt> tuples to a KVI
--   table.
fromList :: [Item (KVITable v)] -> KVITable v

-- | Converts a KVI table to a list of <tt>([(Key,Val)], Value)</tt>
--   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 <a>KeyVal</a> generator for this
--   <a>KVITable</a>
keyValGen :: Lens' (KVITable v) (Key -> KeyVal)

-- | Fetch or set the column name for the actual value cell in the
--   <a>KVITable</a>.
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 <a>KVITable</a> 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
--   <a>KVITable</a> 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
--   <a>KVITable</a> 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
--   <a>KVITable</a>. If the keyspec does not exist, the original table is
--   returned.
delete :: KeySpec -> KVITable v -> KVITable v

-- | Update the <a>KVITable</a> to remove or set a new value for the
--   specified entry if the updating function returns <tt>Nothing</tt> or
--   <tt>Just v</tt>, 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 <a>KVITable</a> to remove or set a new value for the
--   specified entry if the updating function returns <tt>Nothing</tt> or
--   <tt>Just v</tt>, 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 <a>rows</a> function returns a set of rows for the <a>KVITable</a>
--   as a list structure, where each list entry is a different row. A row
--   consists of the <i>values</i> of the keys for that row followed by the
--   value of the entry (to get the names of the keys, use <a>keyVals</a>).
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.IsList.IsList (Data.KVITable.KVITable v)


-- | Common definitions (and support functions) for rendering a
--   <a>KVITable</a>.
module Data.KVITable.Render

-- | The <a>RenderConfig</a> specifies the various controls and
--   configurations used when rendering a <a>KVITable</a> in various
--   formats. The <a>RenderConfig</a> is global t oall formats, although
--   some of the fields in the <a>RenderConfig</a> will be ignored as
--   not-applicable by some formats.
data RenderConfig
RenderConfig :: Bool -> Bool -> Bool -> Bool -> Maybe Key -> Bool -> [Key] -> Maybe Text -> RenderConfig

-- | <a>True</a> (default) removes rows for which there are no values
[hideBlankRows] :: RenderConfig -> Bool

-- | <a>True</a> (default) removes columns for which there are no values
[hideBlankCols] :: RenderConfig -> Bool

-- | <a>True</a> (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

-- | <a>True</a> (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

-- | <a>True</a> (default) if an identical <a>KeyVal</a> 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 <tt>render</tt> 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 <a>KVITable</a> rendering functions.
sortWithNums :: [KeyVal] -> [KeyVal]


-- | This module provides the <a>KVITable</a> <a>render</a> 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
--   <a>RenderConfig</a> controls.
render :: Pretty v => RenderConfig -> KVITable v -> Text

-- | The <a>RenderConfig</a> specifies the various controls and
--   configurations used when rendering a <a>KVITable</a> in various
--   formats. The <a>RenderConfig</a> is global t oall formats, although
--   some of the fields in the <a>RenderConfig</a> will be ignored as
--   not-applicable by some formats.
data RenderConfig
RenderConfig :: Bool -> Bool -> Bool -> Bool -> Maybe Key -> Bool -> [Key] -> Maybe Text -> RenderConfig

-- | <a>True</a> (default) removes rows for which there are no values
[hideBlankRows] :: RenderConfig -> Bool

-- | <a>True</a> (default) removes columns for which there are no values
[hideBlankCols] :: RenderConfig -> Bool

-- | <a>True</a> (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

-- | <a>True</a> (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

-- | <a>True</a> (default) if an identical <a>KeyVal</a> 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 <tt>render</tt> call.
defaultRenderConfig :: RenderConfig


-- | This module provides the <a>KVITable</a> <a>render</a> 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
--   <a>RenderConfig</a> controls. The output is only the
--   <tt><a>table</a></tt> definition; it is intended to be embedded in a
--   larger HTML document.
render :: Pretty v => RenderConfig -> KVITable v -> Text

-- | The <a>RenderConfig</a> specifies the various controls and
--   configurations used when rendering a <a>KVITable</a> in various
--   formats. The <a>RenderConfig</a> is global t oall formats, although
--   some of the fields in the <a>RenderConfig</a> will be ignored as
--   not-applicable by some formats.
data RenderConfig
RenderConfig :: Bool -> Bool -> Bool -> Bool -> Maybe Key -> Bool -> [Key] -> Maybe Text -> RenderConfig

-- | <a>True</a> (default) removes rows for which there are no values
[hideBlankRows] :: RenderConfig -> Bool

-- | <a>True</a> (default) removes columns for which there are no values
[hideBlankCols] :: RenderConfig -> Bool

-- | <a>True</a> (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

-- | <a>True</a> (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

-- | <a>True</a> (default) if an identical <a>KeyVal</a> 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 <tt>render</tt> 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
