-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Data frames For working with tabular data files
--   
@package Frames
@version 0.1.2

module Frames.ColumnTypeable
data Parsed a
Possibly :: a -> Parsed a
Definitely :: a -> Parsed a

-- | Values that can be read from a <a>Text</a> with more or less
--   discrimination.
class Parseable a where parse = fmap Definitely . fromText
parse :: (Parseable a, Functor m, MonadPlus m) => Text -> m (Parsed a)

-- | Discard any estimate of a parse's ambiguity.
discardConfidence :: Parsed a -> a

-- | Acts just like <a>fromText</a>: tries to parse a value from a
--   <a>Text</a> and discards any estimate of the parse's ambiguity.
parse' :: (Functor m, MonadPlus m, Parseable a) => Text -> m a

-- | This class relates a universe of possible column types to Haskell
--   types, and provides a mechanism to infer which type best represents
--   some textual data.
class ColumnTypeable a
colType :: ColumnTypeable a => a -> Q Type
inferType :: ColumnTypeable a => Text -> a
instance Eq a => Eq (Parsed a)
instance Ord a => Ord (Parsed a)
instance Show a => Show (Parsed a)
instance Parseable Text
instance Parseable Double
instance Parseable Float
instance Parseable Int
instance Parseable Bool
instance Functor Parsed


-- | Helpers for working with type-level lists.
module Frames.TypeLevel

-- | Remove the first occurence of a type from a type-level list.

-- | A constraint on each element of a type-level list.

-- | Constraint that every element of a promoted list is equal to a
--   particular type. That is, the list of types is a single type repeated
--   some number of times.

-- | Compound constraint that a type has an instance for each of a list of
--   type classes.

-- | Compound constraint that all types have instances for each of a list
--   of type clasesses. <tt>AllHave classes types</tt>.


-- | Column types
module Frames.Col

-- | A column's type includes a textual name and the data type of each
--   element.
newtype (:->) (s :: Symbol) a
Col :: a -> (:->) a
getCol :: (:->) a -> a

-- | Used only for a show instance that parenthesizes the value.
newtype Col' s a
Col' :: (s :-> a) -> Col' s a

-- | Helper for making a <a>Col'</a>
col' :: a -> Col' s a
instance Eq a => Eq (s :-> a)
instance Ord a => Ord (s :-> a)
instance Num a => Num (s :-> a)
instance Monoid a => Monoid (s :-> a)
instance Real a => Real (s :-> a)
instance RealFloat a => RealFloat (s :-> a)
instance RealFrac a => RealFrac (s :-> a)
instance Fractional a => Fractional (s :-> a)
instance Floating a => Floating (s :-> a)
instance (KnownSymbol s, Show a) => Show (Col' s a)
instance (KnownSymbol s, Show a) => Show (s :-> a)

module Frames.RecF

-- | Two records may be pasted together.
rappend :: Rec k f as -> Rec k f bs -> Rec k f ((++) k as bs)

-- | A record may be traversed with respect to its interpretation functor.
--   This can be used to yank (some or all) effects from the fields of the
--   record to the outside of the record.
rtraverse :: Applicative h => (forall (x :: k). f x -> h (g x)) -> Rec k f rs -> h (Rec k g rs)

-- | Delete a field from a record
rdel :: CanDelete r rs => proxy r -> Rec f rs -> Rec f (RDelete r rs)

-- | A constraint that a field can be deleted from a record.
type CanDelete r rs = (RElem r rs (RIndex r rs), RDelete r rs ⊆ rs)

-- | Add a column to the head of a row.
frameCons :: Functor f => f a -> Rec f rs -> Rec f ((s :-> a) : rs)

-- | Add a pure column to the head of a row.
frameConsA :: Applicative f => a -> Rec f rs -> Rec f ((s :-> a) : rs)

-- | Add a column to the tail of a row. Note that the supplied value should
--   be a <a>Col</a> to work with the <tt>Frames</tt> tooling.
frameSnoc :: Rec f rs -> f r -> Rec f (rs ++ '[r])

-- | Enforce a constraint on the payload type of each column.
type AllCols c ts = LAll c (UnColumn ts)

-- | Strip the column information from each element of a list of types.

-- | Remove the column name phantom types from a record, leaving you with
--   an unadorned Vinyl <a>Rec</a>.
class AsVinyl ts
toVinyl :: (AsVinyl ts, Functor f) => Rec f ts -> Rec f (UnColumn ts)
fromVinyl :: (AsVinyl ts, Functor f) => Rec f (UnColumn ts) -> Rec f ts

-- | Map a function across a homogeneous, monomorphic <a>Rec</a>.
mapMono :: (AllAre a (UnColumn ts), Functor f, AsVinyl ts) => (a -> a) -> Rec f ts -> Rec f ts

-- | Map a typeclass method across a <a>Rec</a> each of whose fields has an
--   instance of the typeclass.
mapMethod :: (Functor f, LAll c (UnColumn ts), AsVinyl ts) => Proxy c -> (forall a. c a => a -> a) -> Rec f ts -> Rec f ts

-- | The ability to pretty print a <tt>Rec'</tt>s fields.
class Functor f => ShowRec f rs

-- | Pretty printing of <a>Rec</a> values.
showRec :: ShowRec f rs => Rec f rs -> String

-- | A type function to convert a <tt>Record</tt> to a <a>Rec</a>.
--   <tt>ColFun f (Rec rs) = Rec f rs</tt>.
class ColumnHeaders (cs :: [*])
columnHeaders :: ColumnHeaders cs => proxy (Rec f cs) -> [String]

-- | Build a record whose elements are derived solely from a constraint
--   satisfied by each.
reifyDict :: (LAll c ts, RecApplicative ts) => proxy c -> (forall a. c a => f a) -> Rec f ts
instance (KnownSymbol s, Show (f (Col' s a)), ShowRec f rs) => ShowRec f ((s :-> a) : rs)
instance Functor f => ShowRec f '[]
instance AsVinyl ts => AsVinyl ((s :-> t) : ts)
instance AsVinyl '[]
instance (ColumnHeaders cs, KnownSymbol s) => ColumnHeaders ((s :-> c) : cs)
instance ColumnHeaders '[]


-- | Co-records: a flexible approach to sum types.
module Frames.CoRec

-- | Generalize algebraic sum types.
data CoRec :: (* -> *) -> [*] -> *
Col :: !(f a) -> CoRec f ts

-- | A Field of a <tt>Record</tt> is a 'CoRec Identity'.
type Field = CoRec Identity

-- | Helper to build a <a>Show</a>-able <a>CoRec</a>
col :: (Show a, a ∈ ts) => a -> CoRec (Dict Show) ts

-- | A function type constructor that takes its arguments in the reverse
--   order.
newtype Op b a
Op :: (a -> b) -> Op b a
runOp :: Op b a -> a -> b

-- | Remove a <a>Dict</a> wrapper from a value.
dictId :: Dict c a -> Identity a

-- | Helper to build a <tt>Dict Show</tt>
showDict :: Show a => a -> Dict Show a

-- | We can inject a a <a>CoRec</a> into a <a>Rec</a> where every field of
--   the <a>Rec</a> is <a>Nothing</a> except for the one whose type
--   corresponds to the type of the given <a>CoRec</a> variant.
corecToRec :: RecApplicative ts => CoRec f ts -> Rec (Maybe :. f) ts

-- | Shorthand for applying <a>corecToRec</a> with common functors.
corecToRec' :: RecApplicative ts => CoRec Identity ts -> Rec Maybe ts

-- | Fold a field selection function over a <a>Rec</a>.
class FoldRec ss ts
foldRec :: FoldRec ss ts => (CoRec f ss -> CoRec f ss -> CoRec f ss) -> CoRec f ss -> Rec f ts -> CoRec f ss

-- | Apply a natural transformation to a variant.
corecMap :: (forall x. f x -> g x) -> CoRec f ts -> CoRec g ts

-- | This can be used to pull effects out of a <a>CoRec</a>.
corecTraverse :: Functor h => (forall x. f x -> h (g x)) -> CoRec f ts -> h (CoRec g ts)

-- | Fold a field selection function over a non-empty <a>Rec</a>.
foldRec1 :: FoldRec (t : ts) ts => (CoRec f (t : ts) -> CoRec f (t : ts) -> CoRec f (t : ts)) -> Rec f (t : ts) -> CoRec f (t : ts)

-- | Similar to <a>First</a>: find the first field that is not
--   <a>Nothing</a>.
firstField :: FoldRec ts ts => Rec (Maybe :. f) ts -> Maybe (CoRec f ts)

-- | Similar to <a>Last</a>: find the last field that is not
--   <a>Nothing</a>.
lastField :: FoldRec ts ts => Rec (Maybe :. f) ts -> Maybe (CoRec f ts)

-- | Apply a type class method on a <a>CoRec</a>. The first argument is a
--   <a>Proxy</a> value for a <i>list</i> of <a>Constraint</a>
--   constructors. For example, <tt>onCoRec [pr|Num,Ord|] (&gt; 20) r</tt>.
--   If only one constraint is needed, use the <tt>pr1</tt> quasiquoter.
onCoRec :: (AllHave cs ts, Functor f, RecApplicative ts) => Proxy cs -> (forall a. HasInstances a cs => a -> b) -> CoRec f ts -> f b

-- | Apply a type class method on a <a>Field</a>. The first argument is a
--   <a>Proxy</a> value for a <i>list</i> of <a>Constraint</a>
--   constructors. For example, <tt>onCoRec [pr|Num,Ord|] (&gt; 20) r</tt>.
--   If only one constraint is needed, use the <tt>pr1</tt> quasiquoter.
onField :: (AllHave cs ts, RecApplicative ts) => Proxy cs -> (forall a. HasInstances a cs => a -> b) -> Field ts -> b

-- | Build a record whose elements are derived solely from a list of
--   constraint constructors satisfied by each.
reifyDicts :: (AllHave cs ts, RecApplicative ts) => proxy cs -> (forall a. HasInstances a cs => f a) -> Rec f ts

-- | Given a proxy of type t and a 'CoRec Identity' that might be a t, try
--   to convert the CoRec to a t.
asA :: (t ∈ ts, RecApplicative ts) => proxy t -> CoRec Identity ts -> Maybe t

-- | Pattern match on a CoRec by specifying handlers for each case. If the
--   CoRec is non-empty this function is total. Note that the order of the
--   Handlers has to match the type level list (t:ts).
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let testCoRec = Col (Identity False) :: CoRec Identity [Int, String, Bool] in
--   match testCoRec $
--         (H $ \i -&gt; "my Int is the successor of " ++ show (i - 1))
--      :&amp; (H $ \s -&gt; "my String is: " ++ s)
--      :&amp; (H $ \b -&gt; "my Bool is not: " ++ show (not b) ++ " thus it is " ++ show b)
--      :&amp; RNil
--   :}
--   "my Bool is not: True thus it is False"
--   </pre>
match :: RecApplicative (t : ts) => CoRec Identity (t : ts) -> Handlers (t : ts) b -> b

-- | Pattern match on a CoRec by specifying handlers for each case. The
--   only case in which this can produce a Nothing is if the list ts is
--   empty.
match' :: RecApplicative ts => CoRec Identity ts -> Handlers ts b -> Maybe b

-- | Newtype around functions for a to b
newtype Handler b a
H :: (a -> b) -> Handler b a

-- | 'Handlers ts b', is essentially a list of functions, one for each type
--   in ts. All functions produce a value of type <tt>b</tt>. Hence,
--   'Handlers ts b' would represent something like the type-level list: [t
--   -&gt; b | t in ts ]
type Handlers ts b = Rec (Handler b) ts
instance (t ∈ ss, FoldRec ss ts) => FoldRec ss (t : ts)
instance FoldRec ss '[]
instance (LAll Show ts, RecApplicative ts) => Show (CoRec Identity ts)
instance Show (CoRec (Dict Show) ts)

module Frames.ColumnUniverse

-- | Generalize algebraic sum types.
data CoRec :: (* -> *) -> [*] -> *

-- | A universe of common column variants.
type Columns = ColumnUniverse CommonColumns

-- | Define a set of variants that captures all possible column types.
type ColumnUniverse = CoRec ColInfo

-- | Common column types
type CommonColumns = '[Bool, Int, Double, Text]
instance (LAll Parseable ts, LAll Typeable ts, FoldRec ts ts, RecApplicative ts, Text ∈ ts) => ColumnTypeable (CoRec ColInfo ts)
instance Text ∈ ts => Monoid (CoRec ColInfo ts)

module Frames.Rec

-- | A record with unadorned values.
type Record = Rec Identity

-- | A <tt>cons</tt> function for building <a>Record</a> values.
(&:) :: a -> Record rs -> Record ((s :-> a) : rs)

-- | Separate the first element of a <a>Record</a> from the rest of the
--   row.
recUncons :: Record ((s :-> a) : rs) -> (a, Record rs)

-- | Undistribute <a>Maybe</a> from a <a>Rec</a> <a>Maybe</a>. This is just
--   a specific usage of <a>rtraverse</a>, but it is quite common.
recMaybe :: Rec Maybe cs -> Maybe (Record cs)

-- | Show each field of a <a>Record</a> <i>without</i> its column name.
showFields :: (RecAll Identity (UnColumn ts) Show, AsVinyl ts) => Record ts -> [String]


-- | Functions useful for interactively exploring and experimenting with a
--   data set.
module Frames.Exploration

-- | <tt>preview src n f</tt> prints out the first <tt>n</tt> results of
--   piping <tt>src</tt> through <tt>f</tt>.
pipePreview :: (MonadIO m, Show b) => Producer a m () -> Int -> Pipe a b m () -> m ()

-- | <tt>select (Proxy::Proxy [A,B,C])</tt> extracts columns <tt>A</tt>,
--   <tt>B</tt>, and <tt>C</tt>, from a larger record. Note, this is just a
--   way of pinning down the type of a usage of <a>rcast</a>.
select :: fs ⊆ rs => proxy fs -> Record rs -> Record fs

-- | <tt>lenses (Proxy::Proxy [A,B,C])</tt> provides a lens onto columns
--   <tt>A</tt>, <tt>B</tt>, and <tt>C</tt>. This is just a way of pinning
--   down the type of <a>rsubset</a>.
lenses :: (fs ⊆ rs, Functor f) => proxy fs -> (Record fs -> f (Record fs)) -> Record rs -> f (Record rs)
recToList :: (AsVinyl rs, AllAre a (UnColumn rs)) => Record rs -> [a]

-- | A proxy value quasiquoter. <tt>[pr|T|]</tt> will splice an expression
--   <tt>Proxy::Proxy T</tt>, while <tt>[pr|A,B,C|]</tt> will splice in a
--   value of <tt>Proxy :: Proxy [A,B,C]</tt>.
pr :: QuasiQuoter

-- | Like <a>pr</a>, but takes a single type, which is used to produce a
--   <a>Proxy</a> for a single-element list containing only that type. This
--   is useful for passing a single type to a function that wants a list of
--   types.
pr1 :: QuasiQuoter


-- | A <a>Frame</a> is a finite <a>Int</a>-indexed collection of rows.
module Frames.Frame

-- | A <a>Frame</a> is a finite collection of rows indexed by <a>Int</a>.
data Frame r
Frame :: !Int -> (Int -> r) -> Frame r
frameLength :: Frame r -> !Int
frameRow :: Frame r -> Int -> r

-- | A <a>Frame</a> whose rows are <a>Record</a> values.
type FrameRec rs = Frame (Record rs)

-- | Build a <a>Frame</a> from any <a>Foldable</a>. This simply uses a
--   boxed <a>Vector</a> to hold each row. If you have a collection of
--   <a>Record</a>s, consider using <a>toFrame</a>.
boxedFrame :: Foldable f => f r -> Frame r

-- | The <a>Monoid</a> instance for <a>Frame</a> provides a mechanism for
--   vertical concatenation of <a>Frame</a>s. That is, <tt>f1 &lt;&gt;
--   f2</tt> will return a new <a>Frame</a> with the rows of <tt>f1</tt>
--   followed by the rows of <tt>f2</tt>.

-- | Horizontal <a>Frame</a> concatenation. That is, <tt>zipFrames f1
--   f2</tt> will return a <a>Frame</a> with as many rows as the smaller of
--   <tt>f1</tt> and <tt>f2</tt> whose rows are the result of appending the
--   columns of <tt>f2</tt> to those of <tt>f1</tt>.
zipFrames :: FrameRec rs -> FrameRec rs' -> FrameRec (rs ++ rs')
instance Monad Frame
instance Applicative Frame
instance Foldable Frame
instance Monoid (Frame r)
instance Functor Frame


-- | Efficient in-memory (in-core) storage of tabular data.
module Frames.InCore

-- | The most efficient vector type for each column data type.

-- | The mutable version of <a>VectorFor</a> a particular type.
type VectorMFor a = Mutable (VectorFor a)

-- | Since we stream into the in-memory representation, we use an
--   exponential growth strategy to resize arrays as more data is read in.
--   This is the initial capacity of each column.
initialCapacity :: Int

-- | Mutable vector types for each column in a row.

-- | Immutable vector types for each column in a row.

-- | Tooling to allocate, grow, write to, freeze, and index into records of
--   vectors.
class RecVec rs
allocRec :: (RecVec rs, Applicative m, PrimMonad m) => proxy rs -> m (Record (VectorMs m rs))
freezeRec :: (RecVec rs, Applicative m, PrimMonad m) => proxy rs -> Int -> Record (VectorMs m rs) -> m (Record (Vectors rs))
growRec :: (RecVec rs, Applicative m, PrimMonad m) => proxy rs -> Record (VectorMs m rs) -> m (Record (VectorMs m rs))
writeRec :: (RecVec rs, PrimMonad m) => proxy rs -> Int -> Record (VectorMs m rs) -> Record rs -> m ()
indexRec :: RecVec rs => proxy rs -> Int -> Record (Vectors rs) -> Record rs
produceRec :: RecVec rs => proxy rs -> Record (Vectors rs) -> Rec ((->) Int) rs

-- | Stream a finite sequence of rows into an efficient in-memory
--   representation for further manipulation. Each column of the input
--   table will be stored optimally based on its type, making use of the
--   resulting generators a matter of indexing into a densely packed
--   representation. Returns the number of rows and a record of column
--   indexing functions. See <a>toAoS</a> to convert the result to a
--   <a>Frame</a> which provides an easier-to-use function that indexes
--   into the table in a row-major fashion.
inCoreSoA :: (Applicative m, PrimMonad m, RecVec rs) => Producer (Record rs) m () -> m (Int, Rec ((->) Int) rs)

-- | Stream a finite sequence of rows into an efficient in-memory
--   representation for further manipulation. Each column of the input
--   table will be stored optimally based on its type, making use of the
--   resulting generators a matter of indexing into a densely packed
--   representation. Returns a <a>Frame</a> that provides a function to
--   index into the table.
inCoreAoS :: (Applicative m, PrimMonad m, RecVec rs) => Producer (Record rs) m () -> m (FrameRec rs)

-- | Like <a>inCoreAoS</a>, but applies the provided function to the record
--   of columns before building the <a>Frame</a>.
inCoreAoS' :: (Applicative m, PrimMonad m, RecVec rs) => (Rec ((->) Int) rs -> Rec ((->) Int) ss) -> Producer (Record rs) m () -> m (FrameRec ss)

-- | Convert a structure-of-arrays to an array-of-structures. This can
--   simplify usage of an in-memory representation.
toAoS :: Int -> Rec ((->) Int) rs -> FrameRec rs

-- | Stream a finite sequence of rows into an efficient in-memory
--   representation for further manipulation. Each column of the input
--   table will be stored optimally based on its type, making use of the
--   resulting generator a matter of indexing into a densely packed
--   representation.
inCore :: (Applicative m, PrimMonad m, RecVec rs, Monad n) => Producer (Record rs) m () -> m (Producer (Record rs) n ())

-- | Build a <a>Frame</a> from a collection of <a>Record</a>s using
--   efficient column-based storage.
toFrame :: (Foldable f, RecVec rs) => f (Record rs) -> Frame (Record rs)

-- | Keep only those rows of a <a>FrameRec</a> that satisfy a predicate.
filterFrame :: RecVec rs => (Record rs -> Bool) -> FrameRec rs -> FrameRec rs
instance (MVector (VectorMFor a) a, Mutable (VectorFor a) ~ VectorMFor a, Vector (VectorFor a) a, RecVec rs) => RecVec ((s :-> a) : rs)
instance RecVec '[]

module Frames.Melt
type ElemOf ts r = RElem r ts (RIndex r ts)
class RowToColumn ts rs
rowToColumnAux :: RowToColumn ts rs => Proxy ts -> Rec f rs -> [CoRec f ts]

-- | Transform a record into a list of its fields, retaining proof that
--   each field is part of the whole.
rowToColumn :: RowToColumn ts ts => Rec f ts -> [CoRec f ts]
meltAux :: (vs ⊆ ts, ss ⊆ ts, Disjoint ss ts ~ True, ts ≅ (vs ++ ss), ColumnHeaders vs, RowToColumn vs vs) => Record ts -> [Record (("value" :-> CoRec Identity vs) : ss)]

-- | This is <a>melt</a>, but the variables are at the front of the record,
--   which reads a bit odd.
meltRow' :: (vs ⊆ ts, ss ⊆ ts, vs ~ RDeleteAll ss ts, Disjoint ss ts ~ True, ts ≅ (vs ++ ss), ColumnHeaders vs, RowToColumn vs vs) => proxy ss -> Record ts -> [Record (("value" :-> CoRec Identity vs) : ss)]

-- | Turn a cons into a snoc after the fact.
retroSnoc :: Record (t : ts) -> Record (ts ++ '[t])

-- | Like <tt>melt</tt> in the <tt>reshape2</tt> package for the <tt>R</tt>
--   language. It stacks multiple columns into a single column over
--   multiple rows. Takes a specification of the id columns that remain
--   unchanged. The remaining columns will be stacked.
--   
--   Suppose we have a record, <tt>r :: Record [Name,Age,Weight]</tt>. If
--   we apply <tt>melt [pr1|Name|] r</tt>, we get two values with type
--   <tt>Record [Name, "value" :-&gt; CoRec Identity [Age,Weight]]</tt>.
--   The first will contain <tt>Age</tt> in the <tt>value</tt> column, and
--   the second will contain <tt>Weight</tt> in the <tt>value</tt> column.
meltRow :: (vs ⊆ ts, ss ⊆ ts, vs ~ RDeleteAll ss ts, Disjoint ss ts ~ True, ts ≅ (vs ++ ss), ColumnHeaders vs, RowToColumn vs vs) => proxy ss -> Record ts -> [Record (ss ++ '["value" :-> CoRec Identity vs])]
class HasLength (ts :: [k])
hasLength :: HasLength ts => proxy ts -> Int

-- | Applies <a>meltRow</a> to each row of a <a>FrameRec</a>.
melt :: (vs ⊆ ts, ss ⊆ ts, vs ~ RDeleteAll ss ts, HasLength vs, Disjoint ss ts ~ True, ts ≅ (vs ++ ss), ColumnHeaders vs, RowToColumn vs vs) => proxy ss -> FrameRec ts -> FrameRec (ss ++ '["value" :-> CoRec Identity vs])
instance HasLength ts => HasLength (t : ts)
instance HasLength '[]
instance (r ∈ ts, RowToColumn ts rs) => RowToColumn ts (r : rs)
instance RowToColumn ts '[]


-- | Lens utilities for working with <a>Record</a>s.
module Frames.RecLens
rlens' :: (i ~ RIndex r rs, RElem r rs i, Functor f, Functor g) => sing r -> (g r -> f (g r)) -> Rec g rs -> f (Rec g rs)

-- | Getter for a <a>Rec</a> field
rget' :: Functor g => (forall f. Functor f => (g (s :-> a) -> f (g (s :-> a))) -> Rec g rs -> f (Rec g rs)) -> Rec g rs -> g a

-- | Setter for a <a>Rec</a> field.
rput' :: Functor g => (forall f. Functor f => (g (s :-> a) -> f (g (s :-> a))) -> Rec g rs -> f (Rec g rs)) -> g a -> Rec g rs -> Rec g rs

-- | Create a lens for accessing a field of a <a>Record</a>.
rlens :: (Functor f, RElem (s :-> a) rs (RIndex (s :-> a) rs)) => proxy (s :-> a) -> (a -> f a) -> Record rs -> f (Record rs)

-- | Getter for a <a>Record</a> field.
rget :: (forall f. Functor f => (a -> f a) -> Record rs -> f (Record rs)) -> Record rs -> a

-- | Setter for a <a>Record</a> field.
rput :: (forall f. Functor f => (a -> f a) -> Record rs -> f (Record rs)) -> a -> Record rs -> Record rs


-- | Infer row types from comma-separated values (CSV) data and read that
--   data from files. Template Haskell is used to generate the necessary
--   types so that you can write type safe programs referring to those
--   types.
module Frames.CSV
type Separator = Text
type QuoteChar = Char
data QuotingMode

-- | No quoting enabled. The separator may not appear in values
NoQuoting :: QuotingMode

-- | Quoted values with the given quoting character. Quotes are escaped by
--   doubling them. Mostly RFC4180 compliant, except doesn't support
--   newlines in values
RFC4180Quoting :: QuoteChar -> QuotingMode
data ParserOptions
ParserOptions :: Maybe [Text] -> Separator -> QuotingMode -> ParserOptions
headerOverride :: ParserOptions -> Maybe [Text]
columnSeparator :: ParserOptions -> Separator
quotingMode :: ParserOptions -> QuotingMode

-- | Default <tt>ParseOptions</tt> get column names from a header line, and
--   use commas to separate columns.
defaultParser :: ParserOptions

-- | Default separator string.
defaultSep :: Separator

-- | Helper to split a <a>Text</a> on commas and strip leading and trailing
--   whitespace from each resulting chunk.
tokenizeRow :: ParserOptions -> Text -> [Text]

-- | Post processing applied to a list of tokens split by the separator
--   which should have quoted sections reassembeld
reassembleRFC4180QuotedParts :: Separator -> QuoteChar -> [Text] -> [Text]

-- | Infer column types from a prefix (up to 1000 lines) of a CSV file.
prefixInference :: (ColumnTypeable a, Monoid a) => ParserOptions -> Handle -> IO [a]

-- | Extract column names and inferred types from a CSV file.
readColHeaders :: (ColumnTypeable a, Monoid a) => ParserOptions -> FilePath -> IO [(Text, a)]

-- | Parsing each component of a <tt>RecF</tt> from a list of text chunks,
--   one chunk per record component.
class ReadRec (rs :: [*])
readRec :: ReadRec rs => [Text] -> Rec Maybe rs

-- | Read a <tt>RecF</tt> from one line of CSV.
readRow :: ReadRec rs => ParserOptions -> Text -> Rec Maybe rs

-- | Produce rows where any given entry can fail to parse.
readTableMaybeOpt :: (MonadIO m, ReadRec rs) => ParserOptions -> FilePath -> Producer (Rec Maybe rs) m ()

-- | Produce rows where any given entry can fail to parse.
readTableMaybe :: (MonadIO m, ReadRec rs) => FilePath -> Producer (Rec Maybe rs) m ()

-- | Returns a <a>MonadPlus</a> producer of rows for which each column was
--   successfully parsed. This is typically slower than
--   <a>readTableOpt</a>.
readTableOpt' :: (MonadPlus m, MonadIO m, ReadRec rs) => ParserOptions -> FilePath -> m (Record rs)

-- | Returns a <a>MonadPlus</a> producer of rows for which each column was
--   successfully parsed. This is typically slower than <a>readTable</a>.
readTable' :: (MonadPlus m, MonadIO m, ReadRec rs) => FilePath -> m (Record rs)

-- | Returns a producer of rows for which each column was successfully
--   parsed.
readTableOpt :: (MonadIO m, ReadRec rs) => ParserOptions -> FilePath -> Producer (Record rs) m ()

-- | Returns a producer of rows for which each column was successfully
--   parsed.
readTable :: (MonadIO m, ReadRec rs) => FilePath -> Producer (Record rs) m ()

-- | Generate a column type.
recDec :: ColumnTypeable a => [(Text, a)] -> Q Type

-- | Massage a column name from a CSV file into a valid Haskell type
--   identifier.
sanitizeTypeName :: Text -> Text

-- | Declare a type synonym for a column.
mkColTDec :: TypeQ -> Name -> DecQ

-- | Declare a singleton value of the given column type.
mkColPDec :: Name -> TypeQ -> Text -> DecsQ

-- | For each column, we declare a type synonym for its type, and a Proxy
--   value of that type.
colDec :: ColumnTypeable a => Text -> Text -> a -> DecsQ

-- | Splice for manually declaring a column of a given type. For example,
--   <tt>declareColumn "x2" ''Double</tt> will declare a type synonym
--   <tt>type X2 = "x2" :-&gt; Double</tt> and a lens <tt>x2</tt>.
declareColumn :: Text -> Name -> DecsQ

-- | Control how row and named column types are generated.
data RowGen a
RowGen :: [String] -> String -> Separator -> String -> Proxy a -> RowGen a

-- | Use these column names. If empty, expect a header row in the data file
--   to provide column names.
columnNames :: RowGen a -> [String]

-- | A common prefix to use for every generated declaration.
tablePrefix :: RowGen a -> String

-- | The string that separates the columns on a row.
separator :: RowGen a -> Separator

-- | The row type that enumerates all columns.
rowTypeName :: RowGen a -> String

-- | A type that identifies all the types that can be used to classify a
--   column. This is essentially a type-level list of types. See
--   <a>colQ</a>.
columnUniverse :: RowGen a -> Proxy a

-- | Shorthand for a <a>Proxy</a> value of <a>ColumnUniverse</a> applied to
--   the given type list.
colQ :: Name -> Q Exp

-- | A default <a>RowGen</a>. This instructs the type inference engine to
--   get column names from the data file, use the default column separator
--   (a comma), infer column types from the default <a>Columns</a> set of
--   types, and produce a row type with name <tt>Row</tt>.
rowGen :: RowGen Columns

-- | Generate a type for each row of a table. This will be something like
--   <tt>Record ["x" :-&gt; a, "y" :-&gt; b, "z" :-&gt; c]</tt>.
tableType :: String -> FilePath -> DecsQ

-- | Like <a>tableType</a>, but additionally generates a type synonym for
--   each column, and a proxy value of that type. If the CSV file has
--   column names "foo", "bar", and "baz", then this will declare <tt>type
--   Foo = "foo" :-&gt; Int</tt>, for example, <tt>foo = rlens (Proxy ::
--   Proxy Foo)</tt>, and <tt>foo' = rlens' (Proxy :: Proxy Foo)</tt>.
tableTypes :: String -> FilePath -> DecsQ

-- | Generate a type for a row a table. This will be something like
--   <tt>Record ["x" :-&gt; a, "y" :-&gt; b, "z" :-&gt; c]</tt>. Column
--   type synonyms are <i>not</i> generated (see <a>tableTypes'</a>).
tableType' :: (ColumnTypeable a, Monoid a) => RowGen a -> FilePath -> DecsQ

-- | Like <a>tableType'</a>, but additionally generates a type synonym for
--   each column, and a proxy value of that type. If the CSV file has
--   column names "foo", "bar", and "baz", then this will declare <tt>type
--   Foo = "foo" :-&gt; Int</tt>, for example, <tt>foo = rlens (Proxy ::
--   Proxy Foo)</tt>, and <tt>foo' = rlens' (Proxy :: Proxy Foo)</tt>.
tableTypes' :: (ColumnTypeable a, Monoid a) => RowGen a -> FilePath -> DecsQ
instance Eq QuotingMode
instance Show QuotingMode
instance Eq ParserOptions
instance Show ParserOptions
instance (Parseable t, ReadRec ts) => ReadRec ((s :-> t) : ts)
instance ReadRec '[]
instance Lift ParserOptions
instance Lift QuotingMode


-- | User-friendly, type safe, runtime efficient tooling for working with
--   tabular data deserialized from comma-separated values (CSV) files. The
--   type of each row of data is inferred from data, which can then be
--   streamed from disk, or worked with in memory.
module Frames

-- | A space efficient, packed, unboxed Unicode text type.
data Text :: *