Frames.CSV

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.

Documentation

type Separator = Text

type QuoteChar = Char

data QuotingMode

Constructors

NoQuoting

No quoting enabled. The separator may not appear in values

RFC4180Quoting QuoteChar

Quoted values with the given quoting character. Quotes are escaped by doubling them. Mostly RFC4180 compliant, except doesn't support newlines in values

Instances

Eq QuotingMode

Methods

(==) :: QuotingMode -> QuotingMode -> Bool

(/=) :: QuotingMode -> QuotingMode -> Bool

Show QuotingMode

Methods

showsPrec :: Int -> QuotingMode -> ShowS

show :: QuotingMode -> String

showList :: [QuotingMode] -> ShowS

Lift QuotingMode

Methods

lift :: QuotingMode -> Q Exp

data ParserOptions

Constructors

ParserOptions

Fields

• headerOverride :: Maybe [Text]
• columnSeparator :: Separator
• quotingMode :: QuotingMode

Instances

Eq ParserOptions

Methods

(==) :: ParserOptions -> ParserOptions -> Bool

(/=) :: ParserOptions -> ParserOptions -> Bool

Show ParserOptions

Methods

showsPrec :: Int -> ParserOptions -> ShowS

show :: ParserOptions -> String

showList :: [ParserOptions] -> ShowS

Lift ParserOptions

Methods

lift :: ParserOptions -> Q Exp

defaultParser :: ParserOptions

Default ParseOptions get column names from a header line, and use commas to separate columns.

defaultSep :: Separator

Default separator string.

Parsing

tokenizeRow :: ParserOptions -> Text -> [Text]

Helper to split a Text on commas and strip leading and trailing whitespace from each resulting chunk.

reassembleRFC4180QuotedParts :: Separator -> QuoteChar -> [Text] -> [Text]

Post processing applied to a list of tokens split by the separator which should have quoted sections reassembeld

prefixInference :: (ColumnTypeable a, Monoid a) => ParserOptions -> Handle -> IO [a]

Infer column types from a prefix (up to 1000 lines) of a CSV file.

readColHeaders :: (ColumnTypeable a, Monoid a) => ParserOptions -> FilePath -> IO [(Text, a)]

Extract column names and inferred types from a CSV file.

Loading Data

class ReadRec rs where

Parsing each component of a RecF from a list of text chunks, one chunk per record component.

Minimal complete definition

readRec

Methods

readRec :: [Text] -> Rec Maybe rs

Instances

ReadRec ([] *)

Methods

readRec :: [Text] -> Rec * Maybe [*]

(Parseable t, ReadRec ts) => ReadRec ((:) * ((:->) s t) ts)

Methods

readRec :: [Text] -> Rec * Maybe ((* ': (s :-> t)) ts)

readRow :: ReadRec rs => ParserOptions -> Text -> Rec Maybe rs

Read a RecF from one line of CSV.

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 ()

Produce rows where any given entry can fail to parse.

readTableOpt' :: forall m rs. (MonadPlus m, MonadIO m, ReadRec rs) => ParserOptions -> FilePath -> m (Record rs)

Returns a MonadPlus producer of rows for which each column was successfully parsed. This is typically slower than readTableOpt.

readTable' :: forall m rs. (MonadPlus m, MonadIO m, ReadRec rs) => FilePath -> m (Record rs)

Returns a MonadPlus producer of rows for which each column was successfully parsed. This is typically slower than readTable.

readTableOpt :: forall m rs. (MonadIO m, ReadRec rs) => ParserOptions -> FilePath -> Producer (Record rs) m ()

Returns a producer of rows for which each column was successfully parsed.

readTable :: forall m rs. (MonadIO m, ReadRec rs) => FilePath -> Producer (Record rs) m ()

Returns a producer of rows for which each column was successfully parsed.

Template Haskell

recDec :: [(Text, Q Type)] -> Q Type

Generate a column type.

sanitizeTypeName :: Text -> Text

Massage a column name from a CSV file into a valid Haskell type identifier.

mkColTDec :: TypeQ -> Name -> DecQ

Declare a type synonym for a column.

mkColPDec :: Name -> TypeQ -> Text -> DecsQ

Declare a singleton value of the given column type and lenses for working with that column.

lowerHead :: Text -> Maybe Text

colDec :: ColumnTypeable a => Text -> Text -> a -> DecsQ

For each column, we declare a type synonym for its type, and a Proxy value of that type.

declareColumn :: Text -> Name -> DecsQ

Splice for manually declaring a column of a given type. For example, declareColumn "x2" ''Double will declare a type synonym type X2 = "x2" :-> Double and a lens x2.

Default CSV Parsing

data RowGen a

Control how row and named column types are generated.

Constructors

RowGen

Fields

• columnNames :: [String]

  Use these column names. If empty, expect a header row in the data file to provide column names.

• tablePrefix :: String

  A common prefix to use for every generated declaration.

• separator :: Separator

  The string that separates the columns on a row.

• rowTypeName :: String

  The row type that enumerates all columns.

• columnUniverse :: Proxy a

  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 colQ.

colQ :: Name -> Q Exp

Shorthand for a Proxy value of ColumnUniverse applied to the given type list.

rowGen :: RowGen Columns

A default RowGen. 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 Columns set of types, and produce a row type with name Row.

tableType :: String -> FilePath -> DecsQ

Generate a type for each row of a table. This will be something like Record ["x" :-> a, "y" :-> b, "z" :-> c].

tableTypes :: String -> FilePath -> DecsQ

Like tableType, 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 type Foo = "foo" :-> Int, for example, foo = rlens (Proxy :: Proxy Foo), and foo' = rlens' (Proxy :: Proxy Foo).

Customized Data Set Parsing

tableType' :: forall a. (ColumnTypeable a, Monoid a) => RowGen a -> FilePath -> DecsQ

Generate a type for a row of a table. This will be something like Record ["x" :-> a, "y" :-> b, "z" :-> c]. Column type synonyms are not generated (see tableTypes').

tableTypesText' :: forall a. (ColumnTypeable a, Monoid a) => RowGen a -> FilePath -> DecsQ

Generate a type for a row of a table all of whose columns remain unparsed Text values.

tableTypes' :: forall a. (ColumnTypeable a, Monoid a) => RowGen a -> FilePath -> DecsQ

Like tableType', 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 type Foo = "foo" :-> Int, for example, foo = rlens (Proxy :: Proxy Foo), and foo' = rlens' (Proxy :: Proxy Foo).

Writing CSV Data

produceCSV :: forall f ts m. (ColumnHeaders ts, AsVinyl ts, Foldable f, Monad m, RecAll Identity (UnColumn ts) Show) => f (Record ts) -> Producer String m ()

yield a header row with column names followed by a line of text for each Record with each field separated by a comma.

writeCSV :: (ColumnHeaders ts, AsVinyl ts, Foldable f, RecAll Identity (UnColumn ts) Show) => FilePath -> f (Record ts) -> IO ()

Write a header row with column names followed by a line of text for each Record to the given file.