Data.CSV.Conduit.Conversion

This module has been shamelessly taken from Johan Tibell's nicely put together cassava package, which itself borrows the approach from Bryan OSullivans widely used aeson package.

We make the necessary adjustments and some simplifications here to bolt this parsing interface onto our underlying CSV typeclass.

Type conversion

newtype Only a

Haskell lacks a single-element tuple type, so if you CSV data with just one column you can use the Only type to represent a single-column result.

Constructors

Only

Fields

• fromOnly :: a

Instances

Eq a => Eq (Only a)

Defined in Data.CSV.Conduit.Conversion

Methods

(==) :: Only a -> Only a -> Bool

(/=) :: Only a -> Only a -> Bool

Ord a => Ord (Only a)

Defined in Data.CSV.Conduit.Conversion

Methods

compare :: Only a -> Only a -> Ordering

(<) :: Only a -> Only a -> Bool

(<=) :: Only a -> Only a -> Bool

(>) :: Only a -> Only a -> Bool

(>=) :: Only a -> Only a -> Bool

max :: Only a -> Only a -> Only a

min :: Only a -> Only a -> Only a

Read a => Read (Only a)

Defined in Data.CSV.Conduit.Conversion

Methods

readsPrec :: Int -> ReadS (Only a)

readList :: ReadS [Only a]

readPrec :: ReadPrec (Only a)

readListPrec :: ReadPrec [Only a]

Show a => Show (Only a)

Defined in Data.CSV.Conduit.Conversion

Methods

showsPrec :: Int -> Only a -> ShowS

show :: Only a -> String

showList :: [Only a] -> ShowS

ToField a => ToRecord (Only a)

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: Only a -> Record

FromField a => FromRecord (Only a)

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser (Only a)

newtype Named a

A wrapper around custom haskell types that can directly be converted/parsed from an incoming CSV stream.

We define this wrapper to stop GHC from complaining about overlapping instances. Just use getNamed to get your object out of the wrapper.

Constructors

Named

Fields

• getNamed :: a

Instances

(FromNamedRecord a, ToNamedRecord a, CSV s (MapRow ByteString)) => CSV s (Named a)

Conversion of stream directly to/from a custom complex haskell type.

Defined in Data.CSV.Conduit

Methods

rowToStr :: CSVSettings -> Named a -> s

intoCSV :: MonadThrow m => CSVSettings -> ConduitM s (Named a) m ()

fromCSV :: Monad m => CSVSettings -> ConduitM (Named a) s m ()

Eq a => Eq (Named a)

Defined in Data.CSV.Conduit.Conversion

Methods

(==) :: Named a -> Named a -> Bool

(/=) :: Named a -> Named a -> Bool

Ord a => Ord (Named a)

Defined in Data.CSV.Conduit.Conversion

Methods

compare :: Named a -> Named a -> Ordering

(<) :: Named a -> Named a -> Bool

(<=) :: Named a -> Named a -> Bool

(>) :: Named a -> Named a -> Bool

(>=) :: Named a -> Named a -> Bool

max :: Named a -> Named a -> Named a

min :: Named a -> Named a -> Named a

Read a => Read (Named a)

Defined in Data.CSV.Conduit.Conversion

Methods

readsPrec :: Int -> ReadS (Named a)

readList :: ReadS [Named a]

readPrec :: ReadPrec (Named a)

readListPrec :: ReadPrec [Named a]

Show a => Show (Named a)

Defined in Data.CSV.Conduit.Conversion

Methods

showsPrec :: Int -> Named a -> ShowS

show :: Named a -> String

showList :: [Named a] -> ShowS

type Record = Vector ByteString

A record corresponds to a single line in a CSV file.

type NamedRecord = Map ByteString ByteString

A shorthand for the ByteString case of MapRow

class FromRecord a where

A type that can be converted from a single CSV record, with the possibility of failure.

When writing an instance, use empty, mzero, or fail to make a conversion fail, e.g. if a Record has the wrong number of columns.

Given this example data:

John,56
Jane,55

here's an example type and instance:

data Person = Person { name :: !Text, age :: !Int }

instance FromRecord Person where
    parseRecord v
        | length v == 2 = Person <$>
                          v .! 0 <*>
                          v .! 1
        | otherwise     = mzero

Minimal complete definition

Nothing

Methods

parseRecord :: Record -> Parser a

parseRecord :: (Generic a, GFromRecord (Rep a)) => Record -> Parser a

Instances

FromField a => FromRecord [a]

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser [a]

(FromField a, Unbox a) => FromRecord (Vector a)

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser (Vector a)

FromField a => FromRecord (Vector a)

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser (Vector a)

FromField a => FromRecord (Only a)

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser (Only a)

(FromField a, FromField b) => FromRecord (a, b)

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser (a, b)

(FromField a, FromField b, FromField c) => FromRecord (a, b, c)

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser (a, b, c)

(FromField a, FromField b, FromField c, FromField d) => FromRecord (a, b, c, d)

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser (a, b, c, d)

(FromField a, FromField b, FromField c, FromField d, FromField e) => FromRecord (a, b, c, d, e)

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser (a, b, c, d, e)

(FromField a, FromField b, FromField c, FromField d, FromField e, FromField f) => FromRecord (a, b, c, d, e, f)

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser (a, b, c, d, e, f)

(FromField a, FromField b, FromField c, FromField d, FromField e, FromField f, FromField g) => FromRecord (a, b, c, d, e, f, g)

Defined in Data.CSV.Conduit.Conversion

Methods

parseRecord :: Record -> Parser (a, b, c, d, e, f, g)

class FromNamedRecord a where

A type that can be converted from a single CSV record, with the possibility of failure.

When writing an instance, use empty, mzero, or fail to make a conversion fail, e.g. if a Record has the wrong number of columns.

Given this example data:

name,age
John,56
Jane,55

here's an example type and instance:

{-# LANGUAGE OverloadedStrings #-}

data Person = Person { name :: !Text, age :: !Int }

instance FromNamedRecord Person where
    parseNamedRecord m = Person <$>
                         m .: "name" <*>
                         m .: "age"

Note the use of the OverloadedStrings language extension which enables ByteString values to be written as string literals.

Minimal complete definition

Nothing

Methods

parseNamedRecord :: NamedRecord -> Parser a

parseNamedRecord :: (Generic a, GFromNamedRecord (Rep a)) => NamedRecord -> Parser a

Instances

FromField a => FromNamedRecord (Map ByteString a)

Defined in Data.CSV.Conduit.Conversion

Methods

parseNamedRecord :: NamedRecord -> Parser (Map ByteString a)

class ToNamedRecord a where

A type that can be converted to a single CSV record.

An example type and instance:

data Person = Person { name :: !Text, age :: !Int }

instance ToNamedRecord Person where
    toNamedRecord (Person name age) = namedRecord [
        "name" .= name, "age" .= age]

Minimal complete definition

Nothing

Methods

toNamedRecord :: a -> NamedRecord

toNamedRecord :: (Generic a, GToRecord (Rep a) (ByteString, ByteString)) => a -> NamedRecord

Instances

ToField a => ToNamedRecord (Map ByteString a)

Defined in Data.CSV.Conduit.Conversion

Methods

toNamedRecord :: Map ByteString a -> NamedRecord

class FromField a where

A type that can be converted from a single CSV field, with the possibility of failure.

When writing an instance, use empty, mzero, or fail to make a conversion fail, e.g. if a Field can't be converted to the given type.

Example type and instance:

{-# LANGUAGE OverloadedStrings #-}

data Color = Red | Green | Blue

instance FromField Color where
    parseField s
        | s == "R"  = pure Red
        | s == "G"  = pure Green
        | s == "B"  = pure Blue
        | otherwise = mzero

Methods

parseField :: Field -> Parser a

Instances

FromField Char

Assumes UTF-8 encoding.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Char

FromField Double

Accepts same syntax as rational.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Double

FromField Float

Accepts same syntax as rational.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Float

FromField Int

Accepts a signed decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Int

FromField Int8

Accepts a signed decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Int8

FromField Int16

Accepts a signed decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Int16

FromField Int32

Accepts a signed decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Int32

FromField Int64

Accepts a signed decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Int64

FromField Integer

Accepts a signed decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Integer

FromField Word

Accepts an unsigned decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Word

FromField Word8

Accepts an unsigned decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Word8

FromField Word16

Accepts an unsigned decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Word16

FromField Word32

Accepts an unsigned decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Word32

FromField Word64

Accepts an unsigned decimal number.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Word64

FromField ()

Ignores the Field. Always succeeds.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser ()

FromField ByteString

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser ByteString

FromField ByteString

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser ByteString

FromField Text

Assumes UTF-8 encoding. Fails on invalid byte sequences.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Text

FromField Text

Assumes UTF-8 encoding. Fails on invalid byte sequences.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser Text

FromField [Char]

Assumes UTF-8 encoding. Fails on invalid byte sequences.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser [Char]

FromField a => FromField (Maybe a)

Nothing if the Field is empty, Just otherwise.

Defined in Data.CSV.Conduit.Conversion

Methods

parseField :: Field -> Parser (Maybe a)

class ToRecord a where

A type that can be converted to a single CSV record.

An example type and instance:

data Person = Person { name :: !Text, age :: !Int }

instance ToRecord Person where
    toRecord (Person name age) = record [
        toField name, toField age]

Outputs data on this form:

John,56
Jane,55

Minimal complete definition

Nothing

Methods

toRecord :: a -> Record

toRecord :: (Generic a, GToRecord (Rep a) Field) => a -> Record

Instances

ToField a => ToRecord [a]

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: [a] -> Record

(ToField a, Unbox a) => ToRecord (Vector a)

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: Vector a -> Record

ToField a => ToRecord (Vector a)

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: Vector a -> Record

ToField a => ToRecord (Only a)

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: Only a -> Record

(ToField a, ToField b) => ToRecord (a, b)

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: (a, b) -> Record

(ToField a, ToField b, ToField c) => ToRecord (a, b, c)

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: (a, b, c) -> Record

(ToField a, ToField b, ToField c, ToField d) => ToRecord (a, b, c, d)

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: (a, b, c, d) -> Record

(ToField a, ToField b, ToField c, ToField d, ToField e) => ToRecord (a, b, c, d, e)

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: (a, b, c, d, e) -> Record

(ToField a, ToField b, ToField c, ToField d, ToField e, ToField f) => ToRecord (a, b, c, d, e, f)

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: (a, b, c, d, e, f) -> Record

(ToField a, ToField b, ToField c, ToField d, ToField e, ToField f, ToField g) => ToRecord (a, b, c, d, e, f, g)

Defined in Data.CSV.Conduit.Conversion

Methods

toRecord :: (a, b, c, d, e, f, g) -> Record

class ToField a where

A type that can be converted to a single CSV field.

Example type and instance:

{-# LANGUAGE OverloadedStrings #-}

data Color = Red | Green | Blue

instance ToField Color where
    toField Red   = "R"
    toField Green = "G"
    toField Blue  = "B"

Methods

toField :: a -> Field

Instances

ToField Char

Uses UTF-8 encoding.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Char -> Field

ToField Double

Uses decimal notation or scientific notation, depending on the number.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Double -> Field

ToField Float

Uses decimal notation or scientific notation, depending on the number.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Float -> Field

ToField Int

Uses decimal encoding with optional sign.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Int -> Field

ToField Int8

Uses decimal encoding with optional sign.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Int8 -> Field

ToField Int16

Uses decimal encoding with optional sign.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Int16 -> Field

ToField Int32

Uses decimal encoding with optional sign.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Int32 -> Field

ToField Int64

Uses decimal encoding with optional sign.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Int64 -> Field

ToField Integer

Uses decimal encoding with optional sign.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Integer -> Field

ToField Word

Uses decimal encoding.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Word -> Field

ToField Word8

Uses decimal encoding.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Word8 -> Field

ToField Word16

Uses decimal encoding.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Word16 -> Field

ToField Word32

Uses decimal encoding.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Word32 -> Field

ToField Word64

Uses decimal encoding.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Word64 -> Field

ToField ByteString

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: ByteString -> Field

ToField ByteString

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: ByteString -> Field

ToField Text

Uses UTF-8 encoding.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Text -> Field

ToField Text

Uses UTF-8 encoding.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Text -> Field

ToField [Char]

Uses UTF-8 encoding.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: [Char] -> Field

ToField a => ToField (Maybe a)

Nothing is encoded as an empty field.

Defined in Data.CSV.Conduit.Conversion

Methods

toField :: Maybe a -> Field

type Field = ByteString

A single field within a record.

Parser

data Parser a

Conversion of a field to a value might fail e.g. if the field is malformed. This possibility is captured by the Parser type, which lets you compose several field conversions together in such a way that if any of them fail, the whole record conversion fails.

Instances

Monad Parser

Defined in Data.CSV.Conduit.Conversion

Methods

(>>=) :: Parser a -> (a -> Parser b) -> Parser b

(>>) :: Parser a -> Parser b -> Parser b

return :: a -> Parser a

fail :: String -> Parser a

Functor Parser

Defined in Data.CSV.Conduit.Conversion

Methods

fmap :: (a -> b) -> Parser a -> Parser b

(<$) :: a -> Parser b -> Parser a

Applicative Parser

Defined in Data.CSV.Conduit.Conversion

Methods

pure :: a -> Parser a

(<*>) :: Parser (a -> b) -> Parser a -> Parser b

liftA2 :: (a -> b -> c) -> Parser a -> Parser b -> Parser c

(*>) :: Parser a -> Parser b -> Parser b

(<*) :: Parser a -> Parser b -> Parser a

Alternative Parser

Defined in Data.CSV.Conduit.Conversion

Methods

empty :: Parser a

(<|>) :: Parser a -> Parser a -> Parser a

some :: Parser a -> Parser [a]

many :: Parser a -> Parser [a]

MonadPlus Parser

Defined in Data.CSV.Conduit.Conversion

Methods

mzero :: Parser a

mplus :: Parser a -> Parser a -> Parser a

Semigroup (Parser a)

Defined in Data.CSV.Conduit.Conversion

Methods

(<>) :: Parser a -> Parser a -> Parser a

sconcat :: NonEmpty (Parser a) -> Parser a

stimes :: Integral b => b -> Parser a -> Parser a

runParser :: Parser a -> Either String a

Run a Parser, returning either Left errMsg or Right result. Forces the value in the Left or Right constructors to weak head normal form.

You most likely won't need to use this function directly, but it's included for completeness.

Accessors

index :: FromField a => Record -> Int -> Parser a

Retrieve the nth field in the given record. The result is empty if the value cannot be converted to the desired type. Raises an exception if the index is out of bounds.

index is a simple convenience function that is equivalent to parseField (v ! idx). If you're certain that the index is not out of bounds, using unsafeIndex is somewhat faster.

(.!) :: FromField a => Record -> Int -> Parser a infixl 9

Alias for index.

unsafeIndex :: FromField a => Record -> Int -> Parser a

Like index but without bounds checking.

lookup :: FromField a => NamedRecord -> ByteString -> Parser a

Retrieve a field in the given record by name. The result is empty if the field is missing or if the value cannot be converted to the desired type.

(.:) :: FromField a => NamedRecord -> ByteString -> Parser a

Alias for lookup.

namedField :: ToField a => ByteString -> a -> (ByteString, ByteString)

Construct a pair from a name and a value. For use with namedRecord.

(.=) :: ToField a => ByteString -> a -> (ByteString, ByteString)

Alias for namedField.

record :: [ByteString] -> Record

Construct a record from a list of ByteStrings. Use toField to convert values to ByteStrings for use with record.

namedRecord :: [(ByteString, ByteString)] -> NamedRecord

Construct a named record from a list of name-value ByteString pairs. Use .= to construct such a pair from a name and a value.